Set Up Metrics

With Sentry Metrics, you can send counters, gauges and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.

Requirements

Metrics for Python are supported in Sentry Python SDK version 2.44.0 and above.

pip install "sentry-sdk"

Usage

Once the feature is enabled on the SDK and the SDK is initialized, you can send metrics using the sentry_sdk.metrics APIs.

The metrics namespace exposes three methods that you can use to capture different types of metric information: count, gauge, and distribution.

from sentry_sdk import metrics

metrics.count("checkout.failed", 1)
metrics.gauge("queue.depth", 42)
metrics.distribution("cart.amount_usd", 187.5)

You can also pass additional attributes directly to count, gauge, and distribution via the attributes kwarg.

from sentry_sdk import metrics

metrics.count(
    "checkout.failed",
    1,
    attributes={
        "route": "/checkout",
        "tenant": "acme",
        "provider": "stripe",
    },
)

Options

before_send_metric

To filter metrics, or update them before they are sent to Sentry, you can use the before_send_metric option.

import sentry_sdk
from sentry_sdk.types import Metric, Hint
from typing import Optional

def before_metric(metric: Metric, _hint: Hint) -> Optional[Metric]:
    # Filter out all failed checkouts on the acme tenant
    if metric["name"] == "checkout.failed" and metric["attributes"].get("tenant") == "acme":
        return None

    return metric

sentry_sdk.init(
    dsn="___PUBLIC_DSN___",
    before_send_metric=before_metric,
)

The before_send_metric function receives a metric object, and should return the metric object if you want it to be sent to Sentry, or None if you want to discard it.

The metric dict has the following keys:

• name: (str) The name of the metric.
• type: (str - one of counter, gauge, distribution) The type of metric.
• value: (float) The numeric value of the metric.
• unit: (Optional[str]) The unit of measurement for the metric value.
• attributes: (dict[str, str | bool | float | int]) Additional attributes to be sent with the metric.
• timestamp: (float) Timestamp in seconds (epoch time) indicating when the metric was recorded.
• trace_id: (Optional[str]) The trace ID of the trace this metric belongs to.
• span_id: (Optional[str]) The span id of the span that was active when the metric was emitted.

Default Attributes

The Python SDK automatically sets several default attributes on all metrics to provide context and improve debugging:

Core Attributes

• environment: The environment set in the SDK if defined. This is sent from the SDK as sentry.environment.
• release: The release set in the SDK if defined. This is sent from the SDK as sentry.release.
• trace.parent_span_id: The span ID of the span that was active when the metric was collected (only set if there was an active span). This is sent from the SDK as sentry.trace.parent_span_id.
• sdk.name: The name of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.name.
• sdk.version: The version of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.version.

Server Attributes

• server.address: The address of the server that sent the metric. Equivalent to server_name that gets attached to Sentry errors.

User Attributes

If user information is available in the current scope, the following attributes are added to the metric:

• user.id: The user ID.
• user.name: The username.
• user.email: The email address.