sentry-setup-metrics

设置 Sentry Metrics

配置 Sentry 的自定义 metrics，用于跟踪计数器、仪表和分布。

何时调用此 Skill

• 用户要求“添加 Sentry metrics”或“跟踪自定义 metrics”
• 用户想要计数器、仪表或分布
• 用户询问 Sentry.metrics 或 sentry_sdk.metrics

重要： 下面的 SDK 版本、API 名称和代码示例仅供参考。实现前请务必对照 docs.sentry.io 核实，因为 API 和最低版本可能已发生变化。

快速参考

查看 Sentry Metrics 入门 以获取支持的 SDK 和最低版本的完整列表。下面的示例使用 JavaScript 和 Python：

平台	最低 SDK	API	状态
JavaScript	10.25.0+	Sentry.metrics.*	开放 Beta
Python	2.44.0+	sentry_sdk.metrics.*	开放 Beta
Ruby	6.3.0+	Sentry.metrics.*	开放 Beta

Metric 类型

类型	用途	示例用例
Counter	累计计数	API 调用、点击、错误
Gauge	时间点值	队列深度、内存、连接数
Distribution	统计值	响应时间、购物车金额

JavaScript 设置

在 SDK 10.25.0+ 中，Metrics 默认启用。

Counter

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

Gauge

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

Distribution

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+ 中，Metrics 默认启用。

Counter

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

Gauge

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

Distribution

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+ 中，Metrics 默认启用。

Counter

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

Gauge

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

Distribution

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

最佳实践

• 每个 metric 保持在 2KB 以下：每个 metric 事件有 2KB 的大小限制——保持属性集简洁
• 使用命名空间名称：api.request.duration，而不是 duration
• 退出时刷新：在进程退出前调用 Sentry.flush()

验证

添加 metric 后，触发发出该 metric 的代码路径，并检查 Sentry Metrics 仪表板（Explore > Metrics）。由于缓冲区刷新，metrics 可能需要几分钟才会出现。

故障排除

问题	解决方案
Metrics 未出现	验证 SDK 版本，检查 DSN，等待缓冲区刷新
Metric 被静默丢弃	检查 metric 事件是否低于 2KB 大小限制——减少属性
Metrics 过多	使用 beforeSendMetric 进行过滤