Markers API
Markers are little icons used in graphs to indicate a change. This can be a deploy using a "Deploy marker" or a custom event with a "Custom marker".
This Marker endpoint allows the creation and indexing of markers that are available per application.
Marker types
Deploy markers
Deploy markers are little dots at the bottom of each graph that indicate when a new revision of an application was deployed. Theyβre a great way to compare deploys with each another and see if the new version increased or decreased application performance.
A list of these markers is also shown on the "Deploys" page on AppSignal.com, in an Application context.
Custom markers
Custom markers provide a way to add more context to graphs, allowing you to add annotations yourself. Create a Custom marker for scaling operations, when there was a sudden spike in traffic or when a database was acting up.
Marker create
This endpoint enables the creation of Deploy and Custom markers.
When creating the payload for this request you can select what type of marker
to create by specifying the kind
value.
Endpoint | /api/[app_id]/markers.json |
Request method | POST |
Context | Applications |
Requires authentication? | Yes |
Response formats | JSON |
Deploy marker
Parameter | Type | Description |
---|---|---|
kind | String | The kind of marker to be created - "deploy". |
created_at | Date - ISO 8601 | Time at which to insert the marker. Leave empty to use the current time. |
repository | String | Git link or reference, e.g. "main". |
revision | String | Git revision reference. Used to create git diff links in the UI. |
user | String | User that has initiated the deploy. |
Payload example
{ "marker": { "kind": "deploy", "created_at": "2015-07-21T15:06:31.737+02:00", "repository": "git@github.com:company/repository.git", "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af", "user": "user" } }
Payload example with curl
curl -H "Content-Type: application/json" -XPOST https://appsignal.com/api/[app-id]/markers.json?token=[your-personal-token] \ -d '{ "marker":{ "kind": "deploy", "repository": "git@github.com:company/repository.git", "revision": "[revision]", "user": "[user]"}}'
All requests to AppSignal API endpoints require a personal API token given as an URL query parameter for authentication.
Custom marker
Used to annotate events that can impact your performance/error rate. Examples are: up/downscale of cloud infrastructure, maintenance on database, cause of error spikes.
Parameter | Type | Description |
---|---|---|
kind | String | The kind of marker to be created - "custom". |
created_at | Date - ISO 8601 | Time at which to insert the marker. Leave empty to use the current time. |
icon | String - Optional | Emoji to use for this Custom marker, defaults to π. |
message | String - Optional | Message shown when hovering over the marker in the UI. Truncated to 200 characters. |
Payload example
{ "marker": { "kind": "custom", "created_at": "2015-07-21T15:06:31.737+02:00", "icon": "π©", "message": "Accidentlly dropped production DB" } }
Marker index
This endpoint returns a list of markers. Combines both Deploy and Custom markers.
Endpoint | /api/[app_id]/markers.json |
Request method | GET |
Context | Applications |
Requires authentication? | Yes |
Response formats | JSON |
Parameters
Parameter | Type | Description |
---|---|---|
kind | String | The kind of marker to be created - "custom". |
from | Date - ISO 8601 / Integer - UNIX timestamp | All times are UTC. |
to | Date - ISO 8601 / Integer - UNIX timestamp | All times are UTC. |
limit | Integer | Limit the number of markers returned. |
count_only | Boolean | Set to "true" to only return the number of markers that exist. |
Response
{ "count": 4212, "markers": [ { "kind": "deploy", "id": "50a61f1b660cd3677775ccb0", "created_at": "2015-07-21T15:06:31.737+02:00", "closed_at": null, "live_for": 107413, "live_for_in_words": "1d", "gem_version": null, "repository": "git@github.com:company/repository.git", "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af", "short_revision": "fe00101", "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb" "user": "user", "exception_count": 200, "exception_rate": 8.81 }, { "kind": "custom", "icon": "π©", "message": "Accidentlly dropped production DB", "created_at": "2015-07-21T15:06:31.737+02:00" }, { "kind": "notification", "message": "Appsignal API issues.", "created_at": "2015-07-21T15:06:31.737+02:00" } ] }
With "count_only": true
.
{ "count": 4212 }
Marker show
This endpoint returns the JSON representation of a single marker.
Endpoint | /api/[app_id]/markers/[marker_id].json |
Request method | GET |
Context | Applications |
Requires authentication? | Yes |
Response formats | JSON |
Parameters
Parameter | Type | Description |
---|---|---|
marker_id | String | The id of the marker to return. |
Response
The response for Deploy markers and Custom markers is different. Deploy markers contain more data about a certain deploy while Custom markers only contain the data given on creation.
Deploy marker
{ "id": "50a61f1b660cd3677775ccb0", "created_at": "2015-07-21T15:06:31.737+02:00", "closed_at": null, "live_for": 107413, "live_for_in_words": "1d", "gem_version": null, "repository": "git@github.com:company/repository.git", "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af", "short_revision": "fe00101", "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb" "user": "user", "exception_count": 200, "exception_rate": 8.81 }
Custom marker
{ "kind": "custom", "icon": "π©", "message": "Accidentlly dropped production DB", "created_at": "2015-07-21T15:06:31.737+02:00" }
Notification marker
{ "kind": "notification", "message": "Appsignal API issues.", "created_at": "2015-07-21T15:06:31.737+02:00" }
Marker update
This endpoint updates a single marker and returns the JSON representation of the updated marker.
Endpoint | /api/[app_id]/markers/[marker_id].json |
Request method | PUT |
Context | Applications |
Requires authentication? | Yes |
Response formats | JSON |
Parameters
Parameter | Type | Description |
---|---|---|
marker_id | String | The id of the marker to update. |
Payload
The payload is the same as a create/POST request and differs per marker type.
Response
The response is the same as a show/GET request and differs per marker type.
Marker delete
This endpoint deletes a single marker.
Endpoint | /api/[app_id]/markers/[marker_id].json |
Request method | DELETE |
Context | Applications |
Requires authentication? | Yes |
Response formats | JSON |
Parameters
Parameter | Type | Description |
---|---|---|
marker_id | String | The id of the marker to delete. |
Response
The response body of this request is empty. The status code will return if it was successful or not.