Orbit
Orbit 时间线注释
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…
注解让你在项目的时间轴上写入上下文：2am 开始的事故、改变了结账流程的发布、某人切换的功能开关。六个月后，它们的意义在于：一个图表要么有神秘的阶跃看不出原因，要么有注解能解释一切。
注解在哪里
打开 Orbit，点击项目，在项目标签栏的 Observability 组下选择 Timeline。该页面标题为 Timeline annotations，描述了在部署时间轴上标记事故、发布、里程碑和注释的功能。
五种类型
| 类型 | 用途 |
|---|---|
| Incident | 发生了中断。故障、性能下降、数据问题 |
| Release | 有意义的发布，尤其是值得说明的 |
| Milestone | 值得记住的时刻：上线日期、首个千级用户、迁移完成 |
| Flag flip | 功能开关打开或关闭，这是一个没有部署的类部署变化 |
| Note | 其他任何值得记录的内容 |
Flag flip 之所以需要单独的类型，是有具体原因的。功能开关的变更会改变生产环境中的行为，但不会产生部署，所以在部署历史中没有记录。当没有部署的日期性能发生变化时，通常是功能开关变更引起的，只有注解能告诉你这一点。
创建注解
- 点击 New annotation。
- 选择 Kind。
- 设置 Occurred at。默认为现在，你可以回溯日期。
- 写入 Title，最多 200 个字符。
- 可选：写入 Body，最多 4000 个字符，用于注释、链接或事后分析文本。
- 点击 Create。
回溯日期很重要。在有时间的时候写入注解，将时间设置为实际发生的时间，这样它会落在时间轴的正确位置。
把答案写在标题里，而不是类别里。"Checkout timing out for AU customers" 在列表中很有用；"Incident" 则没有，而且类型徽章已经说明了这一点。
筛选
顶部的筛选栏提供 All 以及每种类型。筛选到 Incident 会在一个视图中给出项目的事故历史，这正是你在撰写季度评审或判断某个反复出现的问题是否真的反复出现时需要的。
锚定到部署
注解可以附加到特定的部署，而不是独立存在。这是将结果与原因联系起来的方式：注解随着导致它的部署而移动。
这适用于经典场景：一个看起来没问题的部署在一小时后引发了问题。将事故注解锚定到该部署，连接就被永久记录了，而不是只存在某人的记忆中。
事故会被发布
事故注解是公开状态页面中事故部分的来源，前提是你启用了该功能并打开了 Show recent incidents 开关。
假设任何人都可以读到事故注解。不要在其中放置客户名称、凭证、内部系统细节或责任归咎。在事故注解中写入面向客户的说明，将内部细节保留在注释注解或你自己的事后分析文档中。参见 Orbit Status Page。
编写优质的事故注解
在事故期间，保持简洁和真实：
- 用客户会使用的术语说明受影响的内容。
- 说你知道的，而不是你怀疑的。
- 说明你何时会下一次更新。
之后，在正文中添加解决方案：原因是什么、如何修复的，以及什么能阻止它再次发生。这样注解就变成了永久记录，而不是糟糕一小时的快照。
抵制软化表述的诱惑。"Checkout was unavailable for 40 minutes" 比 "some customers may have experienced intermittent issues" 更经得起时间检验，无论是作为公开声明还是作为你自己的记录。
删除
每个注解都有一个删除控件。确认只是简单地说明这不能撤销。
删除打字错误和重复项。不要因为事故很尴尬就删除它：时间轴的价值在于它是完整的，删除了坏日子的历史无法告诉你任何关于模式的信息。
根据图表阅读时间轴
注解在你把它们放在指标旁边时才能发挥作用：
- Web Vitals 中的阶跃变化。 检查时间轴上同一天的发布或功能开关：参见 Orbit Web Vitals。
- 构建时长的跳跃。 查找里程碑，如依赖升级或单体仓库重组：参见 Orbit Build Insights。
- 一群失败的部署。 事故注解通常能解释它，如果没有注解，这本身就值得了解。
自动创建注解
注解可以通过 Orbit API 创建，这意味着你自己的工具可以写入它们。有两个模式值得设置：
- 你的告警系统在页面通知某人时打开一个 Incident 注解，这样时间轴被填充而不需要任何人记得做这件事。
- 你的功能开关工具在每次变更时写入一个 Flag flip 注解，这是保持该记录的唯一可靠方式。
参见 Orbit API Tokens and the REST API 了解身份验证和端点参考。
值得养成的习惯
一个事件一个注解，在正文中更新。 不要五个注解跟踪同一个事故。时间轴应该一眼就能读懂。
也要注解无聊的胜利。 "Moved images to the edge" 放在你的带宽下降的那一周旁边，就是你证明这项工作值得做的方式。
在同一天写它。 一周后写的注解会更模糊，通常在时间上也是错的。
故障排除
注解没有出现在状态页面上。 它的类型不是 Incident，或者状态页面设置中的 Show recent incidents 开关关闭了。
标题被截断了。 标题上限为 200 个字符。把细节放在正文中。
它出现在时间轴的错误位置。 Occurred at 值是事件发生的时间，不是你写它的时间。删除并用正确的时间重新创建。
没有列出任何内容。 还没有创建任何注解。空状态会提示你标记发布、事故或里程碑。
接下来的步骤
- Orbit Status Page，将事故发布给你的客户。
- Orbit Releases，基于标签的版本历史。
- Orbit Project Analytics，注解所解释的图表。