query-metrics

Axiom メトリクスのクエリ

スクリプトのパスはすべてこのスキルのフォルダーからの相対パスです。scripts/<name> として実行してください。対象のデータセットは otel:metrics:v1 種別である必要があります。

セットアップ、前提条件、~/.axiom.toml の設定については、README.md を参照してください。エッジデプロイメントへのルーティングは自動です。スクリプトは各データセットの edgeDeployment を読み取り、設定なしで適切なリージョナルエンドポイントにルーティングします。

ワークフロー

1. scripts/datasets <deploy> --kind otel:metrics:v1 — メトリクスのデータセットを一覧表示します。
2. scripts/metrics-spec — クエリを作成する前に必ず実行してください。MPL は進化しているため、仕様が信頼できる情報源です。一般的な MPL／メトリクスに関する質問に答える場合も使用してください。
3. scripts/metrics-info <deploy> <dataset> metrics — {type, temporality, unit} メタデータとともにメトリクスを一覧表示します。クエリを作成する前に確認してください（クエリの形を選ぶを参照）。
4. scripts/metrics-info <deploy> <dataset> tags [<tag> values] — フィルターのディメンションを調べます。
5. scripts/metrics-query <deploy> '<MPL>' <start> <end> — 実行して、反復します。

ユーザーが特定のエンティティ（サービス、ホストなど）を指定した場合は、scripts/metrics-info <deploy> <dataset> find-metrics "<value>" で、そのエンティティを含むメトリクスを見つけます。find-metrics が検索するのはタグの値であり、メトリクス名ではありません。一般的な探索には使用しないでください。

クエリの形を選ぶ

metrics-info の一覧には、各メトリクスの {type, temporality, unit} が表示されます。クエリを作成する前に確認してください。メトリクスを単純なスカラー値だと決めつけてはいけません。

フィールド	値	影響
type	Gauge、CounterMonotonic、CounterNonMonotonic、Histogram	必要な事前集約オペレーター。
temporality	Cumulative、Delta、null	カウンター値が累積値か、各間隔の差分かを示します。null は Gauge では通常の値です。
unit	UCUM 文字列（Cel、kW.h、s、%、[ppm] など）または null	表示単位。結果を報告するときも維持してください。

種別ごとのルール（オペレーターの正確な名前は変更されるため、metrics-spec を参照してください）：

• Gauge — 瞬時値です。avg／min／max／sum と直接整列します。レートを適用しないでください。瞬時値の意味のない差分を平均することになります。
• CounterMonotonic + Cumulative — 累積値です（リセットは除きます）。生の値をそのまま使うことはほとんどありません。まず毎秒のレートに変換してから、整列／集約します。
• CounterMonotonic + Delta — すでに各間隔の値です。レートへの変換は行わず、合計／整列します。
• CounterNonMonotonic — 増減する可能性があります（キューの深さ、残高など）。レート、差分、現在値のどれを使うべきかは質問によって異なります。どれを選ぶかはユーザーに確認してください。
• Histogram — スカラー値ではありません。align using avg を使うと意味のない結果になります。metrics-spec にあるヒストグラム関数を使って bucket … using を使用してください。分位点はそれらの関数に渡す float 仕様であり、temporality によって使用するバリアント（Cumulative と Delta の補間）が選択されます。正確なシグネチャは metrics-spec を参照してください。
• temporality: null — 「この計測器種別には該当しない」という意味です（Gauge では通常の値です）。「データが欠落している」という意味ではありません。

数値を提示するときは unit を付記してください（null は単位なしとして扱います）。単位の異なるメトリクスを算術演算で組み合わせる場合は、意味のない数値を黙って生成するのではなく、警告してください。

メトリクスのクエリ

scripts/metrics-query [-w pixels] [--pixel-per-point n] <deploy> '<MPL>' <start> <end>

パラメーター	備考
deploy	~/.axiom.toml の名前（例：prod）。
MPL	パイプライン文字列。データセットは MPL 自体から解析されます。
start / end	RFC3339（2025-01-01T00:00:00Z）または相対指定（now-1h、now）。
-w / --chart-width <px>	任意。ピクセル単位の目標チャート幅です。サーバーが $__interval を解決できるようにします。
--pixel-per-point <n>	任意。1 点あたりのピクセル数です（サーバーのデフォルトは 10）。-w と併用するとバケット数を設定します。

シェルでは MPL 文字列を必ずシングルクォートで囲んでください。 MPL にはバッククォートが多く含まれています。ダブルクォートで囲むと、シェルがそれらをコマンド置換として実行し、クエリが気づかないうちに壊れる（または識別子の名前に対応するものが実行される）可能性があります。

グループ化の前に出力を制限してください。 group by <tag> はタグ値ごとに上限なく 1 つの系列を返すため、カーディナリティの高いタグでは出力が大量になります。まずカーディナリティを確認し（describe または tags <tag> values）、調査中は group using <agg> を使うことをおすすめします。

例：

scripts/metrics-query prod -w 1200 \
  '`my-dataset`:`http.server.duration` | align to $__interval using avg' \
  now-1h now

scripts/metrics-query prod -w 1200 \
  '`my-dataset`:`http.server.duration`
   | where `service.name` == "frontend" and method == "GET"
   | align to $__interval using avg
   | group by status_code using sum' \
  now-1d now

適応型の解像度（$__interval）

ステップを固定値（align to 5m）にすると、ズームレベルを変えたときにチャートの表示が不適切になります。拡大時は疎になりすぎ、縮小時は密になりすぎます。Duration が必要な箇所ではシステムパラメーター $__interval を使い、チャート幅を渡してサーバーにステップを選択させてください。

scripts/metrics-query prod -w 1200 \
  '`my-dataset`:`http.server.duration` | align to $__interval using avg' \
  now-7d now

メトリクスサービスは、クエリの時間範囲と目標チャート幅から $__interval を計算し、1s, 5s, 10s, 15s, 30s, 1m, 5m, 10m, 15m, 30m, 1h, 12h, 1d, 1w, 1M, 1Y の段階から適切な解像度へ切り上げます。メトリクスに保存されている解像度を下回ることはありません。

• 宣言は不要です — サーバーが $__interval を自動登録します。param $__interval: Duration; は追加しないでください（エッジはクエリをそのまま転送し、メトリクスサービスがパラメーターを挿入します）。
• バケット数 ≈ chart-width / pixel-per-point（pixel-per-point のデフォルトは 10）。-w を省略すると、サーバーは約 500 個のバケットを目標にします。
• bucket to $__interval using histogram(0.5, 0.95) のように、Duration が有効な箇所であればどこでも使えます。
• 描画幅（例：metrics-chart スキルのプロット幅）に合わせて -w を設定すると、1 つのバケットがほぼ 1 ピクセル列に対応します。この値はリクエスト本文の queryOptions（chart-width、pixel-per-point）に渡されます。

パラメーター

MPL ではパラメーターを宣言できます（param $svc: string;）。値は -p name=value を繰り返して渡します。スクリプトは API の param__ プレフィックスを適用し、値を MPL リテラルとしてそのまま転送します（文字列リテラルには引用符が含まれます）。

scripts/metrics-query \
  -p svc='"frontend"' \
  -p window='5m' \
  prod \
  'param $svc: string; param $window: Duration;
   `otel-metrics`:`http.server.duration` | where `service.name` == $svc | align to $window using avg' \
  now-1h now

必須パラメーターは指定する必要があります。任意のパラメーターは省略できます。リクエスト本文の形は次のとおりです。

{
  "apl": "param $svc: string; …",
  "startTime": "now-1h",
  "endTime": "now",
  "params": { "param__svc": "\"frontend\"", "param__window": "5m" }
}

各型のリテラル構文については metrics-spec を参照してください。

Discovery（metrics-info）

時間範囲のデフォルトは直近24時間です。--start／--end で上書きできます。どちらも RFC3339（オフセット可）、または相対指定の now／now-<N><unit> を受け付けます。<unit> には s m h d w を指定でき、クライアント側で RFC3339 UTC に解決されます。これは、時刻を解析せずにサーバーへ転送する metrics-query よりも範囲が狭くなっています。そのため、metrics-info では now／now-<N>[smhdw] 以外の形式は RFC3339 である必要があり、そうでない場合はリクエストが 400 エラーになります。

コマンド	戻り値
metrics-info <d> <ds> metrics	名前をキーとするすべてのメトリクスと、{type, temporality, unit}。
metrics-info <d> <ds> metrics --by-type	type ごとにグループ化した同じ一覧（クライアント側で再構成）。
metrics-info <d> <ds> metrics --type Gauge --type Histogram	絞り込んだ一覧（複数回指定可能、OR 条件。--by-type と併用できます）。
metrics-info <d> <ds> metrics <metric> info	単一メトリクスの {type, temporality, unit}。存在しない場合は終了コードが 0 以外になります。
metrics-info <d> <ds> metrics <metric> describe	メタデータ、すべてのタグ、タグ値を1回の呼び出しでまとめて取得します（1+1+N 回のラウンドトリップを置き換えます）。フラグ：--no-values（タグ名のみ）、--values-limit N（タグごとの値の上限。デフォルトは50、0 = 無制限）。
metrics-info <d> <ds> metrics <metric> tags	特定のメトリクスが持つタグ。
metrics-info <d> <ds> metrics <metric> tags <tag> values	そのメトリクスにおけるタグ値。
metrics-info <d> <ds> metrics <metric> tags <tag> type	タグが int／float／string／bool のどれかを調べます。{type, present_types} を返します。複数の型が共存する場合は mixed、存在しない場合は absent を返します。
metrics-info <d> <ds> tags	データセット内のすべてのタグ。
metrics-info <d> <ds> tags <tag> values	タグのすべての値（メトリクス全体）。
metrics-info <d> <ds> find-metrics "<value>"	指定したタグ 値 を持つメトリクス（メトリクス名ではありません）。

エラー処理

HTTP エラーは code と message を含む JSON を返します。一部には detail オブジェクトも含まれます。

{"code": 400, "message": "MPL syntax error: …"}

構文エラー（400）には、エラー位置で有効な演算子を示す注釈付きのソースポインターが含まれます。内容を確認してください。通常は修正方法が示されています。

コード	原因
400	クエリ構文が無効、またはデータセット名が不正
401	認証情報がない、または無効
403	権限がない
404	データセットが見つからない
429	レート制限中 — 待機してから再試行してください。短い間隔で繰り返さないでください
500	内部エラー

リクエストは120秒後にクライアント側でタイムアウトします（上書きするには AXIOM_MAX_TIME、10秒の接続タイムアウトには AXIOM_CONNECT_TIMEOUT を使用）。

500 エラーの場合は、curl -v で再実行して traceparent／x-axiom-trace-id ヘッダーを取得し、報告してください。バックエンドチームのデバッグに必要なのはトレース ID です。

スクリプト

スクリプト	使用方法
scripts/setup	要件と設定を確認します。
scripts/datasets <deploy> [--kind <kind>]	エッジデプロイメントのデータセットを一覧表示します。
scripts/metrics-spec	MPL クエリ仕様を取得します。
scripts/metrics-query [-w px] [--pixel-per-point n] <deploy> <mpl> <start> <end>	クエリを実行します。適応型解像度には $__interval と -w を使用してください。
scripts/metrics-info <deploy> <dataset> ...	メトリクス、タグ、値を検出します。
scripts/axiom-api <deploy> <method> <path> [body]	低レベルの API 呼び出しを行います。
scripts/resolve-url <deploy> <dataset>	エッジデプロイメントの URL を解決します。

各スクリプトは、引数なしで実行すると使用方法全体を表示します。