Annotate dashboard elements

This page explains how to use annotations to add context to your dashboard elements.

Annotating charts lets you add context to your charts. For example, use annotations to mark the time of the following:

• Deployments
• Server outages
• Incidents
• Feature flags

This adds context to the trends displayed in your charts and makes it easier to investigate issues in your app or system.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.

• Send data to your Axiom dataset.
• Create an API token in Axiom with permissions to create, read, update, and delete annotations.

Create annotations

Create annotations in one of the following ways:

• Use a GitHub Action
• Send a request to the Axiom API

If you use the Axiom Vercel integration, annotations are automatically created for deployments.

Axiom automatically creates an annotation if a monitor triggers.

Create annotations with GitHub Actions

You can configure GitHub Actions using YAML syntax. For more information, see the GitHub documentation.

To create an annotation when a deployment happens in GitHub, follow these steps:

1. Add the following to the end of your GitHub Action file:

   - name: Add annotation in Axiom when a deployment happens
     uses: axiomhq/annotation-action@v0.1.0
     with:
       axiomToken: ${{ secrets.API_TOKEN }}
       datasets: DATASET_NAME
       type: "production-release"
       time: "2024-01-01T00:00:00Z"                                    # optional, defaults to now
       endTime: "2024-01-01T01:00:00Z"                                 # optional, defaults to null
       title: "Production deployment"                                  # optional
       description: "Commit ${{ github.event.head_commit.message }}"   # optional
       url: "https://example.com"                                      # optional, defaults to job URL
   

2. In the code above, replace the following:

   • Replace DATASET_NAME with the Axiom dataset where you want to send data. To add the annotation to more than one dataset, enter a string of Axiom dataset names separated by commas. For example axiom_datasets: 'DATASET_NAME_1, DATASET_NAME_2, DATASET_NAME_3'.
   • Replace API_TOKEN with your Axiom API token. Add this token to your secrets.

3. Customize the other fields of the code above such as the title, the description, and the URL.

This creates an annotation in Axiom each time you deploy in GitHub.

Create annotations using Axiom API

To create an annotation using the Axiom API, use the following API request:

curl -X 'POST' 'https://api.axiom.co/v2/annotations' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": "2024-03-18T08:39:28.382Z",
    "type": "deploy",
    "datasets": ["DATASET_NAME"],
    "title": "Production deployment",
    "description": "Deploy new feature to the sales form",
    "url": "https://example.com"
  }'

• In the code above, replace the following:
  • Replace DATASET_NAME with the Axiom dataset where you want to send data. To add the annotation to more than one dataset, enter a list of Axiom dataset names.
  • Replace API_TOKEN with your Axiom API token.
• Customize the other fields of the code above such as the title, the description, and the URL. For more information on the allowed fields, see Annotation object.

Example response:

{
  "datasets": ["my-dataset"],
  "description": "Deploy new feature to the sales form",
  "id": "ann_123",
  "time": "2024-03-18T08:39:28.382Z",
  "title": "Production deployment",
  "type": "deploy",
  "url": "https://example.com"
}

The API response from Axiom contains an id field. This is the annotation ID that you can later use to change or delete the annotation.

Get information about annotations

To get information about all datasets in your org, use the following API request:

curl -X 'GET' 'https://api.axiom.co/v2/annotations' \
  -H 'Authorization: Bearer API_TOKEN'

In the code above, replace API_TOKEN with your Axiom API token.

Use the following parameters in the endpoint URL to filter for a specific time interval and dataset:

• start is an ISO timestamp that specifies the beginning of the time interval.
• end is an ISO timestamp that specifies the end of the time interval.
• datasets is the list of datasets whose annotations you want to get information about. Separate datasets by commas, for example datasets=my-dataset1,my-dataset2.

The example below gets information about annotations about occurrences between March 16th and 19th, 2024 and added to the dataset my-dataset:

curl -X 'GET' 'https://api.axiom.co/v2/annotations?start=2024-03-16T00:00:00.000Z&end=2024-03-19T23:59:59.999Z&datasets=my-dataset' \
  -H 'Authorization: Bearer API_TOKEN'

Example response:

[
  {
    "datasets": ["my-dataset"],
    "description": "Deploy new feature to the navigation component",
    "id": "ann_234",
    "time": "2024-03-17T01:15:45.232Z",
    "title": "Production deployment",
    "type": "deploy",
    "url": "https://example.com"
  },
  {
    "datasets": ["my-dataset"],
    "description": "Deploy new feature to the sales form",
    "id": "ann_123",
    "time": "2024-03-18T08:39:28.382Z",
    "title": "Production deployment",
    "type": "deploy",
    "url": "https://example.com"
  }
]

The API response from Axiom contains an id field. This is the annotation ID that you can later use to change or delete the annotation. For more information on the other fields, see Annotation object.

To get information about a specific annotation, use the following API request:

curl -X 'GET' 'https://api.axiom.co/v2/annotations/ANNOTATION_ID' \
  -H 'Authorization: Bearer API_TOKEN'

In the code above, replace the following:

• Replace ANNOTATION_ID with the ID of the annotation.
• Replace API_TOKEN with your Axiom API token.

Example response:

{
  "datasets": ["my-dataset"],
  "description": "Deploy new feature to the sales form",
  "id": "ann_123",
  "time": "2024-03-18T08:39:28.382Z",
  "title": "Production deployment",
  "type": "deploy",
  "url": "https://example.com"
}

For more information on these fields, see Annotation object.

Change annotations

To change an existing annotation, use the following API request:

curl -X 'PUT' 'https://api.axiom.co/v2/annotations/ANNOTATION_ID' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "endTime": "2024-03-18T08:49:28.382Z"
  }'

• In the code above, replace the following:
  • Replace ANNOTATION_ID with the ID of the annotation. For more information about how to determine the annotation ID, see Get information about annotations.
  • Replace API_TOKEN with your Axiom API token.
• In the payload, specify the properties of the annotation that you want to change. The example above adds an endTime field to the annotation created above. For more information on the allowed fields, see Annotation object.

Example response:

{
  "datasets": ["my-dataset"],
  "description": "Deploy new feature to the sales form",
  "id": "ann_123",
  "time": "2024-03-18T08:39:28.382Z",
  "title": "Production deployment",
  "type": "deploy",
  "url": "https://example.com",
  "endTime": "2024-03-18T08:49:28.382Z"
}

Delete annotations

To delete an existing annotation, use the following API request:

curl -X 'DELETE' 'https://api.axiom.co/v2/annotations/ANNOTATION_ID' \
  -H 'Authorization: Bearer API_TOKEN' \

In the code above, replace the following:

• Replace ANNOTATION_ID with the ID of the annotation. For more information about how to determine the annotation ID, see Get information about annotations.
• Replace API_TOKEN with your Axiom API token.

Annotation object

Annotations are represented as objects with the following fields:

• datasets is the list of dataset names for which the annotation appears on charts.
• id is the unique ID of the annotation.
• description is an explanation of the event the annotation marks on the charts.
• time is an ISO timestamp value that specifies the time the annotation marks on the charts.
• title is a summary of the annotation that appears on the charts.
• type is the type of the event marked by the annotation. For example, production deployment.
• url is the URL relevant for the event marked by the annotation. For example, link to GitHub pull request.
• Optional: endTime is an ISO timestamp value that specifies the end time of the annotation.

Show and hide annotations on dashboards

To show and hide annotations on a dashboard, follow these steps:

1. Go to the dashboard where you see annotations. For example, the prebuilt Vercel dashboard automatically shows annotations about deployments.
2. Click Toggle annotations.
3. Select the datasets whose annotations you want to display on the charts.

Example use case

The example below demonstrates how annotations help you troubleshoot issues in your app or system. Your monitor alerts you about rising form submission errors. You explore this trend and when it started. Right before form submission errors started rising, you see an annotation about a deployment of a new feature to the form. You make the hypothesis that the deployment is the reason for the error and decide to investigate the code changes it introduced.

Create annotation

Use the following API request to create an annotation:

curl -X 'POST' 'https://api.axiom.co/v2/annotations' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "time": "2024-03-18T08:39:28.382Z",
    "type": "deploy",
    "datasets": ["my-dataset"],
    "title": "Production deployment",
    "description": "Deploy new feature to the sales form",
    "url": "https://example.com"
  }'

In the code above, replace API_TOKEN with your Axiom API token.

Create a monitor

In this example, you set up a monitor that alerts you when the number of form submission errors rises. For more information on creating a monitor, see Monitoring and Notifiers.

Explore trends

Suppose your monitor sends you a notification about rising form submission errors.

You decide to investigate and run a query to display the number of form submission errors over time. Ensure you select a time range that includes the annotation.

You get a chart similar to the example below displaying form submission errors and annotations about the time of important events such as deployments.

Example histogram with annotation

Inspect issue

1. From the chart, you see that the number of errors started to rise after the deployment of a new feature to the sales form. This correlation allows you to form the hypothesis that the errors might be caused by the deployment.
2. You decide to investigate the deployment by clicking on the link associated with the annotation. The link takes you to the GitHub pull request.
3. You inspect the code changes in depth and discover the cause of the errors.
4. You quickly fix the issue in another deployment.