From 21fe43842a09756e16ccbd792bf245ecf6022988 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 28 Sep 2026 09:39:49 +0000 Subject: [PATCH 1/2] docs(sdk): Remove global metrics enablement from the spec Remove the global flag from the processing pipeline, initialization options, and automatic metrics rules while preserving integration opt-in and filtering. Bump the spec and changed sections to 3.0.0. Fixes SDK-1535 Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- develop-docs/sdk/telemetry/metrics.mdx | 44 ++++++++++---------------- 1 file changed, 17 insertions(+), 27 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index de05da51545f47..041856c79d28bf 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -2,7 +2,7 @@ title: Metrics description: Counter, gauge, and distribution metrics sent as batched trace_metric envelope items. spec_id: sdk/telemetry/metrics -spec_version: 2.11.0 +spec_version: 3.0.0 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/state-management/scopes/attributes version: ">=1.0.0" spec_changelog: + - version: 3.0.0 + date: 2026-09-28 + summary: Removed the global metrics enablement option; retained explicit opt-in for integrations - version: 2.11.0 date: 2026-09-22 summary: Added sentry.is_localhost default attribute for localhost inbound filtering @@ -107,20 +110,19 @@ An SDK **SHOULD** implement [Tracing without Performance](/sdk/foundations/trace - + ### Processing Pipeline Metric processing **MUST** follow this order: 1. Capture metric via [Public APIs](#metrics-module) (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](#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](#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](#data-category-and-rate-limiting). +2. Pass the metric to Hub/Scope via a generic method (e.g., `captureMetric(metric)`). +3. Pass the metric to the Client via a generic method (e.g., `captureMetric(metric)`). +4. Process captured metric (attach default attributes as per [Default Attributes](#default-attributes)). +5. Run `beforeSendMetric`/`before_send_metric` to filter or modify the metric. +6. Add metric to buffer/batch processor as detailed in [Buffering](#buffering). +7. 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](#data-category-and-rate-limiting). @@ -243,13 +245,11 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API **SHOUL - + ### Auto-Emitted Metrics -Metrics emitted via the [public API](#metrics-module) are opt-out. The `enableMetrics`/`enable_metrics` option **MUST** act as a general kill switch for all metrics sent to Sentry — when set to `false`, no metrics **MUST** be sent, regardless of whether they originate from the public API, auto-emitting integrations, or third-party bindings. - -However, metrics that are **automatically emitted by integrations or libraries** without an explicit user call follow different rules because they can generate unexpected volume and cost. +Metrics that are **automatically emitted by integrations or libraries** without an explicit user call require opt-in because they can generate unexpected volume and cost. **Integrations that auto-emit metrics** — An SDK integration that automatically captures metrics (e.g., recording HTTP request durations, database query counts, or runtime resource usage) **MUST** be opt-in. The integration **MUST NOT** emit any metrics unless the user explicitly enables it. The opt-in mechanism **MAY** be a dedicated integration-level option or requiring the user to explicitly add the integration. @@ -353,27 +353,17 @@ Each metric in the `items` array is a JSON object with the following fields: ## Public API - + ### Initialization Options -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`. +SDKs **MUST** expose the following configuration option: - `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: +While metrics functionality is in an experimental state, SDKs **SHOULD** put this option in an experimental namespace to avoid breaking changes. -``` -Sentry.init({ - // stable - enableMetrics: true, - - // experimental - _experiments: { enableMetrics: true }, -}) -``` +SDKs **SHOULD NOT** provide an API whose sole purpose is to disable all metrics. From a2b6ffa14e771dc6037948622f54a09d6e70db72 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 28 Sep 2026 09:45:13 +0000 Subject: [PATCH 2/2] docs(sdk): Remove obsolete metrics experimental guidance Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- develop-docs/sdk/telemetry/metrics.mdx | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index de05da51545f47..f8e5d5c46194db 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -2,7 +2,7 @@ title: Metrics description: Counter, gauge, and distribution metrics sent as batched trace_metric envelope items. spec_id: sdk/telemetry/metrics -spec_version: 2.11.0 +spec_version: 2.11.1 spec_status: stable spec_depends_on: - id: sdk/foundations/transport/envelopes @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/foundations/state-management/scopes/attributes version: ">=1.0.0" spec_changelog: + - version: 2.11.1 + date: 2026-09-28 + summary: Removed obsolete experimental namespace guidance and example from the stable spec - version: 2.11.0 date: 2026-09-22 summary: Added sentry.is_localhost default attribute for localhost inbound filtering @@ -363,18 +366,6 @@ SDKs **MUST** expose the following configuration options: - `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 }, -}) -``` -