sentry-setup-metrics

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:

Platform	Min SDK	API	Status
JavaScript	10.25.0+	Sentry.metrics.*	Open Beta
Python	2.44.0+	sentry_sdk.metrics.*	Open Beta
Ruby	6.3.0+	Sentry.metrics.*	Open Beta

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

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

Issue	Solution
Metrics not appearing	Verify SDK version, check DSN, wait for buffer flush
Metric dropped silently	Check that metric event is under 2KB size limit — reduce attributes
Too many metrics	Use beforeSendMetric to filter