Skip to content

Deploy markers & annotations

An Axiom Annotation is a vertical marker overlaid on every chart that queries the datasets it names — a deploy, an incident, a feature-flag flip, correlated with your telemetry at a glance. In alchemy it’s one resource: declare it next to the services it annotates, and each stage gets its own markers.

You’ll need the Axiom provider registered (setup) and a dataset to annotate (ingest).

Drop a point marker

Section titled “Drop a point marker”
import * as Axiom from "alchemy/Axiom";


yield* Axiom.Annotation("release-1.2.3", {
  type: "deploy",
  title: "Release 1.2.3",
  datasets: ["my-app-traces"],
  time: "2026-06-30T14:00:00Z",
  url: "https://github.com/acme/app/releases/tag/v1.2.3",
});

type and datasets are the only required props. type is a free-form string ("deploy", "incident", …) that groups markers visually in the UI; title, description, and url decorate the marker’s tooltip. time is optional — omit it and Axiom stamps the annotation with its creation time. Axiom assigns the annotation id server-side and exposes it as an output.

Mark a time range

Section titled “Mark a time range”
yield* Axiom.Annotation("inc-2026-04-27", {
  type: "incident",
  title: "Database failover",
  datasets: ["my-app-traces"],
  time:    "2026-04-27T18:05:00Z",
  endTime: "2026-04-27T18:32:00Z",
  url: "https://incident.io/incidents/abc123",
});

Adding endTime turns the vertical line into a shaded band — an incident window, a maintenance period, a load test. Annotations for past events like this are a natural fit for resources: they stay in your program, so every stage (and every rebuild of a stage) carries the same incident history.

Scope across datasets

Section titled “Scope across datasets”
yield* Axiom.Annotation("release-1.2.3", {
  type: "deploy",
  title: "Release 1.2.3",
  datasets: ["my-app-traces", "my-app-logs"],
  time: "2026-06-30T14:00:00Z",
});

datasets takes any number of dataset names, and the marker renders on charts over each of them. One annotation across your traces and logs datasets keeps the deploy line in sync on both dashboards — declare it once rather than duplicating per dataset.

Mark each deploy

Section titled “Mark each deploy”
import pkg from "./package.json" with { type: "json" };


yield* Axiom.Annotation(`deploy-${pkg.version}`, {
  type: "deploy",
  title: `Release ${pkg.version}`,
  datasets: ["my-app-traces"],
  time: new Date().toISOString(),
  url: `https://github.com/acme/app/releases/tag/v${pkg.version}`,
});

Key the logical ID by version: bumping the version creates a fresh marker at deploy time, while re-deploying the same version reconciles the existing annotation in place instead of piling up duplicates — the provider probes Axiom with the server-assigned id and only creates when nothing is found.

Where next

Section titled “Where next”