Set Up Metrics

Learn how to measure the data points you care about by configuring Metrics in your Python app.

Metrics for Python are supported with Sentry Python SDK version 1.40.0 and above.

Sentry metrics help you pinpoint and solve issues that impact user experience and app performance by measuring the data points that are important to you. You can track things like processing time, event size, user signups, and conversion rates, then correlate them back to tracing data in order to get deeper insights and solve issues faster.

Metrics is supported out of the box, so you don't need to do anything to enable it. There are some experimental options you can use to influence metrics behavior.

Counters are one of the more basic types of metrics and can be used to count certain event occurrences.

To emit a counter, do the following:

Copied
# Increment a counter by one for each button click.
sentry_sdk.metrics.incr(
	key="button_click",
	value=1,
	tags={
		"browser": "Firefox",
		"app_version": "1.0.0"
	}
)

Distributions help you get the most insights from your data by allowing you to obtain aggregations such as p90, min, max, and avg.

To emit a distribution, do the following:

Copied
# Add '15.0' to a distribution used for tracking the loading times per page.
sentry_sdk.metrics.distribution(
	key="page_load",
	value=15.0,
	unit="millisecond",
	tags={
		"page": "/home"
	}
)

Sentry supports arbitrary custom values for unit, but we recommend using one of the supported units listed below.

Sets are useful for looking at unique occurrences and counting the unique elements you added.

To emit a set, do the following:

Copied
# Add 'jane' to a set used for tracking the number of users that viewed a page.
sentry_sdk.metrics.set(
	key="user_view",
	value="jane",
	unit="username",
	tags={
		"page": "/home"
	}
)

Sentry supports arbitrary custom values for unit, but we recommend using one of the supported units listed below.

Gauges let you obtain aggregates like min, max, avg, sum, and count. They can be represented in a more space-efficient way than distributions, but they can't be used to get percentiles. If percentiles aren't important to you, we recommend using gauges.

To emit a gauge, do the following:

Copied
# Add '15.0' to a gauge used for tracking the loading times for a page.
sentry_sdk.metrics.gauge(
	key="page_load",
	value=15.0,
	unit="millisecond",
	tags={
		"page": "/home"
	}
)

Sentry supports arbitrary custom values for unit, but we recommend using one of the supported units listed below.

Timers can be used to measure the execution time of a specific block of code. They're implemented like distributions, but measured in seconds.

To emit a timer, do the following:

Copied
# Measure the time of execution of the `process()` function.
with sentry_sdk.metrics.timing(key="event_processing_time"):
	process()

You can use the following options to set/change the behavior of Metrics. As Metrics is still in the beta phase, these options are under the _experiments option.

before_emit_metric

A callback function that is called before a metric is emitted. If the callback returns True the metric is emitted. If the callback returns False the metric is not emitted. The given tags can also be updated in the callback function.

Copied
def before_emit(key, value, unit, tags):
    if key == "removed-metric":
        return False
    tags["extra"] = "foo"
    del tags["release"]
    return True

sentry_sdk.init(
    ...
    _experiments={
        "before_emit_metric": before_emit,
    }
)

metric_code_locations

If True, the line of code where the metric was emitted will be added to the metric. If False, the code location will be omitted.

Default: True

Copied
sentry_sdk.init(
	...
    _experiments={
		"metric_code_locations": False,
	}
)

Units augment metric values by giving meaning to what otherwise might be abstract numbers. Adding units also allows Sentry to offer controls - unit conversions, filters, and so on - based on those units. For values that are unitless, you can supply an empty string or none.

  • nanosecond
  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • week

  • bit
  • byte
  • kilobyte
  • kibibyte
  • megabyte
  • mebibyte
  • gigabyte
  • gibibyte
  • terabyte
  • tebibyte
  • petabyte
  • pebibyte
  • exabyte
  • exbibyte

  • ratio
  • percent

For more details about supported units, see our event ingestion documentation.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").