Chart Annotations

Annotations mark specific moments on your charts — deployments, incidents, config changes, feature releases — so your team can immediately correlate "what changed" with "what broke". Uptrace displays annotations as square dots on the time axis of any chart.

Clicking an annotation dot opens a popover with its name, description (supports Markdown and links to external systems), and any tags attached to it.

Common use cases

Deployment markers — post an annotation after every kubectl apply, helm upgrade, or CI/CD deploy step
Feature flags — mark when a feature is enabled or rolled back in production
Incidents — record incident start and end times and link to your runbook or postmortem
Config changes — annotate firewall rule changes, database tuning, and scaling events
Canary releases — track when a canary is promoted or rolled back

Creating annotations

Send a POST request to the Uptrace API from any step in your deployment pipeline:

shell

curl -X POST https://api.uptrace.dev/api/v1/annotations \
  -H 'uptrace-dsn: <your-dsn>' \
  -d '{"name":"Deployed v1.2.3", "attrs": {"service.version": "v1.2.3"}}'

Use fingerprint to prevent duplicate annotations when a pipeline retries:

shell

curl -X POST https://api.uptrace.dev/api/v1/annotations \
  -H 'uptrace-dsn: <your-dsn>' \
  -d '{
    "name": "Deployed v1.2.3",
    "fingerprint": "deploy-v1.2.3",
    "color": "green",
    "attrs": {
      "deployment.environment": "production",
      "service.version": "v1.2.3"
    }
  }'

Fields

Field	Required	Description
`name`	yes	Annotation label shown on the chart
`description`	no	Markdown text shown in the popover. Supports links to runbooks, PRs, etc.
`color`	no	Dot color: named color (`green`, `red`, `orange`) or hex (`#00ff00`)
`attrs`	no	Key-value metadata (e.g. `{"deployment.environment": "production"}`)
`fingerprint`	no	Deduplication key — duplicate annotations with the same fingerprint are ignored
`time`	no	Override annotation timestamp in RFC 3339 format. Defaults to request time.

CI/CD integration

GitHub Actions

yaml

- name: Annotate deployment
  run: |
    curl -sX POST https://api.uptrace.dev/api/v1/annotations \
      -H "uptrace-dsn: ${{ secrets.UPTRACE_DSN }}" \
      -d "{
        \"name\": \"Deployed ${{ github.sha }}\",
        \"fingerprint\": \"deploy-${{ github.sha }}\",
        \"color\": \"green\",
        \"description\": \"[View commit](https://github.com/${{ github.repository }}/commit/${{ github.sha }})\",
        \"attrs\": {
          \"service.version\": \"${{ github.sha }}\",
          \"deployment.environment\": \"production\"
        }
      }"

GitLab CI

yaml

annotate:
  stage: deploy
  script:
    - |
      curl -sX POST https://api.uptrace.dev/api/v1/annotations \
        -H "uptrace-dsn: ${UPTRACE_DSN}" \
        -d "{
          \"name\": \"Deployed ${CI_COMMIT_SHORT_SHA}\",
          \"fingerprint\": \"deploy-${CI_COMMIT_SHORT_SHA}\",
          \"color\": \"green\",
          \"attrs\": {\"service.version\": \"${CI_COMMIT_SHORT_SHA}\"}
        }"

Shell script (post-deploy hook)

bash

#!/bin/bash
set -euo pipefail

VERSION=$(git rev-parse --short HEAD)
curl -sX POST https://api.uptrace.dev/api/v1/annotations \
  -H "uptrace-dsn: ${UPTRACE_DSN}" \
  -d "{
    \"name\": \"Deployed ${VERSION}\",
    \"fingerprint\": \"deploy-${VERSION}\",
    \"color\": \"green\"
  }"

Metric monitors — alert when a metric crosses a threshold after a deployment
Dashboards — annotations are visible on all dashboard charts
Observability as Code — manage annotations alongside your full infrastructure config