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
import * as Axiom from "@alchemy.run/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
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
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
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.
:::note Like any resource, an annotation whose logical ID leaves the program is deleted on the next deploy — so the version-keyed marker above tracks the current release per stage, not the full release history. For a permanent trail of every past deploy, create annotations out-of-band at release time (Axiom's API from CI); keep the resource form for markers you want reproducible per stage. :::
Where next
- Dashboards as code — the charts your markers land on, plus saved views.
- Ingest — datasets, tokens, and wiring OTEL output into Axiom.
- Annotation API reference — full props and attributes.