Logo of AppSignal

Menu
Docs navigation

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.

Table of Contents

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.

For more information also read our blog post about Custom markers.

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. "master".
revision String Git revision reference. Used to create git diff links in the UI.
user String User that has initiated the deploy.

Payload example

1
2
3
4
5
6
7
8
9
{
  "marker": {
    "kind": "deploy",
    "created_at": "2015-07-21T15:06:31.737+02:00",
    "repository": "git@github.com:company/repository.git",
    "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
    "user": "user"
  }
}

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.
message String - Optional Message shown when hovering over the marker in the UI. Truncated to 200 characters.

Payload example

1
2
3
4
5
6
7
8
{
  "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "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.

1
2
3
{
  "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "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

1
2
3
4
5
6
{
  "kind": "custom",
  "icon": "πŸ’©",
  "message": "Accidentlly dropped production DB",
  "created_at": "2015-07-21T15:06:31.737+02:00"
}

Notification marker

1
2
3
4
5
{
  "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.