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…
Annotationsを使うと、プロジェクトのタイムライン上に文脈を書き込むことができます。午前2時に始まったインシデント、チェックアウトフローを変更したリリース、誰かがフリップしたフィーチャーフラグ。6か月後、それらはグラフ上の謎のステップと説明できるグラフの違いになります。
Annotationsはどこにあるか
Orbitを開いて、プロジェクトをクリックし、プロジェクトタブストリップのObservabilityグループの下からTimelineを選択します。ページはTimeline annotationsというタイトルで、デプロイメントタイムライン上のインシデント、リリース、マイルストーン、メモをマークすることについて説明しています。
5つの種類
| 種類 | 用途 |
|---|---|
| Incident | 何か壊れた。停止、パフォーマンス低下、データ問題 |
| Release | 意味のある配信。特に説明する価値があるもの |
| Milestone | 記憶する価値のある瞬間：ローンチ日、最初の千ユーザー、完了したマイグレーション |
| Flag flip | フィーチャーフラグのオン・オフ。デプロイのような変更ですがデプロイはない |
| Note | その他の書き留める価値のあること |
Flag flipは特定の理由で独自の種類に値します。フラグの変更はデプロイなしに本番環境での動作を変えるため、デプロイ履歴に痕跡を残しません。デプロイのない日にパフォーマンスが変わった場合、フラグフリップが答えであることがよくあり、Annotationだけがそれを教えてくれます。
Annotationを作成する
- New annotationをクリックします。
- Kindを選択します。
- Occurred atを設定します。デフォルトは現在時刻で、過去の日時に設定できます。
- Titleを書きます。最大200文字。
- オプションでBodyを書きます。最大4000文字。メモ、リンク、事後分析テキスト用。
- Createをクリックします。
過去の日時設定が重要です。時間に余裕があるときにAnnotationを書き、その時間を実際に起きた時刻に設定して、タイムライン上の正しい場所に配置します。
カテゴリーではなくタイトルに答えを入れてください。「AUの顧客のチェックアウトがタイムアウト」はリストの中では有用です。「Incident」は有用ではなく、種類バッジが既に示しています。
フィルタリング
上部のフィルターバーはAllと各種類を提供します。Incidentにフィルタリングすると、プロジェクトのインシデント履歴が1つのビューで表示されます。これはまさに四半期ごとのレビューを書いたり、繰り返し発生する問題が実際に繰り返されているかどうかを調べたりするときに必要なものです。
デプロイメントにアンカーする
Annotationは単独ではなく、特定のデプロイメントに添付できます。これで結果を原因に結びつけられます。Annotationはそれを引き起こしたデプロイメントとともに移動します。
デプロイは問題がないように見えたが、1時間後に問題を引き起こしたという古典的なパターンに使用します。Annotationをそのデプロイメントにアンカーすれば、誰かの記憶の中で生きているのではなく、永続的に接続が記録されます。
インシデントは公開される
Incident Annotationは、Show recent incidentsがオンになって有効にされた場合、公開ステータスページのインシデントセクションのソースです。
誰でもIncident Annotationを読める可能性があると想定してください。顧客名、認証情報、内部システムの詳細、責任の所在をAnnotationに入れないでください。Annotationに顧客向けのアカウントを書き、内部の詳細はNote Annotationまたは独自の事後分析ドキュメントに保管してください。Orbit Status Pageを参照してください。
良いIncident Annotationを書く
インシデント中は、短くて事実的に保ちます。
- 顧客が使う言葉で、何が影響を受けるか。
- 疑われるのではなく、あなたが知っていることは何か。
- 次のアップデートはいつになるか。
その後、本体に解決策を追加します。原因が何だったのか、何がそれを修正したのか、何がそれの再発を防ぐのか。それはAnnotationをひどい時間のスナップショットではなく、永続的な記録に変えます。
和らげたいという衝動に抵抗してください。「Checkoutは40分間利用不可だった」は「一部の顧客が間欠的な問題を経験した可能性があります」よりも良く経過します。公開声明としても、独自の記録としても。
削除
各Annotationには削除コントロールがあります。確認は単に、これを取り消すことができないと言っています。
タイプミスと重複を削除します。インシデントが恥ずかしいために削除しないでください。タイムラインの価値は完全であることであり、悪い日が削除された履歴はパターンについて何も教えることができません。
チャートに対するタイムラインを読む
Annotationはメトリクスの横に配置するときに価値が出ます。
- Web Vitalsのステップ変化。 同じ日のタイムラインでリリースまたはフラグフリップをチェックしてください。Orbit Web Vitalsを参照してください。
- ビルド期間のジャンプ。 依存関係アップグレードやモノレポ構造化などのマイルストーンを探してください。Orbit Build Insightsを参照してください。
- 失敗したデプロイのクラスター。 通常、Incident Annotationがそれを説明し、1つがない場合、それ自体が知る価値があります。
Annotationを自動的に作成
AnnotationはOrbit APIを通じて作成できます。つまり、独自のツーリングでAnnotationを書くことができます。セットアップする価値のある2つのパターンがあります。
- アラートシステムが誰かにページを開くときにIncident Annotationを開くため、タイムラインは誰かがそれを行うことを思い出さずに入力されます。
- フィーチャーフラグツーリングはすべての変更でFlag flip Annotationを書きます。これはそのレコードを保ち続けるための唯一の信頼できる方法です。
認証とエンドポイントリファレンスについては、Orbit API Tokens and the REST APIを参照してください。
構築する価値のある習慣
1つのイベントに1つのAnnotation。本体に更新します。 同じインシデントを追跡する5つのAnnotationではありません。タイムラインは一目で読める必要があります。
退屈な勝利にもAnnotationをつけます。 「エッジに画像を移動」が帯域幅が低下した週の横にあるのは、その仕事が実行する価値があったことを証明する方法です。
その日のうちに書きます。 1週間後に書かれたAnnotationはより曖昧で、通常、その時刻について間違っています。
トラブルシューティング
Annotationはステータスページにない。 その種類はIncidentではない、またはステータスページ設定でShow recent incidentsスイッチが オフです。
タイトルが切り詰められた。 タイトルは200文字の上限があります。詳細を本体に入れてください。
タイムライン上の間違った場所に表示されます。 Occurred at値は、書いた時刻ではなく、イベントが起きた時刻です。削除して正しい時刻で再作成します。
何も表示されていません。 Annotationはまだ作成されていません。空の状態ページはリリース、インシデント、またはマイルストーンをマークするよう求めます。
次に行くべき場所
- Orbit Status Page：インシデントを顧客に公開するため。
- Orbit Releases：タグベースのバージョン履歴。
- Orbit Project Analytics：Annotationが説明するチャート。