Track custom numeric measurements from your application using counters, gauges, distributions, and sets.
Sentry Metrics lets you instrument your application with custom numeric measurements and visualize them over time. Unlike errors or transactions (which capture individual events), metrics are aggregated server-side, making them suitable for high-cardinality data points that would be too expensive to store as individual events.
Tracks how many times something happened. Supports increment(). Use for counting events like successful payments, cache hits, or feature flag evaluations.
Gauge
Tracks the current value of something that goes up and down. Reports min, max, last, sum, and count. Use for queue depth, active connections, or memory usage.
Distribution
Records the statistical distribution of values. Supports percentile queries (p50, p75, p95, p99). Use for request durations, payload sizes, or DB query times.
Set
Counts unique occurrences. Use for counting unique users who triggered an event or unique session IDs in a time window.
import sentry_sdk# Counter: increment by 1 (default) or a custom valuesentry_sdk.metrics.incr( key="checkout.button.clicked", value=1, tags={"variant": "blue", "environment": "production"},)# Distribution: record a value for percentile analysissentry_sdk.metrics.distribution( key="api.response_time", value=142.5, unit="millisecond", tags={"endpoint": "/api/checkout"},)# Gauge: set the current valuesentry_sdk.metrics.gauge( key="queue.depth", value=73, tags={"queue": "email"},)# Set: track unique valuessentry_sdk.metrics.set( key="active.users", value=user.id, tags={"plan": "pro"},)
Sentry applies cardinality limits to protect query performance. A high-cardinality tag (for example, using a user ID or request ID as a tag value) can create millions of unique time series, which degrades performance and increases cost.
Do not use high-cardinality values as metric tags. User IDs, session IDs, request IDs, and UUIDs should never be tag values. Use them as the value of a Set metric instead if you need to count unique occurrences.
Sentry enforces cardinality limits per use case. When a metric exceeds the limit, new time series for that metric are dropped until cardinality drops below the threshold.
Metrics are ingested through the Sentry SDK → Relay → Kafka → Snuba pipeline. Relay aggregates raw metric samples into buckets (typically 10-second windows) before forwarding them, which significantly reduces the volume of data sent to Snuba. Snuba stores the pre-aggregated buckets in ClickHouse where they can be queried efficiently.
