Events
This guide provides an overview of the event tracking system in OpsChain.
After following this guide you should know:
- how events are handled in OpsChain
- which events are created by OpsChain automatically
- how to query events via the API
- how to create custom events using the API
All the examples in this guide assume the OpsChain API server is running on your local machine. Replace <host> with your OpsChain server name if connecting to a remote OpsChain server.
Overview
Any API request that modifies data in OpsChain will be tracked for auditing and reporting purposes, this includes creating and updating data, interacting with activities and more. In future versions, OpsChain will track more events, please let us know if there are particular events you would like tracked.
OpsChain does not track API requests to the api/events API itself.
The data provided within the attributes section of the event API response varies depending on the type of event, but it contains more detailed information about the event context.
All automatically created API events start with the api: prefix and are then followed by the API controller, and then the API method. When a failure occurs, OpsChain will create an event with the error: prefix.
System created events
Events created internally by OpsChain can be identified by the system property. If system is true then the event was created by OpsChain, if it is false then the event was created by a user using the api/events endpoint - the username field identifies the user that initiated the request.
Further down we present a list of the event types created by OpsChain.
Viewing events
You can view events in the OpsChain web UI by navigating to the audit history page.
On the API, the OpsChain api/events endpoint can be queried to see events in the OpsChain system.
curl -u "{{username}}:{{password}}" http://<host>/api/events
The response is a JSON:API payload containing a list of the most recent events. The response will include the relevant events from oldest to newest in the response data array, i.e. data[0] will be the oldest event in the result set.
Example change start event
Below is an example of a change start event returned by the api/events endpoint.
{
"id": "43404b06-e265-4d4e-a387-4fc83320a778",
"type": "event",
"attributes": {
"username": "opschain",
"system": true,
"type": "api:changes:start",
"created_at": "2021-01-01T01:00:00.000000Z"
},
"relationships": {
"source": {
"links": {
"source": "/api/projects/hello_world/changes/d57edfd7-7536-40fc-9c5b-9492faa0a6fd"
}
}
},
"links": {
"self": "/api/events/43404b06-e265-4d4e-a387-4fc83320a778"
}
}
Filtering events on the API
The query to the api/events endpoint can be filtered by providing the relevant query parameters.
For example, the following query will return up to 100 events that were created after 2021-01-01.
By default, the response is limited to only 10 events, and there is a hard limit of 1000 events. The response status code will be 206 Partial Content when the response has been truncated by the limit.
curl --globoff --user "{{username}}:{{password}}" 'http://<host>/api/events?filter[created_at_gt]=2021-01-01T01:00:00.000000Z&limit=100'
The --globoff argument is required when using the filtering queries using curl.
Filtering examples with the API
The API filtering and sorting guide includes a variety of examples that highlight OpsChain's filtering feature and how it can be used to find specific events.
More complex examples using the event API endpoint
Below are some more complex examples of querying the api/events API.
The examples require the jq and curl utilities, and have been tested with Zsh and Bash 4.
Waiting for an event to occur
The following is an example of watching the events API waiting for a change start event to occur.
user='{{username}}:{{password}}'
since="$(date --iso-8601=ns)"
event='api:changes:start'
while true; do
response="$(curl -s -G --user "${user}" http://<host>/api/events --data-urlencode "filter[created_at_gt]=${since}" --data-urlencode "filter[type_eq]=${event}")"
if jq -e '.data | length > 0' <<<"${response}" >/dev/null; then
echo "${response}"
break
fi
sleep 1
done
Don't forget to add --data-urlencode "filter[system_true]=yes" if you wish to wait for a system event.
Paginating through events
The following is an example of paginating backwards through the events API. It will output the newest event to the oldest.
user='{{username}}:{{password}}'
while true; do
response="$(curl -s -G --user "${user}" http://<host>/api/events --data-urlencode "filter[created_at_lt]=${before}")"
before="$(jq -r '.data[0].attributes.created_at // empty' <<<"${response}")"
if [[ -z "${before}" ]]; then
break
fi
jq '.data | reverse[]' <<<"${response}"
done
Creating custom events
Events can be created in the OpsChain events framework by sending a POST request to the api/events endpoint.
The request needs to be a valid JSON:API request. E.g.
curl --fail --user {{username}}:{{password}} http://<host>/api/events -H 'content-type: application/vnd.api+json' -d '{ "data": { "type": "Event", "attributes": { "type": "custom", "some": "value", "nesting": { "also": "works" } } } }'
curl --fail --user {{username}}:{{password}} http://<host>/api/events -H 'content-type: application/vnd.api+json' -d @event-file.json
OpsChain responds with a 201 status code and no response body when the event is created successfully.
Linking events
Events can be linked to data within OpsChain. Below is an example of linking a project with the path /projects/bank (this is the same as a project with the code bank) to a custom event.
curl --fail --user {{username}}:{{password}} http://<host>/api/events -H 'content-type: application/vnd.api+json' -d '{ "data": { "type": "Event", "attributes": { "type": "linked:to:project:example", "project_path": "/projects/bank" } } }'
Events can be linked to:
- Projects via a path or an ID, e.g.
"project_path": "/projects/bank", or"node_path": "/projects/bank", or"project_id": "ff1bf781-4fe0-4b14-b0d2-20ef8cb1be80" - Environments via a path or an ID, e.g.
"node_path": "/projects/bank/environments/dev", or"node_id": "969a2b4c-a700-40d2-a25c-1f4f68cf6d54" - Assets via a path or an ID, e.g.
"node_path": "/projects/bank/environments/dev/assets/obp", or"node_id": "2f988308-325d-4a41-bdab-4cf0b8c3103a" - In addition, the following models can be linked via an ID, (e.g.
"{{model_type_id}}": "ff1bf781-4fe0-4b14-b0d2-20ef8cb1be80"):- Scheduled changes (via
scheduled_change_id) - Changes (via
change_id) - Steps (via
step_id) - Workflow steps (via
workflow_step_id) - Workflow runs (via
workflow_run_id) - Bookmarks (via
bookmark_id) - Templates (via
template_id) - Template versions (via
template_version_id) - Git remotes (via
git_remote_id) - Properties (via
properties_id) - Properties versions (via
properties_version_id) - Settings (via
settings_id) - Settings versions (via
settings_version_id)
- Scheduled changes (via
System event types
Currently, the following system events are supported. These values will be present in the type field for an event:
api:authorisation_policies:createapi:authorisation_policies:destroyapi:authorisation_policies:updateapi:authorisation_rules:createapi:authorisation_rules:destroyapi:authorisation_rules:updateapi:bookmarks:createapi:bookmarks:updateapi:bookmarks:destroyapi:changes:createapi:changes:startapi:changes:successapi:changes:errorapi:changes:cancelapi:changes:abortapi:changes:destroyapi:nodes:createapi:nodes:updateapi:nodes:destroyapi:git_remotes:createapi:git_remotes:updateapi:git_remotes:destroyapi:templates:createapi:templates:updateapi:template_versions:updateapi:policy_assignments:createapi:policy_assignments:destroyapi:policy_rules:createapi:policy_rules:destroyapi:projects:createapi:projects:updateapi:projects:destroyapi:properties:updateapi:scheduled_changes:createapi:scheduled_workflows:createapi:scheduled_changes:destroyapi:scheduled_workflows:destroyapi:secrets:encryptapi:secrets:resolveapi:settings:updateapi:steps:startapi:steps:approveapi:steps:approve:deniedapi:steps:continueapi:steps:successapi:steps:errorapi:steps:cancelapi:steps:abortapi:workflow_runs:createapi:workflow_runs:startapi:workflow_runs:successapi:workflow_runs:errorapi:workflow_runs:cancelapi:workflow_runs:abortapi:workflow_runs:destroyapi:workflow_steps:startapi:workflow_steps:successapi:workflow_steps:errorapi:workflow_steps:cancelapi:workflow_steps:abortapi:workflows:createapi:workflows:updateerror:data_cleanup:activitieserror:data_cleanup:eventserror:data_cleanup:jobserror:scheduled_changes:change_creationerror:scheduled_changes:git_shaerror:scheduled_workflows:skippedinfo:data_cleanup:activitiesinfo:data_cleanup:eventsinfo:data_cleanup:jobs
Custom (i.e. user created) events can have any type as it is specified when the event is created.
Removing events
Older OpsChain events can be removed to free up space, see the OpsChain data cleaning guide for more details.