---
title: "Performance Metrics"
description: "Learn how to attach performance metrics to your transactions."
url: https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics/
---

# Performance Metrics | Sentry for Ruby

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](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#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)](https://docs.sentry.io/platforms/android/performance/instrumentation/performance-metrics.md)
* [Apple (version `7.28.0` or later)](https://docs.sentry.io/platforms/apple/performance/instrumentation/performance-metrics.md)
* [Dart (version `6.11.0` or later)](https://docs.sentry.io/platforms/dart/performance/instrumentation/performance-metrics.md)
* [Flutter (version `6.11.0` or later)](https://docs.sentry.io/platforms/dart/guides/flutter/performance/instrumentation/performance-metrics.md)
* [Java (version `6.5.0` or later)](https://docs.sentry.io/platforms/java/performance/instrumentation/performance-metrics.md)
* [JavaScript (version `7.0.0` or later)](https://docs.sentry.io/platforms/javascript/performance/instrumentation/performance-metrics.md)
* [.NET (version `3.23.0` or later)](https://docs.sentry.io/platforms/dotnet/performance/instrumentation/performance-metrics.md)
* [Python (version `1.5.12` or later)](https://docs.sentry.io/platforms/python/tracing/instrumentation/custom-instrumentation.md)
* [React Native (version `4.0.0` or later)](https://docs.sentry.io/platforms/react-native/performance/instrumentation/performance-metrics.md)
* [Ruby (version `5.8.0` or later)](https://docs.sentry.io/platforms/ruby/performance/instrumentation/performance-metrics.md)
* [Rails (version `5.8.0` or later)](https://docs.sentry.io/platforms/ruby/guides/rails/performance/instrumentation/performance-metrics.md)

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](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#supported-measurement-units).

Adding custom measurements is supported in `sentry-ruby` version `5.8.0` and above.

```ruby
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)
```

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.

## [Automatic Queue Time Capture](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#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](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#setup)

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

**Nginx:**

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

**HAProxy:**

```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](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#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](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#disable-queue-time-capture)

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

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

## [Supported Measurement Units](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#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](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#duration-units)

* `nanosecond`
* `microsecond`
* `millisecond`
* `second`
* `minute`
* `hour`
* `day`
* `week`

### [Information Units](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#information-units)

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

### [Fraction Units](https://docs.sentry.io/platforms/ruby/tracing/instrumentation/performance-metrics.md#fraction-units)

* `ratio`
* `percent`

If you want to explore further, you can find details about supported units in our [event ingestion documentation](https://getsentry.github.io/relay/relay_metrics/enum.MetricUnit.html).