Guide
Chart annotations
Annotations draw deploys, alert incidents and your own events as markers on time charts, so you can see a change next to its effect. They appear on the Explore histogram and | stats time charts, Metrics charts, dashboard time-series panels and the Traces overview charts. Hover a marker for its title, kind, service, time and note; click it to open the linked page.
The kinds#
| Kind | Where it comes from | Drawn as |
|---|---|---|
| Deploy | Automatic. The first time a service sends a new service.version resource attribute on its logs or spans. | A vertical line with a small marker at the top. Click it to open Explore for that service around the deploy (15 minutes either side). |
| Incident | Your alert incidents, read live. The title is the rule name. | A shaded band from the moment the incident opened to the moment it resolved, or to now while it is firing. Click it to open the incident. |
| Custom | Created by people in the app, by CI/CD with an API key, or by AI agents through MCP. | A vertical line, or a shaded band when it has an end time. |
| Change | Reported by CI/CD or recorded under Alerts, Changes: a deploy, config change, flag or migration. | A vertical line, like a deploy. |
How deploys are found#
Set service.version as a resource attribute in your OpenTelemetry SDK or collector (for example OTEL_RESOURCE_ATTRIBUTES=service.name=checkout,service.version=2.4.1). Logthread notes the first sighting of each service and version pair on logs and spans. Deploys are detected on the same schedule as the service topology, so a deploy appears within about 10 minutes of its first event, not instantly. A service's very first version also becomes an annotation, and so does a version already running when you first start sending data. For an instant marker from a pipeline, create a custom annotation as shown below.
Show, hide and filter#
The Annotations control on those pages switches markers on or off, picks the kinds, and can limit them to the services in the current view. It is remembered per browser. By default markers are on, all kinds are shown, and only the view's own services are used when the view has a service filter. A marker with no service always shows.
Add an annotation#
In the app#
Open Annotations on Explore, Metrics or a dashboard and choose Add annotation (members, admins and owners). Give it a title, an optional note, a time (now, or the range you brushed in Explore), an optional service and tags. The control lists the latest custom annotations in view, with Delete for the ones you may delete: admins and owners can delete any custom annotation, and members can delete their own. Deploy and incident markers cannot be deleted.
From CI/CD#
Create an API key with the Create annotations (annotate) scope and store it in your CI secret store. Then call the API when a release finishes:
curl -X POST https://logthread.com/api/annotations \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
-d '{"title": "Release 2.4.1", "text": "Checkout rollout", "service": "checkout", "tags": ["release", "prod"]}'The answer (HTTP 201) is the new annotation. Leave out time to use now. Send time (ISO 8601, for example 2026-10-28T14:00:00Z) and end for a past event or a range, such as a maintenance window.
| Field | Rules |
|---|---|
title | Required, 1 to 200 characters. |
text | Optional, up to 2,000 characters. |
time | Optional, default now. Between 30 days ago and 1 day ahead. |
end | Optional. Not before time, at most 7 days after it. Makes the annotation a range. |
service | Optional, up to 200 characters. |
tags | Optional, up to 10, each 1 to 64 characters of letters, digits and _ . : / -. |
Unknown fields are rejected. The key can read annotations with GET /api/annotations?from=...&to=... (any API key can) but cannot delete them.
From an AI agent#
The MCP tools list_annotations and create_annotation do the same; create_annotation needs a key with the annotate scope. See AI agents (MCP).
Report changes from CI#
Deploys, config changes and feature flags have their own API, so incidents can list them. See What changed before an incident.
Read annotations over the API#
curl "https://logthread.com/api/annotations?from=2026-10-28T00:00:00Z&to=2026-10-29T00:00:00Z&kinds=deploy,custom&services=checkout" \
-H "Authorization: Bearer <api key>"Answers {"items": [...], "truncated": false}, newest first. Each item has id, kind, time, end, title, text, service, tags, link, state (incidents: firing, acknowledged, resolved or muted) and created_by (custom only). from and to are required.
Limits#
| Custom annotations per workspace | 50,000. Past that, creating one fails with annotation_limit until you delete some. |
| Range of a query | At most 90 days; up to 500 items come back, with truncated: true when there are more. |
| Range annotation length | At most 7 days. |
| Time of a new annotation | From 30 days ago to 1 day ahead. |
| Keeping | Deploy and custom annotations are kept for 400 days, then removed. Incidents follow your alert history. |
| Who can do what | Viewers see annotations. Members create them and delete their own. Admins and owners delete any custom annotation. |
Every creation and deletion is recorded in the Audit log (annotation.create, annotation.delete).
Next: put your charts together on a dashboard.