Setup Sentry Metrics

Configure Sentry’s custom metrics for tracking counters, gauges, and distributions.

Invoke This Skill When

• User asks to “add Sentry metrics” or “track custom metrics”
• User wants counters, gauges, or distributions
• User asks about Sentry.metrics or sentry_sdk.metrics

Important: The SDK versions, API names, and code samples below are examples. Always verify against docs.sentry.io before implementing, as APIs and minimum versions may have changed.

Quick Reference

Check Sentry Metrics Getting Started for the full list of supported SDKs and minimum versions. Examples below use JavaScript and Python:

Metric Types

JavaScript Setup

Metrics are enabled by default in SDK 10.25.0+.

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" },
});

Filtering (optional)

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

Python Setup

Metrics are enabled by default in SDK 2.44.0+.

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"}
)

Filtering (optional)

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)

Common Units

Timing Helper Pattern

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 Setup

Metrics are enabled by default in SDK 6.3.0+.

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" })

Best Practices

• Stay under 2KB per metric: Each metric event has a 2KB size limit — keep attribute sets concise
• Namespaced names: api.request.duration, not duration
• Flush on exit: Call Sentry.flush() before process exit

Verification

After adding a metric, trigger the code path that emits it and check the Sentry Metrics dashboard (Explore > Metrics). Metrics may take a few minutes to appear due to buffer flushing.

Troubleshooting