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.

Deploy marker

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.

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

Response

The response body of this request is empty. The status code will return if it was successful or not.