可観測性（システムの内部動作を外部から把握できる性質）の基本原理――幅広いイベント（発生した事象の記録）、高基数性（多様な属性の組み合わせ）、中核分析ループ、イベント・メトリクス・ログの違い、計測（プログラムの動作を記録すること）とデバッグ成果の関連性。 ツール固有の使い方ではなく、基本原理に基づいた提案を行います。 以下のような質問が対象です: 「可観測性とは何か」「なぜ可観測性が必要か」「なぜHoneycombなのか」「イベントとメトリクスの違い」「イベントとログの違い」「メトリクスとログの違い」「なぜ幅広いイベントが必要か」「高基数性とは何か」「中核分析ループとは」「可観測性とモニタリングの違い」「ディメンショナリティ（多次元の属性）とは何か」「可観測性を説明する」、または可観測性に関する概念的な質問、あるいは従来型のモニタリングと異なるHoneycombのアプローチに関する質問。
First principles behind observability — wide events, high cardinality, the core analysis loop, events vs metrics vs logs, and how instrumentation connects to debugging outcomes. Grounds recommendations in first principles rather than tool-specific how-to. Trigger phrases: "what is observability", "why observability", "why Honeycomb", "events vs metrics vs logs", "events vs metrics", "events vs logs", "metrics vs logs", "why wide events", "what is high cardinality", "core analysis loop", "observability vs monitoring", "what is dimensionality", "explain observability", or any conceptual question about observability or why Honeycomb's approach differs from traditional monitoring.
Honeycombが採用する観測可能性（システムの動作状態を理解・説明する能力）のアプローチの基本原則です。このスキルは推奨事項の根拠となり、概念的な質問に答えるためのものです。SDKのセットアップやツール固有のガイダンスについては、otel-instrumentationスキルとquery-patternsスキルを参照してください。
観測可能性：システムが取りうるあらゆる状態を、新しいコードをデプロイすることなく、システムが生み出す情報を調べるだけで、理解し説明できる能力。たとえどんなに新奇で複雑な状況でも対応できます。
幅広いイベント（Wide Event）：作業単位の全コンテキストをキーと値のペアで記録するフラットなデータ構造。誰がリクエストを送ったか、どのエンドポイントか、キャッシュヒット・ミス、ビルドバージョン、処理時間、エラー状態、その操作に関連するビジネスコンテキストなどをすべて含みます。OpenTelemetryでは、スパンが幅広いイベントに相当します。
高カーディナリティ（Cardinality）：あるフィールドが持ちうる異なる値の数。数百万個の値を持つuser.idは高カーディナリティです。数個の値しか持たないhttp.methodは低カーディナリティです。
高ディメンショナリティ（Dimensionality）：イベント上の異なるフィールドの数。50個の属性を持つスパンは高ディメンショナリティです。
| 概念 | 観測可能性 | 従来の監視 |
|---|---|---|
| 質問 | 任意、事前には決定不可 | 事前に定義済み（ダッシュボード、アラート） |
| データ形状 | クエリ時に決定 | 計測時に決定 |
| カーディナリティ | 高カーディナリティは価値 | 高カーディナリティはコスト高 |
| 調査 | 探索 → 絞り込み → 確認 | ダッシュボード確認 → エスカレーション |
収集するデータの形状は、後で質問できることの範囲を制限します。メトリクスは計測時にコンテキストを事前に集約してしまいます。幅広いイベントはコンテキストを保持し、クエリ時にデータ分析の形状を決定できます。
スパン上のすべての属性がクエリ可能な次元になります。同じスパンにuser.id、deployment.version、cache.hitを追加することで、単一のクエリで関連付けられます。たとえば「遅いリクエストはテナントXから来ており、バージョン2.3.1で、キャッシュミスが発生している」という分析が可能です。メトリクスだけではこれができません。なぜなら、ディメンション（次元）の組み合わせごとに新しい時系列が作成されるからです。
Honeycombのストレージエンジンは、メトリクスシステムに影響するコスト爆増なしに、高カーディナリティとディメンショナリティを処理できます。user.idのような高カーディナリティフィールドを追加しても、数百万の時系列が生まれません。各イベントの追加の列になり、クエリ時に集約されます。
| 構造化イベント（スパン） | メトリクス | ログ | |
|---|---|---|---|
| 捕捉内容 | リクエスト全体のコンテキスト（すべての属性） | 事前に集約された数値（低カーディナリティなタグ付き） | 行単位のテキストまたは構造化フィールド |
| 失われるもの | なし — 生イベント保持 | 個別リクエスト、高カーディナリティなディメンション | 行間の関連性（トレースコンテキストなし） |
| クエリ能力 | 任意のディメンション上でGROUP BY、フィルタ、BubbleUp実行可能 | 事前定義ディメンションの高速集約 | テキスト検索、構造化フィールドクエリ |
| コスト増減 | イベント数に比例 | ディメンション数（カーディナリティ）に指数比例 | 総量に比例、クエリコスト変動 |
| 最適用途 | 調査、根本原因分析 | 安価なアラート、長期トレンド | 監査証跡、稀なイベント |
メトリクスやログ行を生み出すのと同じ計測労力で、幅広いイベントを生み出すことができます。そしてイベントは3つの機能をすべて提供します。数えられ（メトリクス的に）、読め（ログ的に）、あらゆるディメンション横断で分析できます（観測可能性として）。
同じ操作を3つの方法で計測したコード例については、${CLAUDE_PLUGIN_ROOT}/skills/observability-fundamentals/references/events-vs-metrics-vs-logs.mdを参照してください。
Honeycombでのデバッグは以下のループに従います：定義 → 可視化 → 調査 → 評価
そしてループを繰り返します。各回答は新しい質問を生みます。BubbleUpはすべての列で分布を比較して自動化しますが、イベントに比較に十分なディメンションがないと機能しません。
このループを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 — コード例：同じ操作をイベント、メトリクス、ログとして実装First principles behind Honeycomb's approach to observability. Use this to ground recommendations and answer conceptual questions — for SDK setup and tool-specific guidance, see the otel-instrumentation and query-patterns skills.
Observability: The ability to understand and explain any state your system can get into, no matter how novel or complex — by examining what the system produces, without deploying new code for each new question.
Wide event: A flat key-value record capturing the full context of a unit of work — who made the request, which endpoint, cache hit/miss, build version, duration, error status, and any business context relevant to the operation. In OpenTelemetry, a span is a wide event.
High cardinality: The number of unique values a field can have. user.id with
millions of values is high cardinality. http.method with a handful is low cardinality.
High dimensionality: The number of distinct fields on your events. A span with 50 attributes has high dimensionality.
| Concept | Observability | Traditional Monitoring |
|---|---|---|
| Questions | Arbitrary, unknown ahead of time | Pre-defined (dashboards, alerts) |
| Data shape | Decided at query time | Decided at instrumentation time |
| Cardinality | High cardinality is valuable | High cardinality is expensive |
| Investigation | Explore → narrow → confirm | Check dashboard → escalate |
The shape of the data you collect constrains the questions you can ask later. Metrics pre-aggregate context away at instrumentation time. Wide events preserve context and let you decide the shape of your analysis at query time.
Every attribute on a span is a queryable dimension. Adding user.id, deployment.version,
and cache.hit to the same span lets you correlate them in a single query — "slow
requests are from tenant X on version 2.3.1 with cache misses." Separate metrics can't
do this because each dimension combination creates a new time series.
Honeycomb's storage engine handles high cardinality and dimensionality without the
cost explosion that affects metrics systems. Adding a high-cardinality field like
user.id doesn't create millions of time series — it's another column on each event,
aggregated at query time.
| Structured Events (Spans) | Metrics | Logs | |
|---|---|---|---|
| Captures | Full request context (all attributes) | Pre-aggregated numbers with low-cardinality tags | Text or structured fields per line |
| Discards | Nothing — raw events retained | Individual requests, high-cardinality dimensions | Correlation across lines (without trace context) |
| Query power | GROUP BY, filter, BubbleUp on any dimension | Fast aggregates on pre-defined dimensions | Text search, structured field queries |
| Cost scaling | Linear with event volume | Exponential with dimension count (cardinality) | Linear with volume, query cost varies |
| Best for | Investigation, root cause analysis | Cheap alerting, long-term trends | Audit trails, rare events |
The same instrumentation effort that produces a metric or log line can produce a wide event — and the event gives you all three capabilities: count it (metric), read it (log), analyze it across dimensions (observability).
For code examples showing the same operation instrumented three ways, see
${CLAUDE_PLUGIN_ROOT}/skills/observability-fundamentals/references/events-vs-metrics-vs-logs.md.
Debugging in Honeycomb follows a loop: Define → Visualize → Investigate → Evaluate.
Then loop — each answer raises new questions. BubbleUp automates steps 2-3 by comparing distributions across every column, but it only works if events have enough dimensions to diff on.
For the structured workflow that implements this loop with Honeycomb's tools, see the production-investigation skill.
Every attribute on a span is a dimension BubbleUp can use to find root causes. The attributes that matter most during incidents answer three questions:
Instrument for the questions you'll ask at 3am, not for completeness. If BubbleUp returns nothing useful during an investigation, the issue is usually an instrumentation gap — add the missing dimensions and try again.
For the complete attribute catalog, see
${CLAUDE_PLUGIN_ROOT}/skills/otel-instrumentation/references/wide-event-attributes.md.
For SDK guidance on adding attributes, see the otel-instrumentation skill.
Instrumentation is not a one-time setup task. The engineers who write the code are best positioned to know which operations are critical, which paths are error-prone, and what context helps during debugging. Treat instrumentation like testing: plan telemetry when planning features, review it in code reviews, and add missing dimensions as post-incident follow-ups.
${CLAUDE_PLUGIN_ROOT}/skills/observability-fundamentals/references/events-vs-metrics-vs-logs.md — Code examples: same operation as event, metric, and log原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。