Performance Metrics

Learn how to attach performance metrics to your transactions.

Sentry's SDKs support sending performance metrics data to Sentry. These are numeric values attached to transactions that are aggregated and displayed in Sentry.

In addition to automatic performance metrics, the SDK supports setting custom performance measurements on transactions. This allows you to define measurements that are important to your application and send them to Sentry.

To set a performance measurement, you need to supply the following:

  • name (string)
  • value (any numeric type - float, integer, etc.)
  • unit (string, defaults to the string none if omitted)

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

Adding custom measurements is supported in Sentry's Python SDK version 1.16.0 and above.


To capture in the SDK:

from sentry_sdk import set_measurement

# Record amount of memory used
set_measurement('memory_used', 123, 'byte')

# Record time when job was started
set_measurement('job_start_time', 1.3, 'second')

# Record amount of times cache was read
set_measurement('cache_read_count', 4)

The feature was marked experimental between versions 1.5.12 and 1.16.0. To enable the capturing of custom measurements before 1.16.0, you'll need to enable the custom_measurements experiment option and fetch the transaction manually.

        "custom_measurements": True,  # for versions before 1.16.0

transaction = Hub.current.scope.transaction

if transaction:
    transaction.set_measurement('memory_used', 123, 'byte')

Currently, unit conversion is only supported once the data has already been stored. This means that, for example, ('myMeasurement', 60, 'second') and ('myMeasurement', 3, 'minute') would not be aggregated, but rather stored as two separate measurements. To avoid this, make sure to use a consistent unit when recording a custom measurement.

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").