query-patterns

Honeycomb クエリパターン

効果的な Honeycomb クエリを書くための、意見を込めたガイダンスです。MCP ツールは すでにパラメータとスキーマを文書化しています。このスキルは、ツールの呼び出し方ではなく、 各パターンをいつ、なぜ使うかに焦点を当てています。

主要な原則

1. レイテンシに AVG を使わない — AVG はテールレイテンシを隠してしまいます。遅いユーザーが何を経験しているかを確認するには P99（または P95/P90）を使用してください。AVG はペイロードサイズのようなレイテンシ以外のメトリクス用に取っておきましょう。
2. 分布には HEATMAP を使う — 単一の数値による集計は二峰性のパターンを隠してしまいます。HEATMAP は、母集団が1つなのか2つなのかを明らかにします。
3. 計算を1つのクエリにまとめる — COUNT, P99(duration_ms), HEATMAP(duration_ms) を単一のクエリで実行すると、API 呼び出しを減らし、全体像を把握できます。
4. 広く始めて、WHERE で絞り込む — まず COUNT/GROUP BY で形状を把握し、その後フィルターを追加して焦点を絞ります。
5. 先行作業を確認する — 新しいクエリを書く前に find_queries を呼び出してください。すでに誰かがその質問に答えているかもしれません。

適切な操作の選択

質問	使用するもの
トラフィックはどれくらい？	COUNT を route またはサービスでグループ化
ユニークユーザー/IP は何人？	COUNT_DISTINCT(field)
ほとんどのユーザーにとってどれくらい速い？	P50(duration_ms)
最も遅いユーザーにとってどれくらい速い？	P99(duration_ms)
二峰性のパターンはある？	HEATMAP(duration_ms)
最悪のケースは？	MAX(duration_ms)
同時操作はいくつ？	CONCURRENCY
時間の経過とともに悪化している？	RATE_AVG(duration_ms)

リレーショナルフィールド戦略

リレーショナルプレフィックスを使用して、トレース内でスパンをまたぐ質問をします。

• 「特定のダウンストリームが原因の遅いエンドポイントを表示する」: any.service.name でフィルターして、そのサービスが関与しているトレースを見つけ、root.http.route でグループ化して、どのユーザー向けエンドポイントが影響を受けているかを確認します。
• 「エラーになったトレースは何が違うのか？」: any.error = true でフィルターし、root.name でグループ化して、どのエントリポイントのトレースツリー内のどこかにエラーがあるかを確認します。
• ノイズを除外する: none.service.name = "health-check" はヘルスチェックを含むトレースを除去します。

計算フィールド

計算フィールドは、クエリ時に評価されるイベント単位の式です。コードに再度インストルメンテーションを施すことなく、既存のフィールドを変換・分類・結合できます。

3つのスコープ — ニーズに合う最も狭いスコープを選択してください:

• クエリスコープ（保存されない）: 探索的な単発分析
• データセットレベル（保存される）: 1つのサービスのデータセット内で再利用可能
• 環境レベル（保存される）: すべてのデータセットで再利用可能（例: error_pct）

一般的なパターン:

• エラー率: MUL(IF($error, 1, 0), 100) → パーセンテージを取得するには AVG(error_pct) を使用
• ステータス分類: IF(GTE($http.status_code, 500), "5xx", GTE($http.status_code, 400), "4xx", "ok")
• レイテンシのバケット化: BUCKET($duration_ms, 500, 0, 3000)
• プレフィックスルーティング: IF(STARTS_WITH($url, "/admin"), "admin", STARTS_WITH($url, "/api"), "api", "other")
• 完全一致の分類: IF(EQUALS(...)) の連鎖の代わりに SWITCH を使用してください — 同じ式で、より効率的です

重要なガードレール:

• 表示専用（エイリアスのみ）のフィールドを作成しないでください — 別のフィールドの名前を変えるだけのフィールドは分析上の価値を何も追加せず、スキーマを煩雑にします。計算フィールドは、実際の計算（分類、抽出、演算）を行う場合にのみ保存してください。
• 大規模または複雑なフィールドに対する正規表現は避けてください — exception.stacktrace、db.statement、またはログ行全体に対して REG_MATCH、REG_VALUE、REG_COUNT を実行すると、非常に遅くなる可能性があります。まず、より的を絞った OTel フィールド（exception.type、exception.message、db.operation）が存在するか確認してください。長いフィールドにどうしても正規表現を使う必要がある場合は、先に CONTAINS チェックでガードしてください。
• EQUALS は厳密な型一致を行います — フィールドが文字列として保存されている場合、EQUALS($http.status_code, 200) は暗黙的に false を返します。比較する前に find_columns を使ってフィールドの型を確認してください。
• FORMAT_TIME は高コストです — 大量のクエリでは避けてください。
• 単発の作業にはデータセットレベルではなくクエリスコープで保存してください — 保存されたフィールドは全員のスキーマに表示されます。

完全な構文、演算子リファレンス、および拡張されたアンチパターンの例については、 ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/calculated-fields.md を参照してください。

すべてのクエリの前に

• ユーザー向けのレイテンシを計測するときは is_root でフィルタリングしてください — これがないと、内部スパンが数値を膨らませます
• 人間が読める時間範囲（"24h"、"-6h"）を使用してください — エポックタイムスタンプは間違いが起きやすく、レビューも困難です
• クエリの前に find_columns でカラムを検証してください — フィールド名が存在することを確認し、空の結果を防ぎます

結果の解釈

クエリを実行すると、MCP ツールは整形されたマークダウンとメタデータを返します。 最も重要なメタデータフィールドは query_result_json です — これは生の JSON 結果への署名付き URL です。正確な分析には、ASCII レンダリングだけに 頼るのではなく、これをダウンロードして jq や python でパースしてください。

主な解釈ルール:

• P99/P50 > 10x — 二峰性分布の可能性が高いため、確認のために HEATMAP を実行してください
• 内訳結果の TOTAL 行 = すべてのグループの集計
• OTHER 行 = クエリの上限を超えたグループ（OTHER が多い場合は上限を増やしてください）
• ASCII ヒートマップ ▁▂▃▄▅▆▇█ = 低から高への密度。2つの帯 = 2つの母集団
• メタデータ内の query_run_pk — 外れ値分析のために run_bubbleup に直接渡してください

追加リソース

参照ファイル

• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/visualize-operations.md — 例を交えた VISUALIZE 操作の完全リファレンス
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/relational-fields.md — クロスサービスパターンを交えたリレーショナルフィールドの詳細ガイド
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/query-examples.md — ユースケース別に整理された豊富なクエリクックブック
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/result-interpretation.md — クエリ結果の解釈、生の JSON アクセス、統計的ヒューリスティクスのガイド
• ${CLAUDE_PLUGIN_ROOT}/skills/query-patterns/references/calculated-fields.md — 計算フィールドの構文、演算子の完全リファレンス、一般的なパターンとアンチパターン（表示用フィールド、高コストな文字列操作、型の不一致）

相互参照

• これらのクエリパターンを使用する構造化された調査ワークフローについては: production-investigation スキル
• SLO の解釈とバーノアラートの設計については: slos-and-triggers スキル