オブザーバビリティの世界へようこそ。
システムが巨大化し、マイクロサービスが複雑に絡み合う現代において、多くのエンジニアが陥る「罠」があります。それは、「デプロイした直後に何かが起きたのに、それがデプロイの影響なのか、たまたま起きたノイズなのか判別できず、貴重な時間をログの海で浪費する」という悪夢です。
今日は、その悪夢を終わらせるための魔法——「Grafana Annotation（注釈）」によるデプロイ追跡の極意を伝授します。
—
1. なぜ「Annotation」がオブザーバビリティの神髄なのか
メトリクスグラフを見ていて、「14:02にエラー率が跳ね上がったな。何があったんだ？」と焦ったことはありませんか？ 多くの人はここから「GitHubのコミットログを見る」「Slackのデプロイ通知を探す」という作業を始めます。
これこそが時間の無駄です。
Annotationを使えば、グラフ上に「デプロイ開始」「デプロイ完了」「ロールバック」といったイベントを直接描画できます。これにより、「グラフ上の変動」と「コードの変更」を視覚的に重ね合わせることができるのです。脳の負荷を極限まで下げ、瞬時に因果関係を特定する。これがプロの監視の作法です。
—
2. 準備：Grafana APIキーの発行
まずは、CI/CDツール（今回はGitHub Actionsを例にします）からGrafanaへ書き込むための鍵を作ります。
1. Grafanaの `Administration` > `Users and connections` > `Service accounts` へ移動。
2. `Add service account` をクリック。
3. `Role` に `Editor` を付与。
4. `Add service account token` でトークンを生成し、控えておきます（※二度と表示されないので注意！）。
—
3. 実践：GitHub ActionsでAnnotationを自動化する
CI/CDパイプラインの最後に、Grafanaへ「今、デプロイしました」という合図を送るステップを追加します。`curl` を使うだけのシンプルな構成です。
.github/workflows/deploy.yml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to Production
run: ./deploy-script.sh # ここで実際のデプロイ処理
- name: Notify Grafana Annotation
# デプロイ成功時にGrafanaにマーカーを打つ
run: |
curl -X POST https://your-grafana-url.com/api/annotations \
-H “Authorization: Bearer ${{ secrets.GRAFANA_API_TOKEN }}” \
-H “Content-Type: application/json” \
-d ‘{
“text”: “Deployment: ${{ github.sha }} (by ${{ github.actor }})”,
“tags”: [“deploy”, “production”],
“isRegion”: false
}’
この設定のポイント
- `tags`: ここが重要です。「deploy」「production」とタグを付けておけば、特定のタグを持つアノテーションだけをダッシュボード上でフィルタリングできます。
- `text`: デプロイしたコミットハッシュや実行者を入れておきましょう。マウスをホバーするだけで、「誰が、何を」入れたのか即座に分かります。
—
4. 精度を高める：ダッシュボードでの可視化設定
コードを送るだけでは不十分です。Grafanaのダッシュボードでそのアノテーションを表示させる設定を行います。
1. 可視化したいダッシュボードの `Dashboard settings`（歯車アイコン）を開く。
2. `Annotations` > `Add annotation query` を選択。
3. 以下のように設定します：
- Name: Deployment Tracker
- Data source: Grafana (または使用しているメトリクスソース)
- Tags: `deploy,production` （先ほど送信したタグと一致させる）
これで、グラフ上に垂直の線が引かれます。線をクリックすれば、デプロイの詳細がポップアップされます。
—
5. さらに先へ：現場で震えるほど役立つ「応用テクニック」
ここからは、一歩進んだ「達人」の知見です。
- 期間を示す（`isRegion: true`）:
デプロイが瞬時に終わらない場合、`isRegion: true` を指定して開始と終了の2回APIを叩いてください。グラフ上に「デプロイ期間中」という帯が表示され、どのメトリクスの変動がデプロイ期間と完全に一致しているかを一目で判別できます。
- 自動ロールバックと連動させる:
アラートが鳴った直後に自動ロールバックするスクリプトを組んでいるなら、その際にもAnnotationを打ちましょう。`type: “rollback”` とタグを打てば、「デプロイしてエラーが発生し、即座に修正された」という履歴が時系列で美しく残ります。
—
最後に：監視とは「物語」を読むこと
監視ツールをただの「数字を表示する箱」にしないでください。
Annotationを使いこなすことは、システムの歴史をグラフに刻むことです。障害が発生したとき、慌ててログを漁るのではなく、「ああ、このデプロイのここから影響が出ているね」と冷静に指差せる。
この状態こそが、エンジニアにとっての最大の武器です。
今日の設定が、あなたの運用ライフを劇的に楽にすることを約束します。さあ、今すぐコードを書いて、あなたのダッシュボードに「歴史」を刻んでみてください。