observability-fundamentals について
エンジニア向けに、Honeycombのオブザーバビリティの考え方を解説するスキルです。ワイドイベント、次元分析、調査のループを通じて、計装と根本原因分析の関係を説明します。
主な機能
- 01ワイドイベントとスパンの解説
- 02イベント・メトリクス・ログの比較
- 03カーディナリティと次元数の説明
- 04調査分析ループの概要
- 05計装と根本原因分析の関連付け
活用シーン
- 01有用なテレメトリー属性の選定
- 02イベントベースの可観測性の理解
- 03インシデント調査の構成
- 04計装の不足箇所の特定
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/observability-fundamentalsを入力して読み込まれたか確認します。
同梱ファイルreferences/events-vs-metrics-vs-logs.md
詳細
可観測性の基礎
Honeycomb の可観測性へのアプローチを支える第一原理です。これを基盤として推奨事項を根拠づけ、概念的な質問に答えてください。SDK のセットアップやツール固有のガイダンスについては、otel-instrumentation および query-patterns スキルを参照してください。
定義
可観測性: システムが取り得るあらゆる状態を、どれほど新奇または複雑であっても理解し説明する能力 — 新しい問いごとに新しいコードをデプロイすることなく、システムが生成するものを調べることで実現します。
ワイドイベント: ある作業単位の完全なコンテキストを捉えたフラットなキーと値のレコード — 誰がリクエストを行ったか、どのエンドポイントか、キャッシュヒット/ミス、ビルドバージョン、所要時間、エラーステータス、およびその操作に関連するあらゆるビジネスコンテキスト。OpenTelemetry では、スパンがワイドイベントです。
高いカーディナリティ: あるフィールドが取り得る一意な値の数。数百万の値を持つ user.id は高いカーディナリティです。ごく少数の値しか持たない http.method は低いカーディナリティです。
高い次元性: イベント上の異なるフィールドの数。50 個の属性を持つスパンは高い次元性を持ちます。
| 概念 | 可観測性 | 従来のモニタリング |
|---|---|---|
| 問い | 任意で、事前には不明 | 事前定義済み（ダッシュボード、アラート） |
| データの形 | クエリ時に決定 | 計装時に決定 |
| カーディナリティ | 高いカーディナリティが価値を持つ | 高いカーディナリティはコストが高い |
| 調査 | 探索 → 絞り込み → 確認 | ダッシュボードを確認 → エスカレーション |
なぜワイドイベントなのか
収集するデータの形は、後で尋ねることのできる問いを制約します。メトリクスは計装時にコンテキストを事前集約して捨ててしまいます。ワイドイベントはコンテキストを保持し、分析の形をクエリ時に決められるようにします。
スパン上のすべての属性はクエリ可能な次元です。user.id、deployment.version、cache.hit を同じスパンに追加すれば、それらを 1 つのクエリで相関させられます —「遅いリクエストはテナント X からの、バージョン 2.3.1 で、キャッシュミスのものだ」。別々のメトリクスではこれができません。各次元の組み合わせが新しい時系列を生成するからです。
Honeycomb のストレージエンジンは、メトリクスシステムに影響するコスト爆発なしに、高いカーディナリティと次元性を扱います。user.id のような高いカーディナリティのフィールドを追加しても、数百万の時系列は生まれません — それは各イベント上のもう 1 つのカラムであり、クエリ時に集約されます。
イベント vs メトリクス vs ログ
| 構造化イベント（スパン） | メトリクス | ログ | |
|---|---|---|---|
| 捉えるもの | 完全なリクエストコンテキスト（すべての属性） | 低カーディナリティのタグ付きで事前集約された数値 | 行ごとのテキストまたは構造化フィールド |
| 捨てるもの | 何も捨てない — 生のイベントを保持 | 個々のリクエスト、高いカーディナリティの次元 | 行をまたいだ相関（トレースコンテキストがない場合） |
| クエリ能力 | 任意の次元での GROUP BY、フィルター、BubbleUp | 事前定義された次元での高速な集約 | テキスト検索、構造化フィールドのクエリ |
| コストのスケーリング | イベント量に対して線形 | 次元数（カーディナリティ）に対して指数関数的 | 量に対して線形、クエリコストは変動 |
| 最適な用途 | 調査、根本原因分析 | 低コストなアラート、長期的な傾向 | 監査証跡、まれなイベント |
メトリクスやログ行を生成するのと同じ計装の労力でワイドイベントを生成できます — そしてイベントは 3 つの能力すべてを提供します。数える（メトリクス）、読む（ログ）、次元をまたいで分析する（可観測性）。
同じ操作を 3 通りの方法で計装したコード例については、${CLAUDE_PLUGIN_ROOT}/skills/observability-fundamentals/references/events-vs-metrics-vs-logs.md を参照してください。
中核となる分析ループ
Honeycomb でのデバッグは、定義 → 可視化 → 調査 → 評価 というループに従います。
- 定義 — 問いを組み立てます。アラート、SLO バジェットの消費、またはユーザーからの報告を出発点にします。
- 可視化 — クエリを実行して、問題の形を把握します (HEATMAP、COUNT、P99)。
- 調査 — BubbleUp (すべてのディメンションにわたる外れ値とベースラインの自動比較) とトレース分析で絞り込みます。
- 評価 — 疑わしい原因を含めた場合と含めない場合でクエリを実行し、仮説を確認します。
その後、ループします — 各回答が新たな問いを生みます。BubbleUp はすべてのカラムにわたって分布を比較することでステップ 2〜3 を自動化しますが、これはイベントに差分を取るための十分なディメンションがある場合にのみ機能します。
Honeycomb のツールでこのループを実装する構造化されたワークフローについては、production-investigation スキルを参照してください。
計装は調査につながる
スパン上のすべての属性は、BubbleUp が根本原因を見つけるために使用できるディメンションです。インシデント時に最も重要となる属性は、次の 3 つの問いに答えます:
- 誰が影響を受けているか? — ユーザー、テナント、アカウント階層、リージョン
- 何が変わったか? — デプロイバージョン、フィーチャーフラグ、設定バージョン
- ボトルネックはどこか? — ビジネスオペレーションのスパン、タイミングの内訳、キャッシュの状態
網羅性のためではなく、深夜 3 時に尋ねることになる問いに備えて計装してください。調査中に BubbleUp が有用な結果を返さない場合、問題は通常、計装の不足です — 不足しているディメンションを追加して再試行してください。
属性の完全なカタログについては、${CLAUDE_PLUGIN_ROOT}/skills/otel-instrumentation/references/wide-event-attributes.md を参照してください。
属性の追加に関する SDK のガイダンスについては、otel-instrumentation スキルを参照してください。
開発プラクティスとしての計装
計装は一度きりのセットアップ作業ではありません。コードを書くエンジニアは、どのオペレーションが重要か、どのパスがエラーを起こしやすいか、デバッグ時にどのようなコンテキストが役立つかを知るのに最も適した立場にいます。計装をテストのように扱ってください。機能を計画するときにテレメトリーを計画し、コードレビューでそれをレビューし、インシデント後のフォローアップとして不足しているディメンションを追加します。
その他のリソース
参照ファイル
${CLAUDE_PLUGIN_ROOT}/skills/observability-fundamentals/references/events-vs-metrics-vs-logs.md— コード例: 同じオペレーションをイベント、メトリクス、ログとして表現
相互参照
- SDK のセットアップとカスタム計装について: otel-instrumentation スキル
- 中核となる分析ループを実装する調査ワークフローについて: production-investigation スキル
- 自律的な計装ギャップ分析について: instrumentation-advisor エージェント