Events endpoints
Sections
Use the /events
endpoint to learn about events that occurred during an orchestrator
job.
GET /jobs/:job-id/events
Retrieve all of the events that occurred during a given job.
Parameters
The request accepts this query parameter:
Parameter | Definition |
---|---|
start
|
Start the list of events with the nth event. |
For example:
https://orchestrator.example.com:8143/orchestrator/v1/jobs/352/events?start=1272
Copied!
Response format
The response is a JSON object that details the events in a job, and uses these keys:
Key | Definition |
---|---|
next-events
|
A link to the next event in the job. |
items
|
A list of all events related to the job. |
id
|
The job ID. |
type
|
The current status of the event. See event-types. |
timestamp
|
The time when the event was created. |
details
|
Information about the event. |
message
|
A message about the given event. |
For example:
{
"next-events" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/352/events?start=1272"
},
"items" : [ {
"id" : "1267",
"type" : "node_running",
"timestamp" : "2016-05-05T19:50:08Z",
"details" : {
"node" : "puppet-agent.example.com",
"detail" : {
"noop" : false
}
},
"message" : "Started puppet run on puppet-agent.example.com ..."
}]
}
Copied!
Event types
The response format for each event contains one of these event types, which is determined by the status of the event.
Event type | Definition |
---|---|
node_errored
|
Created when there was an error running Puppet on a node. |
node_failed
|
Created when Puppet failed to run on a node. |
node_finished
|
Created when puppet ran successfully on a node. |
node_running
|
Created when Puppet starts running on a node. |
node_skipped
|
Created when a Puppet run is skipped on a node (for example, if a dependency fails). |
job_aborted
|
Created when a job is aborted without completing. |
job_stopping |
Created when a stop request is received and the job is running. |
job_finished |
Created when a job is no longer running. The details contain final state. This should always be the last event for a job. |
Error responses
For this endpoint, the kind
key of the error displays the conflict.
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error
|
If the start parameter or the
job-id in the request are not integers, the server returns a
400 response. |
puppetlabs.orchestrator/unknown-job
|
If the job does not exist, the server returns a
404 response. |
GET /plan_jobs/:job-id/events
Retrieve all of the events that occurred during a given plan job.
Parameters
Parameter | Definition |
---|---|
start |
The lowest database ID of an event that should be shown. |
For example:
https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/events?start=1272
Response format
The response is a JSON object that derails the events in a plan job. The following keys and their subkeys are used:
Key | Description |
---|---|
next-events |
A link to the next event in the job. |
id |
The url of the next event. |
event |
The next event id. |
Key | |
---|---|
items |
A list of all events related to the job. |
id |
The id of the event. |
type |
The type of event. See event-types . |
timestamp |
The time when the event was created. |
details |
Details of the event, differs based on the type of the event. See the potential values section for more detailed information. |
{
"next-events" : {
"id" : "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/events?start=1272",
"event": "1272"
},
"items" : [ {
"id" : "1267",
"type" : "task_start",
"timestamp" : "2016-05-05T19:50:08Z",
"details" : {
"job-id" : "8765"
}
},
{
"id" : "1268",
"type" : "plan_finished",
"timestamp" : "2016-05-05T19:50:14Z",
"details" : {
"plan-id" : "1234",
"result" : {
"Plan output"
},
},
}]
}
Copied!
Event types
Key | Description |
---|---|
task_start |
Created when a task run is started. |
script_start |
Created when a script run as part of a plan is started. |
command_start |
Created when a command run as part of a plan is started. |
upload_start |
Created when a file upload as part of a plan is started. |
wait_start |
Created when a wait_until_available() call as part of a plan
is started. |
out_message |
Created when out::message is called as part of a plan.
details will contain a message key with a
value containing the message sent with out::message truncated to
1,024 bytes. The full message content can be obtained using the GET /plan_jobs/:job-id/event/:event-id endpoint. |
apply_start |
Created when a puppet apply run as part of a plan is started. |
apply_prep_start |
Created when an apply_prep is run as part of
a plan is started. |
plan_finished |
Created when a plan job successfully finishes. |
plan_failed |
Created when a plan job fails. |
"Sub" plans
run_plan()
function it will begin execution of
another "sub" plan during the execution of the plan job. "Sub" plans will not receive their
own plan job, they will execute as part of the original plan job. There are specific events
for "sub" plans that indicate a plan within a plan has started or finished:Key | Definition |
---|---|
plan_start |
Created when a new plan was kicked off from the current plan job using the
run_plan() function. |
plan_end |
Created when a plan started using run_plan() has
finished.
Note:
plan_end indicates the end of a "sub" plan
(i.e. the plan job has not finished yet, but the "sub" plan has), while
plan_finished indicates the end of a plan job. |
Potential values in details
task and plan actions
task_start
, command_start
, apply_start
,
etc).{
"type" : "task_start",
"timestamp" : "2019-09-30T22:22:32Z",
"details" : {
"job-id" : 69
},
"id" : "80"
}
Copied!
plan_finished
or
plan_failed
plan_finished
or plan_failed
,
details will include plan-id
and result
.{
"type" : "plan_finished",
"timestamp" : "2019-09-30T22:22:33Z",
"details" : {
"result" : "plan result",
"plan-id" : "9"
},
"id" : "81"
}
Copied!
out_message
out_message
, details
will include
message
. {
"type" : "out_message",
"timestamp" : "2019-09-30T22:22:32Z",
"details" : {
"message" : "message sent from a plan"
}
}
Copied!
plan_start
or plan_end
If the event type is plan_start
or plan_end
,
details
will include the plan that ran (plan
) and
plan_end
will include duration
.
plan_start
:{
"type" : "plan_start",
"timestamp" : "2019-09-30T22:22:31Z",
"details" : {
"plan" : "test::sub_plan"
},
"id" : "76"
}
Copied!
plan_end
: {
"type" : "plan_end",
"timestamp" : "2019-09-30T22:22:32Z",
"details" : {
"plan" : "test::sub_plan",
"duration" : 0.647551
}
}
Copied!
Error responses
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error |
If the start parameter or the job-id in the
request are not integers, the server returns a 400
response. |
puppetlabs.orchestrator/unknown-job |
If the plan job does not exist, the server returns a 404
response. |
GET /plan_jobs/:job-id/event/:event-id
Fetch a specific event for a job.
Response format
Key | Definition |
---|---|
id |
ID of this event. |
type |
Event type. |
timestamp |
When the event occurred. |
details |
Hash of detail fields specific to the event type. |
/plan_jobs/:job-id/events
endpoint, no truncation
of fields occurs. {
"id": "1265",
"type": "out_message",
"timestamp": "2016-05-05T19:50:06Z",
"details": {
"message": "this is an output message"
}
}
Copied!
Error responses
Key | Definition |
---|---|
puppetlabs.orchestrator/validation-error |
If the job-id in the request is not an
integer, the server returns a 400
response. |
puppetlabs.orchestrator/unknown-job |
If the plan job does not exist, the server returns a
404 response. |
puppetlabs.orchestrator/mismatched-job-event-id |
If the event-id specified does not belong to
the job-id specified, the server returns a
404 response. |