Orbit
Orbit Timeline Annotations
Annotations let you write context onto a project's timeline: the incident that started at 2am, the release that changed the checkout flow, the feature flag someone flipped. Six months later they are the difference between a chart with a mysterious step in it and a chart you can explain.
Where Annotations Live
Open Orbit, click the project, and choose Timeline under the Observability group in the project tab strip. The page is titled Timeline annotations and describes itself as marking incidents, releases, milestones and notes on your deployment timeline.
The Five Kinds
| Kind | Use it for |
|---|---|
| Incident | Something broke. Outages, degraded performance, data problems |
| Release | A meaningful shipment, especially one worth explaining |
| Milestone | A moment worth remembering: launch day, first thousand users, a migration completed |
| Flag flip | A feature flag turned on or off, which is a deploy-shaped change with no deploy |
| Note | Anything else worth writing down |
Flag flip deserves its own kind for a specific reason. A flag change alters behaviour in production without producing a deployment, so it leaves no trace in the deploy history. When performance moves on a day with no deploys, a flag flip is very often the answer, and only an annotation will tell you.
Creating an Annotation
- Click New annotation.
- Choose the Kind.
- Set Occurred at. It defaults to now, and you can backdate it.
- Write a Title, up to 200 characters.
- Optionally write a Body, up to 4000 characters, for notes, links or postmortem text.
- Click Create.
Backdating matters. Write the annotation when you have time, and set the time to when the thing actually happened, so it lands in the right place on the timeline.
Put the answer in the title, not the category. "Checkout timing out for AU customers" is useful in a list; "Incident" is not, and the kind badge already says that.
Filtering
The filter bar at the top offers All plus each kind. Filtering to Incident gives you an incident history for the project in one view, which is exactly what you want when writing a quarterly review or working out whether a recurring problem is actually recurring.
Anchoring To a Deployment
An annotation can be attached to a specific deployment rather than standing alone. That is how you tie a consequence to a cause: the annotation travels with the deployment that caused it.
Use it for the classic pattern of a deploy that looked fine and caused a problem an hour later. Anchor the incident to that deployment and the connection is recorded permanently, rather than living in someone's memory.
Incidents Are Published
Incident annotations are the source for the incidents section of your public status page, if you have one enabled with Show recent incidents switched on.
Assume anyone can read an incident annotation. Do not put customer names, credentials, internal system details or blame in one. Write the customer-facing account in the incident annotation and keep the internal detail in a note annotation or your own postmortem document. See Orbit Status Page.
Writing a Good Incident Annotation
During the incident, keep it short and factual:
- What is affected, in the terms a customer would use.
- What you know, not what you suspect.
- When you will next update.
Afterwards, add a body with the resolution: what the cause was, what fixed it, and what stops it recurring. That turns the annotation into a permanent record instead of a snapshot of a bad hour.
Resist the urge to soften. "Checkout was unavailable for 40 minutes" ages better than "some customers may have experienced intermittent issues", both as a public statement and as your own record.
Deleting
Each annotation has a delete control. The confirmation says simply that this cannot be undone.
Delete typos and duplicates. Do not delete incidents because they are embarrassing: the value of the timeline is that it is complete, and a history with the bad days removed cannot tell you anything about patterns.
Reading the Timeline Against Your Charts
Annotations pay off when you put them next to a metric:
- A step change in Web Vitals. Check the timeline for a release or a flag flip on the same day: see Orbit Web Vitals.
- A jump in build duration. Look for a milestone such as a dependency upgrade or a monorepo restructure: see Orbit Build Insights.
- A cluster of failed deploys. An incident annotation usually explains it, and if there is not one, that itself is worth knowing.
Creating Annotations Automatically
Annotations can be created through the Orbit API, which means your own tooling can write them. Two patterns are worth setting up:
- Your alerting system opens an Incident annotation when it pages someone, so the timeline is populated without anyone remembering to do it.
- Your feature-flag tooling writes a Flag flip annotation on every change, which is the only reliable way to keep that record.
See Orbit API Tokens and the REST API for authentication and the endpoint reference.
Habits Worth Building
One annotation per event, updated in the body. Not five annotations tracking the same incident. The timeline should be readable at a glance.
Annotate the boring wins too. "Moved images to the edge" next to the week your bandwidth dropped is how you prove the work was worth doing.
Write it the same day. An annotation written a week later is vaguer and usually wrong about the time.
Troubleshooting
The annotation is not on the status page. Its kind is not Incident, or the Show recent incidents switch is off on the status page settings.
The title was truncated. Titles cap at 200 characters. Put the detail in the body.
It appears in the wrong place on the timeline. The Occurred at value is when the event happened, not when you wrote it. Delete and recreate with the right time.
Nothing is listed. No annotations have been created yet. The empty state prompts you to mark a release, incident or milestone.
Where To Go Next
- Orbit Status Page to publish incidents to your customers.
- Orbit Releases for the tag-based version history.
- Orbit Project Analytics for the charts annotations explain.