Performance Metrics

The SDK supports sending performance metrics data to Sentry. These are numeric values attached to transactions that are aggregated and displayed in Sentry.

Custom Measurements

In addition to automatic performance metrics, the SDK supports custom performance measurements on transactions.

Sentry supports custom performance measurements on transactions: you define measurements that matter to your application (for example, memory usage, query time, or user action counts) and send them with the transaction from your SDK. They appear in Dashboards, Discover, and transaction trace detail. You can define up to 10 custom measurements per transaction; any additional ones are truncated. Configure and send them in your SDK; supported platforms:

• Android (version 6.5.0 or later)
• Apple (version 7.28.0 or later)
• Dart (version 6.11.0 or later)
• Flutter (version 6.11.0 or later)
• Java (version 6.5.0 or later)
• JavaScript (version 7.0.0 or later)
• .NET (version 3.23.0 or later)
• Python (version 1.5.12 or later)
• React Native (version 4.0.0 or later)
• Ruby (version 5.8.0 or later)
• Rails (version 5.8.0 or later)

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-ruby version 5.8.0 and above.

transaction = Sentry.get_current_scope.get_transaction

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

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

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

Automatic Queue Time Capture

The Ruby SDK automatically captures queue time for Rack-based applications when the X-Request-Start header is present. This measures how long requests wait in the web server queue (e.g., waiting for a Puma thread) before your application begins processing them.

Queue time is attached to transactions as the http.server.request.time_in_queue attribute and helps identify server capacity issues. Tracing must be enabled for queue time to be captured.

Setup

Configure your reverse proxy to add the X-Request-Start header:

Nginx:

location / {
  proxy_pass http://your-app;
  proxy_set_header X-Request-Start "t=${msec}";
}

HAProxy:

frontend http-in
  http-request set-header X-Request-Start t=%Ts%ms

Heroku: The header is automatically set by Heroku's router.

How It Works

The SDK:

1. Reads the X-Request-Start header timestamp from your reverse proxy
2. Calculates the time difference between the header timestamp and when the request reaches your application
3. Subtracts puma.request_body_wait (if present) to exclude time spent waiting for slow client uploads
4. Attaches the result as http.server.request.time_in_queue to the transaction

Disable Queue Time Capture

If you don't want queue time captured, disable it in your configuration:

Sentry.init do |config|
  config.capture_queue_time = false
end

Supported Measurement Units

Units augment measurement 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.

Duration Units

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

Information Units

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

Fraction Units

• ratio
• percent

If you want to explore further, you can find details about supported units in our event ingestion documentation.