Metrics

Metric processing MUST follow this order:

1. Capture metric via Public APIs (e.g. Sentry.metrics.count).
2. Check if metrics are disabled as per enableMetrics/enable_metrics configuration — if so, skip the rest of the steps.
3. Pass the metric to Hub/Scope via a generic method (e.g., captureMetric(metric)).
4. Pass the metric to the Client via a generic method (e.g., captureMetric(metric)).
5. Process captured metric (attach default attributes as per Default Attributes).
6. Run beforeSendMetric/before_send_metric to filter or modify the metric.
7. Add metric to buffer/batch processor as detailed in Buffering.
8. At time of flushing buffer, send array of metrics to Sentry via trace_metric envelope, apply rate limiting as per Data Category and Rate Limiting.

SDKs MUST attach the following attributes to every metric by default:

1. sentry.environment — the environment set in the SDK, if defined.
2. sentry.release — the release set in the SDK, if defined.
3. sentry.sdk.name — the name of the SDK that sent the metric.
4. sentry.sdk.version — the version of the SDK that sent the metric.

SDKs SHOULD minimize the number of default attributes. Metrics cardinality can explode quickly with too many attributes. New default attributes SHOULD only be added after significant feedback from users and discussion internally with the SDK and ingest teams.

SDKs MAY attach user information as attributes, guarded by sendDefaultPii (unless manually set by user, since 2.5.0):

1. user.id — the user ID. Maps to id in the User payload.
2. user.name — the username. Maps to username in the User payload.
3. user.email — the email address. Maps to email in the User payload.

By default, Relay parses the user agent attached to an incoming metric envelope to extract browser and os information. These attributes are attached by Relay, but client-side SDKs MAY attach them if they do not forward a user agent when sending metrics to Sentry.

1. browser.name — display name of the browser application. Maps to name in the Browser Context.
2. browser.version — version string of the browser. Maps to version in the Browser Context.

Backend SDKs (Node.js, Python, PHP, etc.) SHOULD attach the following attribute:

1. server.address — the address of the server that sent the metric. Equivalent to server_name attached to errors and transactions.

SDKs MUST buffer metrics before sending them (since 2.2.0, tightened from SHOULD). SDKs SHOULD flush the buffer when specific conditions are met. For initial implementation, a simple strategy is fine, for example: flushing if the buffer length exceeds 100 items or if 5 seconds have passed.

To prevent data loss, the buffer SHOULD forward metrics to the transport in the scenarios outlined in the telemetry buffer data forwarding scenarios (since 2.2.0).

Furthermore:

• The aggregation window SHOULD be time and size based.
• SDKs SHOULD implement safeguards to prevent excessive memory usage from metric buffering.

Metrics SHOULD be associated with traces if possible. If a metric is recorded during an active span, the SDK SHOULD set the span_id property of the metric to the span ID of the span that was active when the metric was collected.

The trace_id field is REQUIRED on every metric payload and MUST be taken from the current propagation context.

Whenever possible, metrics SHOULD be linked to replays. If a metric is recorded while an active, sampled replay is in progress, the SDK SHOULD attach:

1. sentry.replay_id — the ID of the replay that was active when the metric was collected. This MUST NOT be set if there was no active replay.
2. sentry._internal.replay_is_buffering — indicates that the metric is associated with a replay that is currently buffering. This ensures correct handling of scenarios where a replay_id is present but the corresponding replay was never actually sent.

The data category for metrics is trace_metric. Rate limiting applies as usual. SDKs SHOULD track client outcomes to monitor how often metrics are dropped. If the SDK receives a rate limit, it MUST NOT send any trace metrics until the limit expires (based on the communicated end timestamp).

If debug is set to true in SDK init, calls to the Sentry metrics API SHOULD also print to the console with appropriate details. This will help debugging metrics setups.

Metrics are sent as a trace_metric envelope item containing a JSON object with an items array. See the Examples section for a complete envelope.

An envelope MUST contain at most one trace_metric envelope item — all metrics for a flush are batched into a single item's items array. Metrics from different traces MAY be mixed into the same trace_metric item, but if they are, the envelope MUST NOT include a DSC (dynamic sampling context) header.

Item Headers:

{
	"type": "trace_metric",
	"item_count": 10,
	"content_type": "application/vnd.sentry.items.trace-metric+json"
}
{
	"items": [{..metric..}, {..metric..}, {..metric..}]
}

Each metric in the items array is a JSON object with the following fields:

{
  "timestamp": 1544719860.0,
  "trace_id": "5b8efff798038103d269b633813fc60c",
  "span_id": "b0e6f15b45c36b12",
  "name": "api.response_time",
  "value": 125.5,
  "unit": "millisecond",
  "type": "distribution",
  "attributes": {
    "endpoint": { "value": "api/users", "type": "string" },
    "method": { "value": "GET", "type": "string" },
    "status_code": { "value": 200, "type": "integer" }
  }
}

SDKs MUST expose the following configuration options:

• enableMetrics/enable_metrics — a boolean flag to control if metric envelopes will be generated and sent to Sentry. If false, the SDK MUST NOT send metrics. Defaults to true.

• beforeSendMetric/before_send_metric — an OPTIONAL function that takes a metric object and returns a metric object. Called before sending the metric to Sentry. Can be used to modify the metric or prevent it from being sent (by returning null/None).

While metrics functionality is in an experimental state, SDKs SHOULD put these options in an experimental namespace to avoid breaking changes:

Sentry.init({
  // stable
  enableMetrics: true,

  // experimental
  _experiments: { enableMetrics: true },
})

SDKs MUST expose metrics methods in a metrics module or namespace. At minimum, the SDK MUST implement the following methods:

• Sentry.metrics.count(name, value, options) — increment a counter
• Sentry.metrics.gauge(name, value, options) — set a gauge value
• Sentry.metrics.distribution(name, value, options) — add a distribution value

Parameters:

• name String, required — the name of the metric.
• value Number, required — the value of the metric.
• options Object, optional — containing:
  • unit String, optional — the unit of measurement (only used for distribution and gauge). SDKs MUST NOT restrict what can be sent in (e.g. by using an enum) but SHOULD offer constants or similar that help customers send in units we support (since 2.4.0).
  • attributes Object, optional — a dictionary of attributes (key-value pairs with type information).
  • scope Scope, optional — the scope to capture the metric with.

The Hub/Scope and Client MUST exclusively provide a generic method for capturing metrics (e.g., captureMetric(metric)). They MUST NOT replicate the static Sentry.metrics.X API methods to avoid increasing our API surface. Users utilizing multiple Hub/Scope or Clients will need to rely on the generic method for capturing metrics.