custom-metrics

Vercel Custom Metrics

Vercel Function で実行されるサーバーサイドコードから出力される、アプリケーションやビジネスの数値測定には Custom Metrics を使用します。ワークフローは、metric() で数値サンプルを出力 → デプロイ済みの関数を呼び出す → vc metrics または Observability でメトリクスを検出してクエリする、という流れです。

メトリクスを出力する

@vercel/functions をインストールまたはアップグレードし、ルートエントリーポイントから metric をインポートします。

pnpm add @vercel/functions

import { metric } from '@vercel/functions';

export async function POST() {
  const startedAt = performance.now();

  try {
    await createOrder();
    metric('orders.created', 1, { outcome: 'success' });
    return Response.json({ ok: true });
  } catch (error) {
    metric('orders.created', 1, { outcome: 'error' });
    throw error;
  } finally {
    metric('orders.duration_ms', performance.now() - startedAt);
  }
}

シグネチャは次のとおりです。

metric(name: string, value: number, tags?: Record<string, string>): void

• name は、orders.created や orders.duration_ms など、安定した測定項目を識別します。
• value は数値サンプルです。合計する増分には 1 を出力し、所要時間、サイズ、スコアには観測値を出力します。
• tags は省略可能な文字列属性です。取り込み後、検出されたタグキーはフィルタリングやグループ化に使えるディメンションとして表示されます。
• metric() は同期的に実行され、void を返します。await は使用しないでください。
• ランタイムが Custom Metrics をサポートしていない場合、このヘルパーは何も行いません。計測が機能しているかは、ローカル実行だけでなく、デプロイ済みの Vercel Function の呼び出しで確認してください。

役立つクエリのためにメトリクスを設計する

• 可能であれば、単位のサフィックスを付けた、安定したドット区切りの名前を使用します。例：checkout.completed、checkout.duration_ms、queue.batch_size。
• アプリケーションで定義する名前に、予約済みの vercel. プレフィックスを使用しないでください。
• 変動するデータはメトリクス名ではなくタグに含めます。checkout.completed.pro ではなく、{ plan: 'pro' } を指定した checkout.completed を使用します。
• タグのカーディナリティを制限してください。適切なタグは outcome、plan、provider、正規化されたルートなどです。ユーザー ID、リクエスト ID、メールアドレス、生の URL、その他の一意または機密性の高い値は含めないでください。
• 結果が確定した時点で、サンプルを 1 つ出力します。再試行可能な処理や少なくとも 1 回実行される処理では、試行回数と成功した論理操作のどちらを測定するのかを決め、それに応じた名前を付けてください。

出力した値に合った集計方法を選びます。

測定項目	出力	クエリ
発生回数または増分	metric('checkout.completed', 1)	sum または persecond
所要時間またはサイズ	metric('checkout.duration_ms', duration)	avg、p75、p95、max
サンプリングされた値	metric('queue.batch_size', size)	avg、min、max、パーセンタイル

メトリクスを検出してクエリする

デプロイ済みのコードを少なくとも 1 回実行してから、リンク済みのプロジェクトと正しいチームスコープを使用します。

vc metrics schema
vc metrics schema orders.duration_ms

vc metrics orders.created -a sum --group-by outcome --since 24h
vc metrics orders.duration_ms -a p95 --since 1h
vc metrics orders.duration_ms -a p95 --group-by outcome --since 24h --format=json

vc と vercel は同等です。スキーマには利用可能な集計方法と検出されたタグディメンションが記載されているため、必ず最初に vc metrics schema <name> で対象のメトリクスを確認してください。現在のリンク先やスコープが曖昧な場合は -S <team> と -p <project> を使用し、チーム全体を対象にする意図がある場合に限り --all を使用してください。

Custom Metrics のクエリには Observability Plus が必要であり、選択したチームで利用可能である必要があります。メトリクスが見つからない場合は、次の点を確認してください。

1. 関数が Vercel にデプロイされ、計測対象のパスが実際に実行されたことを確認します。
2. @vercel/functions が metric をエクスポートしていることを確認します。必要であればアップグレードしてください。
3. vc whoami、選択されているチーム、リンク済みのプロジェクトを確認します。
4. 取り込みの遅延を考慮してから、vc metrics schema を再実行します。
5. チームで Observability Plus と Custom Metrics が有効になっていることを確認します。

適切なシグナルを選ぶ

• 集計、傾向の確認、フィルタリングを行う数値には、Custom Metrics を使用します。
• Web Analytics のユーザーインタラクションやコンバージョンイベントには、Web Analytics のカスタムイベントを使用します。
• トレース、操作時間、リクエストの因果関係には、OpenTelemetry spans を使用します。
• 詳細な診断コンテキストや個々の記録には、ログを使用します。

詳細なイベントペイロードをメトリクスタグに埋め込まないでください。リクエストごとの詳細な調査が必要な場合は、カーディナリティの低いメトリクスを構造化ログやトレースと併用します。