sentry-setup-metrics

Sentry Metrics の設定

カウンター、ゲージ、分布を追跡するために、Sentry のカスタムメトリクスを設定します。

このスキルを使用する場面

• ユーザーが「Sentry のメトリクスを追加する」または「カスタムメトリクスを追跡する」と依頼した場合
• ユーザーがカウンター、ゲージ、分布を求めている場合
• ユーザーが Sentry.metrics または sentry_sdk.metrics について質問した場合

重要： 以下の SDK バージョン、API 名、コードサンプルは例です。API や最小バージョンが変更されている可能性があるため、実装する前に必ず docs.sentry.io で確認してください。

クイックリファレンス

サポート対象の SDK と最小バージョンの一覧は、Sentry Metrics Getting Started を確認してください。以下の例では、JavaScript と Python を使用しています。

プラットフォーム	最小 SDK	API	ステータス
JavaScript	10.25.0+	Sentry.metrics.*	オープンベータ
Python	2.44.0+	sentry_sdk.metrics.*	オープンベータ
Ruby	6.3.0+	Sentry.metrics.*	オープンベータ

メトリクスの種類

種類	用途	使用例
カウンター	累積カウント	API 呼び出し、クリック、エラー
ゲージ	特定時点の値	キューの深さ、メモリ、接続数
分布	統計値	応答時間、カートの金額

JavaScript の設定

SDK 10.25.0+ では、メトリクスはデフォルトで有効です。

カウンター

Sentry.metrics.count("api_call", 1, {
  attributes: { endpoint: "/api/users", status_code: 200 },
});

ゲージ

Sentry.metrics.gauge("queue_depth", 42, {
  unit: "none",
  attributes: { queue: "jobs" },
});

分布

Sentry.metrics.distribution("response_time", 187.5, {
  unit: "millisecond",
  attributes: { endpoint: "/api/products" },
});

フィルタリング（任意）

Sentry.init({
  beforeSendMetric: (metric) => {
    if (metric.attributes?.sensitive) return null;
    return metric;
  },
});

Python の設定

SDK 2.44.0+ では、メトリクスはデフォルトで有効です。

カウンター

sentry_sdk.metrics.count("api_call", 1, attributes={"endpoint": "/api/users"})

ゲージ

sentry_sdk.metrics.gauge("queue_depth", 42, attributes={"queue": "jobs"})

分布

sentry_sdk.metrics.distribution(
    "response_time", 187.5,
    unit="millisecond",
    attributes={"endpoint": "/api/products"}
)

フィルタリング（任意）

def before_send_metric(metric, hint):
    if metric.get("attributes", {}).get("sensitive"):
        return None
    return metric

sentry_sdk.init(dsn="YOUR_DSN", before_send_metric=before_send_metric)

一般的な単位

カテゴリー	値
時間	millisecond、second、minute、hour
サイズ	byte、kilobyte、megabyte
通貨	usd、eur、gbp
その他	none、percent、ratio

時間計測ヘルパーのパターン

JavaScript

async function withTiming(name, fn, attrs = {}) {
  const start = performance.now();
  try { return await fn(); }
  finally {
    Sentry.metrics.distribution(name, performance.now() - start, {
      unit: "millisecond", attributes: attrs,
    });
  }
}

Python

import time, sentry_sdk

def track_duration(name, **attrs):
    def decorator(fn):
        def wrapper(*args, **kwargs):
            start = time.time()
            try: return fn(*args, **kwargs)
            finally:
                sentry_sdk.metrics.distribution(
                    name, (time.time() - start) * 1000,
                    unit="millisecond", attributes=attrs
                )
        return wrapper
    return decorator

Ruby の設定

SDK 6.3.0+ では、メトリクスはデフォルトで有効です。

カウンター

Sentry.metrics.count("api_call", 1, attributes: { endpoint: "/api/users" })

ゲージ

Sentry.metrics.gauge("queue_depth", 42, attributes: { queue: "jobs" })

分布

Sentry.metrics.distribution("response_time", 187.5, unit: "millisecond", attributes: { endpoint: "/api/products" })

ベストプラクティス

• メトリクスあたり 2KB 未満に抑える：各メトリクスイベントのサイズ上限は 2KB です。属性セットは簡潔にしてください。
• 名前空間を含む名前を使用する：duration ではなく、api.request.duration を使用します。
• 終了時にフラッシュする：プロセスの終了前に Sentry.flush() を呼び出します。

確認

メトリクスを追加したら、それを出力するコードパスを実行し、Sentry の Metrics ダッシュボード（Explore > Metrics）を確認してください。バッファのフラッシュにより、メトリクスが表示されるまで数分かかる場合があります。

トラブルシューティング

問題	解決策
メトリクスが表示されない	SDK のバージョンを確認し、DSN を確認して、バッファがフラッシュされるまで待ちます
メトリクスが通知なく破棄される	メトリクスイベントが 2KB のサイズ上限以内か確認し、属性を減らします
メトリクスが多すぎる	beforeSendMetric を使用してフィルタリングします