metrics-queries

Honeycomb でのメトリクスクエリ

Honeycomb のメトリクスデータセットは、トレース/イベントデータセットとは動作が異なります。 トレースに対して機能する操作は、メトリクスでは失敗したり、誤解を招く結果を生じたりする可能性があります。 このスキルでは、そうした違いを解説し、正確で有用なメトリクスクエリを構築できるようにします。

メトリクスデータセットの見つけ方

メトリクスデータセットは、名前に「metrics」が含まれているかどうかで識別されるわけではありません。多くのイベント データセットのスラグには「metrics」が含まれています（例: kafka-metrics、refinery-metrics、 kubernetes-node-metrics）。これらは通常のイベントデータセットであり、メトリクスデータセットではありません。

実際のメトリクスデータセットを識別する方法:

1. get_environment を呼び出し、dataset_type = metrics となっている行を探します。 スラグは通常 metrics ですが、環境によって異なる場合があります。
2. あるいは、候補となるデータセットに対して get_dataset_columns を呼び出します — メトリクスデータセットは gauge、sum(cumulative,monotonic)、histogram(delta) といった型メタデータを示す MetricInfo カラムを返します。イベントデータセットにはこれがありません。

データセットを推測しないでください。 メトリクスクエリを構築する前に、必ず get_environment または get_dataset_columns で確認してください。ユーザーが「metrics」と言っていても、メトリクス風のフィールドを持つイベントデータセット （例: telegraf、system_stats）を指している場合、以下のクエリルールは適用されません — それらはイベントデータセットであり、query-patterns スキルの通常のクエリパターンに従います。

メトリクスとその属性の見つけ方

メトリクスデータセットは、イベントデータセットとは根本的に異なるスキーマを持っています。各メトリクス には、独自のリソース属性とデータポイント属性のセットがあります。同じデータセット内の 2 つのメトリクスでも、 フィルタリングやグルーピングに利用できる属性がまったく異なる場合があります。

何をクエリするかを発見するためのワークフロー:

1. メトリクス名を見つける: メトリクスデータセットに対して（metric_name を指定せずに） get_dataset_columns を呼び出します。これは MetricInfo 内に型とともにメトリクス名を返します。 特定のメトリクスを検索するには、キーワードを指定して find_columns を使用します（例: 「cpu」、「memory」、 「http request duration」）。

2. 特定のメトリクスの属性を見つける: クエリしたいメトリクスを metric_name パラメータに設定して get_dataset_columns を呼び出します（例: metric_name: "k8s.pod.memory.usage"）。これは、そのメトリクスと共起するリソース属性および データポイント属性を、サンプル値とともに返します。 これらが WHERE 句や GROUP BY 句で使用できるものです。

3. クエリ前に検証する: すべての属性がすべてのメトリクスに存在するわけではありません。フィルターや 内訳に追加する前に、必ず手順 2 で利用可能な属性を確認してください。

メトリクスデータセットで許可される操作と禁止される操作

以下の操作はメトリクスデータセットでは許可されていません:

禁止される操作	理由
COUNT（カラム指定なし）	メトリクスイベントをカウントするのであって、メトリクス値をカウントするのではない — メトリクスにとって無意味
RATE_SUM	メトリクスデータセットではサポートされていません
RATE_AVG	メトリクスデータセットではサポートされていません
RATE_MAX	メトリクスデータセットではサポートされていません
CONCURRENCY	スパン期間が必要ですが、メトリクスには期間がありません

代わりにこれらを使用してください:

目的	メトリクスで使用するもの
gauge 値を可視化する	AVG(metric)、MAX(metric)、HEATMAP(metric)
カウンター/サムを可視化する	SUM(metric)、AVG(metric)、MAX(metric)
値の分布を確認する	HEATMAP(metric)、P50(metric)、P99(metric)
1 秒あたりの変化率を追跡する	計算フィールドで時間集計を上書きする（以下を参照）
パーセンタイル分析	P50(metric)、P90(metric)、P99(metric)
null 以外の値のカウント	COUNT(metric)（カラムを指定した場合）

メトリクスの型と時間集計

Honeycomb は、生のメトリクス値をクエリのタイムステップに合わせるために、時間集計を自動的に適用します。 適用される関数はメトリクスの型によって異なり、get_dataset_columns の MetricInfo カラムで確認できます。

メトリクスタイプごとのデフォルトの時間集計

MetricInfo	型	デフォルト関数	動作
gauge	ゲージ	LAST()	タイムステップごとに直近の値を返します
sum(cumulative,monotonic)	単調累積合計	INCREASE()	ステップ間の変化を計算し、カウンターのリセットを処理します
sum(cumulative)	非単調累積合計	LAST()	直近の値（増加も減少もあり得ます）
sum(delta) または sum(delta,monotonic)	デルタ合計	SUMMARIZE()	各ステップ内のすべての値を合計します
histogram(cumulative)	累積ヒストグラム	INCREASE()	ステップ間のバケットごとの変化
histogram(delta)	デルタヒストグラム	SUMMARIZE()	各ステップ内のバケット値を合計します

これらのデフォルトは自動的に適用されます — 設定する必要はありません。 メトリクスデータセットで AVG、MAX、P99 などから得られる結果は、すでに 時間集計が最初に適用されたものを反映しています。

時間集計の上書き

デフォルトを上書きするには（たとえば、累積カウンターに対して INCREASE ではなく RATE を確認したい場合）、 メトリクス名を時間集計関数でラップした クエリスコープの計算フィールド を使用し、 そのフィールドに calculations で空間集計を適用します。

{
  "calculated_fields": [
    { "name": "req_rate", "expression": "RATE($http.server.requests, 300)" }
  ],
  "calculations": [
    { "op": "AVG", "column": "req_rate" }
  ]
}

計算フィールドでサポートされる時間集計関数:

• LAST($metric) — ステップごとの直近のデータポイント（ゲージ、非単調合計）
• SUMMARIZE($metric) — 補間を行いながらステップごとにすべての値を合計します（デルタメトリクス）
• INCREASE($metric[, range_interval_seconds]) — 範囲全体での値の変化を計算し、カウンターのリセットを処理します
• RATE($metric[, range_interval_seconds]) — 1 秒あたりの変化率（INCREASE / time）

オプションの range_interval_seconds パラメータ（整数、秒単位）は、変化を計算するための ルックバックウィンドウを制御します。結果を平滑化したり、疎なデータを補正したりするために使用します。 省略した場合、クエリの粒度が範囲間隔として使用されます。

重要: 計算フィールドには calculations で空間集計（AVG、SUM、P99、HEATMAP など）を 引き続き適用する必要があります。時間集計関数だけでは可視化は生成されません — 生のメトリクス値を変換し、その後で空間集計がタイムシリーズ全体を集約します。

時間集計関数、カウンターリセットの処理、range_interval_seconds の詳細なリファレンスについては、 次を参照してください: ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/temporal-aggregation.md

ヒストグラムメトリクスのクエリ

OpenTelemetry のヒストグラムは、サブフィールドのコレクションとして保存されます。http.server.duration という名前の ヒストグラムの場合、Honeycomb は次を作成します:

フィールド	意味
http.server.duration.count	データポイントの総数
http.server.duration.sum	すべての値の合計
http.server.duration.avg	平均値（sum/count）
http.server.duration.p50	中央値（50 パーセンタイル）
http.server.duration.p99	99 パーセンタイル
http.server.duration.p001 から .p999	パーセンタイルの全範囲

ヒストグラムをクエリする 2 つの方法:

1. パーセンタイルまたは分布演算で親カラム名を直接使用する。 これが推奨されるアプローチです:

   { "op": "P99", "column": "http.server.duration" }
   

   { "op": "HEATMAP", "column": "http.server.duration" }
   

2. ステップ内のすべてのタイムシリーズにわたる最悪ケースの事前計算済みパーセンタイルを 取得したい場合は、サブフィールドを MAX とともに使用する:

   { "op": "MAX", "column": "http.server.duration.p99" }
   

   これは、そのタイムステップ内の単一のタイムシリーズが報告した最高の p99 値を返します。 これは、すべてのデータにわたって 99 パーセンタイルを計算する P99(http.server.duration) とは異なります。

どちらをいつ使うか:

• ほとんどの分析では: P99(parent_column) または HEATMAP(parent_column) を使用します
• ホストやポッド全体の最悪ケースの境界には: MAX(parent_column.p99) を使用します
• ヒストグラムからのスループットには: SUM(parent_column.count) または AVG(parent_column.count) を使用します

メトリクスを使用したクエリ演算

クエリ演算（名前付き計算と数式を含む複合クエリ）は、イベントデータセットと同様にメトリクスデータセットでも機能します。計算に名前を付け、必要に応じて計算ごとのフィルターを追加し、それらを組み合わせる数式を定義します。

一般的なメトリクスの数式パターン:

使用率のパーセンテージ

{
  "calculations": [
    { "op": "AVG", "column": "k8s.pod.memory.usage", "name": "used" },
    { "op": "AVG", "column": "k8s.pod.memory.available", "name": "available" }
  ],
  "formulas": [
    { "name": "utilization_pct", "expression": "$used / ($used + $available) * 100" }
  ],
  "breakdowns": ["k8s.pod.name"],
  "orders": [{ "column": "utilization_pct", "order": "descending" }],
  "limit": 20
}

ヒストグラムのテール比率

{
  "calculations": [
    { "op": "P50", "column": "http.server.duration", "name": "median" },
    { "op": "P99", "column": "http.server.duration", "name": "tail" }
  ],
  "formulas": [
    { "name": "tail_ratio", "expression": "$tail / $median" }
  ],
  "breakdowns": ["service.name"]
}

カウンターからのエラー率（時間集計のオーバーライドあり）

{
  "calculated_fields": [
    { "name": "error_rate", "expression": "RATE($http.server.errors)" },
    { "name": "request_rate", "expression": "RATE($http.server.requests)" }
  ],
  "calculations": [
    { "op": "SUM", "column": "error_rate", "name": "errors_per_sec" },
    { "op": "SUM", "column": "request_rate", "name": "requests_per_sec" }
  ],
  "formulas": [
    { "name": "error_pct", "expression": "$errors_per_sec / $requests_per_sec * 100" }
  ]
}

その他のクエリ例については、以下を参照してください: ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/metrics-query-examples.md

メトリクスの粒度

メトリクスは既知の一定間隔（例: 10秒、30秒、60秒ごと）で到着します。粒度はトレースよりもメトリクスにとって重要です:

• 粒度をレポート間隔に合わせてください。 メトリクスが60秒ごとにレポートされる場合、60で割り切れる粒度（例: 60、120、300）を使用してください。粒度がずれているとバケットサイズが不均一になり、ノイズの多い結果が生じます。
• スパイクのように見えるグラフは通常、粒度がレポート間隔よりも細かいことを意味します。粒度を大きくするか、UI で「Omit Missing Values」を有効にして連続した線を生成してください。
• RATE 演算と粒度: RATE_SUM（イベントデータセット上）は粒度の選択に特に敏感です — バケットあたりのデータポイントが一貫していないと、結果が変動します。

よくある落とし穴

1. メトリクスに対して COUNT を使用する。 COUNT はメトリクスイベントの数をカウントするのであり、メトリクスの値ではありません。代わりに AVG、SUM、MAX、または HEATMAP を使用してください。
2. メトリクスデータセットに対して RATE_AVG/RATE_SUM/RATE_MAX を使用する。 これらは許可されていません。レートを取得するには、RATE($metric) を使用した計算フィールドを作成し、その後 AVG や SUM などの空間集計を適用してください。
3. すべてのメトリクスが同じ属性を共有していると仮定する。 各メトリクスには独自のリソース属性とデータポイント属性のセットがあります。フィルターや内訳を追加する前に、特定のメトリクスで何が利用可能かを確認するため、常に metric_name を指定して get_dataset_columns を呼び出してください。
4. イベントデータセットとメトリクスデータセットを混同する。 kafka-metrics、refinery-metrics などの名前のデータセットはイベントデータセットです。get_environment の dataset_type を確認してください。
5. 親カラムが機能するのにヒストグラムのサブフィールドをクエリする。 特に最悪ケースの境界が必要でない限り、AVG(http.server.duration.p99) ではなく P99(http.server.duration) を使用してください。
6. 集計関数を指定しない。 SELECT に空間集計がないメトリクスクエリはデフォルトで COUNT になりますが、これはメトリクスにとって無意味です。

その他のリソース

リファレンスファイル

• ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/metrics-query-examples.md — 一般的なシナリオ向けの run_query 例を含むメトリクスクエリクックブック
• ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/temporal-aggregation.md — 時間集計関数、カウンターリセット、range_interval_seconds に関する詳細リファレンス
• ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/metric-types.md — OpenTelemetry のメトリクスタイプ、それらが Honeycomb にどのようにマッピングされるか、MetricInfo の値の意味

クロスリファレンス

• 一般的なクエリ構築パターン（計算フィールド、リレーショナルフィールド、結果の解釈）については: query-patterns スキル
• トレースとともにメトリクスを使用して本番環境の問題を調査するには: production-investigation スキル
• SLO の解釈とバーンアラートの設計については: slos-and-triggers スキル
• メトリクスを送信するためにアプリケーションを計装するには: otel-instrumentation スキル