Axiom Metrics のクエリ

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

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

ワークフロー

1. scripts/datasets <deploy> --kind otel:metrics:v1 — メトリクスデータセットを一覧表示します。
2. scripts/metrics-spec <deploy> <dataset> — クエリを作成する前に必須。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 — 上下に変動可（キューの深さ、残高）。意図は曖昧です。レート、デルタ、または現在値がすべて異なる質問に対して意味があります。ユーザーに尋ねてから 1 つを選択します。
• Histogram — スカラーではありません。align using avg は無意味な結果を生成します。metrics-spec のバケット/分位数オペレータを使用してください。
• temporality: null — 「このインストルメント型には適用されない」（Gauge の標準）。「データ不足」ではありません。

数値を表示する際は、unit を添付してください（null を単位なしとして扱う）。異なる単位を持つメトリクスを演算で組み合わせる場合は、無意味な数値を無言で生成するのではなく、警告してください。

メトリクスのクエリ

scripts/metrics-query <deploy> '<MPL>' <start> <end>

パラメータ	備考
deploy	~/.axiom.toml の名前（例：prod）。
MPL	パイプライン文字列。データセットは MPL 自体から解析されます。
start / end	RFC3339（2025-01-01T00:00:00Z）または相対的（now-1h、now）。

例：

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

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

パラメータ

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 にあります。

発見（metrics-info）

時間範囲はデフォルトで過去 24 時間。--start / --end でオーバーライドします。

コマンド	戻り値
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}。不在の場合は非ゼロ終了。
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 エラーは message、code、オプションの detail を含む JSON を返します：

{"message": "...", "code": 400, "detail": {"errorType": 1, "message": "raw error"}}

コード	原因
400	クエリ構文が無効またはデータセット名が不良
401	認証がない/無効
403	アクセス権限なし
404	データセットが見つからない
429	レート制限
500	内部エラー

500 の場合、curl -v で再実行して traceparent / x-axiom-trace-id ヘッダーをキャプチャして報告してください。トレース ID がバックエンドチームがデバッグに必要とするものです。

スクリプト

スクリプト	使用方法
scripts/setup	要件と設定を確認します。
scripts/datasets <deploy> [--kind <kind>]	エッジデプロイメント付きでデータセットを一覧表示します。
scripts/metrics-spec <deploy> <dataset>	MPL クエリスペックを取得します。
scripts/metrics-query <deploy> <mpl> <start> <end>	クエリを実行します。
scripts/metrics-info <deploy> <dataset> ...	メトリクス、タグ、値を発見します。
scripts/axiom-api <deploy> <method> <path> [body]	低レベル API 呼び出し。
scripts/resolve-url <deploy> <dataset>	エッジデプロイメント URL に解決します。

任意のスクリプトを引数なしで実行すると、完全な使用方法が表示されます。