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:
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:
-
Add the following to the end of your GitHub Action file:
-
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 exampleaxiom_datasets: 'DATASET_NAME_1, DATASET_NAME_2, DATASET_NAME_3'
. - Replace
API_TOKEN
with your Axiom API token. Add this token to your secrets.
- Replace
-
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:
- 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.
- Replace
- 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:
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:
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 exampledatasets=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
:
Example response:
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:
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:
For more information on these fields, see Annotation object.
Change annotations
To change an existing annotation, use the following API request:
- 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.
- Replace
- 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:
Delete annotations
To delete an existing annotation, use the following API request:
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:
- Go to the dashboard where you see annotations. For example, the prebuilt Vercel dashboard automatically shows annotations about deployments.
- Click Toggle annotations.
- 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:
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
- 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.
- You decide to investigate the deployment by clicking on the link associated with the annotation. The link takes you to the GitHub pull request.
- You inspect the code changes in depth and discover the cause of the errors.
- You quickly fix the issue in another deployment.