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

Quick Reference

Platform	Min SDK	API
JavaScript	10.25.0+	Sentry.metrics.*
Python	2.44.0+	sentry_sdk.metrics.*

Note: Ruby does not have metrics support.

Metric Types

Type	Purpose	Example Use Cases
Counter	Cumulative counts	API calls, clicks, errors
Gauge	Point-in-time values	Queue depth, memory, connections
Distribution	Statistical values	Response times, cart amounts

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

Category	Values
Time	millisecond, second, minute, hour
Size	byte, kilobyte, megabyte
Currency	usd, eur, gbp
Other	none, percent, ratio

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

Best Practices

• Low cardinality: Avoid user IDs, request IDs in attributes
• Namespaced names: api.request.duration, not duration
• Flush on exit: Call Sentry.flush() before process exit

Troubleshooting

Issue	Solution
Metrics not appearing	Verify SDK version, check DSN, wait for buffer flush
High cardinality warning	Remove unique IDs from attributes
Too many metrics	Use beforeSendMetric to filter