From 3957c4f61c37e1b87434ee80e7324271676a4e19 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 10 Oct 2025 12:09:56 +0200 Subject: [PATCH 01/21] add metrics docs --- .../sdk/data-model/envelope-items.mdx | 42 ++ develop-docs/sdk/telemetry/feedbacks.mdx | 2 +- develop-docs/sdk/telemetry/metrics.mdx | 551 ++++++++++++++++++ develop-docs/sdk/telemetry/profiles/index.mdx | 2 +- develop-docs/sdk/telemetry/replays.mdx | 2 +- develop-docs/sdk/telemetry/sessions/index.mdx | 2 +- develop-docs/sdk/telemetry/spans/index.mdx | 2 +- develop-docs/sdk/telemetry/traces/index.mdx | 2 +- 8 files changed, 599 insertions(+), 6 deletions(-) create mode 100644 develop-docs/sdk/telemetry/metrics.mdx diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index bde96cf511202..8fa9e5169bb4c 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -457,6 +457,48 @@ _None_ _None_ +### Trace Metric + +Item type `"trace_metric"` contains an array of metric payloads encoded as JSON. This allows for multiple metric payloads to be sent in a single envelope item. + +Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`. + +It's okay to mix metrics from different traces into the same trace_metric envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header. + +See the Metrics documentation for the payload +details. For an example `trace_metric` envelope, see [Appendix A of the Metrics documentation](/sdk/telemetry/metrics#appendix-a-example-trace_metric-envelope). + +Example: + +```json +{ + "type": "trace_metric", + "item_count": 5, + "content_type": "application/vnd.sentry.items.trace_metric+json" +} +{ + "items": [{..metric..}, {..metric..}, {..metric..}, {..metric..}, {..metric..}] +} +``` + +**Constraints:** + +_None_ + +**Envelope Headers:** + +_None_ + +**Additional Item Headers:** + +`item_count` + +: **integer, required.** The number of metric entries in the envelope. + +`content_type` + +: **string, required.** The content type of the metric entries. Must be `application/vnd.sentry.items.trace_metric+json`. + ### Reserved Types Reserved types may not be written by any implementation. They are reserved for diff --git a/develop-docs/sdk/telemetry/feedbacks.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx index 7bf08d86a8f26..468ba690c43a1 100644 --- a/develop-docs/sdk/telemetry/feedbacks.mdx +++ b/develop-docs/sdk/telemetry/feedbacks.mdx @@ -1,6 +1,6 @@ --- title: Feedbacks -sidebar_order: 4 +sidebar_order: 5 --- This document is meant for Sentry SDK developers and maintainers of the Feedback ingestion pipeline. diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx new file mode 100644 index 0000000000000..fbd805f7dcc6c --- /dev/null +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -0,0 +1,551 @@ +--- +title: Metrics +sidebar_order: 4 +--- + + + +The Sentry Metrics feature is under active development. The information in this document is subject to change. + + + +This document defines the format used by Sentry to ingest metrics, as well as the SDK API and behavior that create and send metrics to Sentry. + + + +The envelope item type is named `trace_metric` for internal usage to avoid naming collisions with other metric systems within Sentry's infrastructure. From an SDK perspective, these are simply referred to as "metrics". + + + +## Metrics Protocol + +Metrics are sent to Sentry via the `trace_metric` envelope item. Each `trace_metric` envelope item contains a batch of metric payloads encoded as JSON, allowing for transmission of multiple metrics in a single envelope. + +### `trace_metric` Envelope Item + +The `trace_metric` envelope item is an object that contains an array of metric payloads encoded as JSON. This allows for multiple metric payloads to be sent in a single envelope item. See [Appendix A](#appendix-a-example-trace_metric-envelope) for an example `trace_metric` envelope. + +```json +{ + "type": "trace_metric", + "item_count": 10, + "content_type": "application/vnd.sentry.items.trace_metric+json" +} +{ + "items": [{..metric..}, {..metric..}, {..metric..}, {..metric..}, {..metric..}, ...] +} +``` + +### `trace_metric` Envelope Item Payload + +The `trace_metric` envelope item payload is a JSON object that represents a Sentry Metric. + +```json +{ + "timestamp": 1544719860.0, + "trace_id": "5b8efff798038103d269b633813fc60c", + "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" } + } +} +``` + +It consists of the following fields: + +`timestamp` + +: **Number, required**. Timestamp in seconds (epoch time) indicating when the metric was recorded. + +`type` + +: **String, required**. The type of metric. One of: + +- `counter`: A metric that increments counts +- `gauge`: A metric that tracks a value that can go up or down +- `distribution`: A metric that tracks the statistical distribution of values + +`name` + +: **String, required**. The name of the metric. This should follow a hierarchical naming convention using dots as separators (e.g., `api.response_time`, `db.query.duration`). + +`value` + +: **Number, required**. The numeric value of the metric. The interpretation depends on the metric `type`: + +- For `counter` metrics: the count to increment by (should default to 1) +- For `gauge` metrics: the current value +- For `distribution` metrics: a single measured value + +Integers should be a 64-bit signed integer, while doubles should be a 64-bit floating point number. + +`trace_id` + +: **String, optional**. The trace id of the metric. The value should be 16 random bytes encoded as a hex string (32 characters long). The trace id should be grabbed from the current propagation context in the SDK. + +`span_id` + +: **String, optional**. The span id for the metric. + +`unit` + +: **String, optional**. The unit of measurement for the metric value. + +`attributes` + +: **Object, optional**. A dictionary of key-value pairs of arbitrary data attached to the metric. Attributes must also declare the type of the value. The following types are supported: `string`, `boolean`, `integer`, `double`. + +Example with multiple attribute types: + +```json +{ + "timestamp": 1544719860.0, + "trace_id": "5b8efff798038103d269b633813fc60c", + "span_id": "b0e6f15b45c36b12", + "name": "http.request.duration", + "value": 245.3, + "unit": "millisecond", + "type": "distribution", + "attributes": { + "endpoint": { "value": "/api/users", "type": "string" }, + "status_code": { "value": 200, "type": "integer" }, + "response_size": { "value": 1024.5, "type": "double" }, + "cache_hit": { "value": true, "type": "boolean" } + } +} +``` + +### Metric Types + +#### Counter + +Counters track the number of times an event occurs. They only increase and are useful for tracking things like requests, errors, or any other countable event. + +```json +{ + "name": "api.requests", + "value": 1, + "type": "counter", + "attributes": { + "endpoint": { "value": "/api/users", "type": "string" }, + "method": { "value": "POST", "type": "string" } + } +} +``` + +#### Gauge + +Gauges track a value that can arbitrarily increase or decrease over time, such as memory usage, queue depth, or connection pool size. + +```json +{ + "name": "db.connection_pool.active", + "value": 42, + "unit": "connection", + "type": "gauge", + "attributes": { + "pool_name": { "value": "main_db", "type": "string" }, + "max_size": { "value": 100, "type": "integer" }, + "database": { "value": "postgres", "type": "string" } + } +} +``` + +#### Distribution + +Distributions track the statistical distribution of a set of values. They're useful for understanding percentiles, averages, and other statistical properties of measurements like response times or file sizes. + +```json +{ + "name": "page.load_time", + "value": 245.7, + "unit": "millisecond", + "type": "distribution", + "attributes": { + "page": { "value": "/dashboard", "type": "string" }, + "browser": { "value": "chrome", "type": "string" } + } +} +``` + +## Public API + +API wise the SDKs are required to expose metrics methods which are to be defined in a `metrics` module or namespace. The SDKs should also include some initialization options to configure the behavior of metrics in the SDK. + +### Initialization Options + +The 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 via the Sentry SDK's Metrics APIs. If this flag is set to `false`, the SDK should not send metrics to Sentry. Defaults to `false`. + +- `beforeSendMetric`/`before_send_metric`: A function that takes a metric object and returns a metric object. This function is called before sending the metric to Sentry. It can be used to modify the metric object or to prevent the metric from being sent to Sentry. This function is optional. + +While the metrics functionality for an SDK is in an experimental state, SDKs should put these configuration options in an experimental namespace to avoid breaking changes. Also, since integrations will not send automatically generated metrics, the `enableMetrics` flag will not be needed after metrics are released and instead default to `true`. + +```js +Sentry.init({ + _experiments: { enableMetrics: true }, +}); +``` + +### Metrics Module + +At minimum the SDK needs to implement the following methods for each metric type: + +- `Sentry.metrics.increment(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 + +#### Method Signatures + +The parameters for these methods are: + +- `name` **String, required**: The name of the metric +- `value` **Number, required**: The value of the metric +- `options` **Object, optional**: An object containing the following properties: + - `unit` **String, optional**: The unit of measurement (distribution and gauge only) + - `attributes` **Object, optional**: A dictionary of attributes (key-value pairs with type information) + - `scope` **Scope, optional**: The scope to capture the metric with. + +Below are some example SDK implementations to get you started. These are not finalized versions of the API and individual SDK authors should ensure the metrics APIs best fit their platforms. + +#### JavaScript + +```jsx +// Increment a counter +Sentry.metrics.increment("button.clicks", 1, { + attributes: { + button_id: "submit", + page: "checkout", + }, +}); + +// Set a gauge value +Sentry.metrics.gauge("db.connection_pool.active", 42, { + unit: "connection", + attributes: { + pool_name: "main_db", + database: "postgres", + }, +}); + +// Record a distribution +Sentry.metrics.distribution("page.load_time", 245.7, { + unit: "millisecond", + attributes: { + page: "/dashboard", + browser: "chrome", + }, +}); +``` + +#### Python + +```python +# Increment a counter +Sentry.metrics.increment('button.clicks', 1, { + 'attributes': {'button_id': 'submit', 'page': 'checkout'} +}) + +# Set a gauge value +Sentry.metrics.gauge('db.connection_pool.active', 42, { + 'unit': 'connection', + 'attributes': {'pool_name': 'main_db', 'database': 'postgres'} +}) + +# Record a distribution +Sentry.metrics.distribution('page.load_time', 245.7, { + 'unit': 'millisecond', + 'attributes': {'page': '/dashboard', 'browser': 'chrome'} +}) +``` + +#### PHP + +```php +use function Sentry\metrics; + +metrics()->increment('button.clicks', 1, [ + 'attributes' => ['button_id' => 'submit', 'page' => 'checkout'] +]); + +metrics()->gauge('db.connection_pool.active', 42, [ + 'unit' => 'connection', + 'attributes' => ['pool_name' => 'main_db', 'database' => 'postgres'] +]); + +metrics()->distribution('page.load_time', 245.7, [ + 'unit' => 'millisecond', + 'attributes' => ['page' => '/dashboard', 'browser' => 'chrome'] +]); +``` + +#### Java + +```java +import io.sentry.Sentry; + +Sentry.metrics().increment("button.clicks", 1, + Map.of("attributes", Map.of("button_id", "submit", "page", "checkout")) +); + +Sentry.metrics().gauge("db.connection_pool.active", 42, + Map.of( + "unit", "connection", + "attributes", Map.of("pool_name", "main_db", "database", "postgres") + ) +); + +Sentry.metrics().distribution("page.load_time", 245.7, + Map.of( + "unit", "millisecond", + "attributes", Map.of("page", "/dashboard", "browser", "chrome") + ) +); +``` + +#### Apple + +```swift +// Swift +SentrySDK.metrics() + .increment( + name: "button.clicks", + value: 1, + options: [ + "attributes": ["button_id": "submit", "page": "checkout"] + ] + ) + +SentrySDK.metrics() + .gauge( + name: "db.connection_pool.active", + value: 42, + options: [ + "unit": "connection", + "attributes": ["pool_name": "main_db", "database": "postgres"] + ] + ) + +SentrySDK.metrics() + .distribution( + name: "page.load_time", + value: 245.7, + options: [ + "unit": "millisecond", + "attributes": ["page": "/dashboard", "browser": "chrome"] + ] + ) +``` + +### Threading and Concurrency Considerations + +The threading and concurrency considerations for metrics are the same as for logs. See the [Threading and Concurrency Considerations section in the Logs documentation](/sdk/telemetry/logs/#threading-and-concurrency-considerations) for more information. + +## SDK Behavior + +In general metric processing should follow this order: + +1. Capture metric via [Public APIs](#metrics-module) (e.g. `Sentry.metrics.increment`). +1. (While experimental) Check if metrics are enabled as per `enableMetrics`/`enable_metrics` configuration - if not, skip the rest of the steps. +1. Process captured metric (attach default attributes as per [default attributes](#default-attributes)). +1. Run `beforeSendMetric`/`before_send_metric` to filter or modify the metric. +1. Add metric to buffer/batch processor as detailed in [buffering](#buffering). +1. 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). + + + +An SDK should implement [Tracing without Performance](/sdk/telemetry/traces/tracing-without-performance) before adding support for metrics. This is required to ensure that metrics are associated with traces and that the correct trace context is sent to Sentry. + + + +### Default Attributes + +By default the SDK should attach the following attributes to a metric: + +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 +5. `sentry.replay_id`: The replay id of the replay that was active when the metric was collected. This should not be set if there was no active replay. + +```json +{ + "attributes": { + "sentry.environment": { "value": "production", "type": "string" }, + "sentry.release": { "value": "1.0.0", "type": "string" }, + "sentry.sdk.name": { + "value": "sentry.javascript.browser", + "type": "string" + }, + "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, + "sentry.replay_id": { + "value": "36b75d9fa11f45459412a96c41bdf691", + "type": "string" + } + } +} +``` + +#### User Attributes + +SDKs may optionally attach user information as attributes: + +1. `user.id`: The user ID. Maps to `id` in the [User](/sdk/data-model/event-payloads/user/) payload. +2. `user.name`: The username. Maps to `username` in the [User](/sdk/data-model/event-payloads/user/) payload. +3. `user.email`: The email address. Maps to `email` in the [User](/sdk/data-model/event-payloads/user/) payload. + +Note: Adding user information to metrics may significantly increase cardinality and should be done carefully. + +```json +{ + "attributes": { + "user.id": { "value": "123", "type": "string" } + } +} +``` + +#### User Agent Parsing + +By default, Relay should parse the user agent attached to an incoming log envelope to parse `browser` and `os` information for logs. These attributes should be attached by Relay, but SDKs can attach them if they do not forward a user agent when sending logs to Sentry. + +1. `browser.name`: Display name of the browser application. Maps to `name` in the [Contexts](/sdk/data-model/event-payloads/contexts/#browser-context) payload. +2. `browser.version`: Version string of the browser. Maps to `version` in the [Contexts](/sdk/data-model/event-payloads/contexts/#browser-context) payload. + +```json +{ + "browser.name": "Chrome", + "browser.version": "120.0" +} +``` + +#### Future Default Attributes + +The SDKs should aim to minimize the number of default attributes attached to a metric. Metrics cardinality can explode quickly with too many attributes, and we want to keep metrics lightweight and cost-effective. + +New default attributes should only be added after significant feedback from users and discussion internally with the SDK and ingest teams. There is no hard rule about what exact attributes are allowed, every proposed new attribute will be evaluated on a case-by-case basis. + +### Data Category and Rate Limiting + +TBD + +### Buffering + +Metrics should be buffered and aggregated before being sent. SDKs should keep a buffer of metrics on the client that flushes out based on some kind of condition. We recommend following the [batch processor specification](/sdk/telemetry/spans/batch-processor/) outlined in the develop docs, but you should choose the approach that works best for your platform. + +- The aggregation window should be time and size based. +- Flush triggers (e.g. SDK shutdown, size thresholds) should be considered based on the platform and use case. +- SDKs should implement safeguards to prevent excessive memory usage from metric buffering. + +### Behaviour with other Sentry Telemetry + +#### Tracing + +Metrics should be associated with traces. If a metric is recorded during an active span, the SDK should set the `sentry.trace.parent_span_id` attribute to the span id of the span that was active when the metric was collected. + +#### Replays + +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 the `sentry.replay_id` attribute with the ID of the replay that was active at the time the metric was collected. Additionally, the SDK should include the `sentry._internal.replay_is_buffering` attribute to indicate that the metric is associated with a replay that is currently buffering. This ensures we can correctly handle scenarios where a `replay_id` is present, but the corresponding replay was never actually sent. + +### Other + +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. + +## Appendix A: Example `trace_metric` Envelope + +```json +{ "sdk": { "name": "sentry.javascript.browser", "version": "10.17.0" } } +{ + "type": "trace_metric", + "item_count": 5, + "content_type": "application/vnd.sentry.items.trace_metric+json" +} +{ + "items": [ + { + "timestamp": 1746456149.019, + "trace_id": "624f66e93a04469f9992c7e9f1485056", + "name": "api.requests", + "value": 1, + "type": "counter", + "attributes": { + "endpoint": { "value": "/api/users", "type": "string" }, + "method": { "value": "POST", "type": "string" }, + "status_code": { "value": 201, "type": "integer" }, + "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, + "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, + "sentry.environment": { "value": "production", "type": "string" }, + "sentry.release": { "value": "1.0.0", "type": "string" } + } + }, + { + "timestamp": 1746456149.019, + "trace_id": "624f66e93a04469f9992c7e9f1485056", + "name": "api.response_time", + "value": 125.5, + "unit": "millisecond", + "type": "distribution", + "attributes": { + "endpoint": { "value": "/api/users", "type": "string" }, + "method": { "value": "POST", "type": "string" }, + "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, + "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, + } + }, + { + "timestamp": 1746456149.02, + "trace_id": "624f66e93a04469f9992c7e9f1485056", + "name": "cache.hit_rate", + "value": 0.95, + "unit": "ratio", + "type": "gauge", + "attributes": { + "cache_name": { "value": "user_sessions", "type": "string" }, + "region": { "value": "us-west-1", "type": "string" }, + "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, + "sentry.sdk.version": { "value": "10.17.0", "type": "string" } + } + }, + { + "timestamp": 1746456149.02, + "trace_id": "624f66e93a04469f9992c7e9f1485056", + "name": "database.query.duration", + "value": 42.3, + "unit": "millisecond", + "type": "distribution", + "attributes": { + "query_type": { "value": "SELECT", "type": "string" }, + "table": { "value": "users", "type": "string" }, + "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, + "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, + "sentry.origin": { "value": "auto.db.graphql", "type": "string" } + } + }, + { + "timestamp": 1746456149.021, + "trace_id": "624f66e93a04469f9992c7e9f1485056", + "name": "active.users", + "value": 12345, + "type": "set", + "attributes": { + "cohort": { "value": "beta", "type": "string" }, + "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, + "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, + "sentry.replay_id": { "value": "36b75d9fa11f45459412a96c41bdf691", "type": "string" } + } + } + ] +} +``` + +## Related Resources + +- [GitHub PR #17883 - Metrics API Implementation](https://github.com/getsentry/sentry-javascript/pull/17883/files) +- [Batch Processor Specification](/sdk/telemetry/spans/batch-processor/) +- [Tracing without Performance](/sdk/telemetry/traces/tracing-without-performance) +- [Trace Origin](/sdk/telemetry/traces/trace-origin/) diff --git a/develop-docs/sdk/telemetry/profiles/index.mdx b/develop-docs/sdk/telemetry/profiles/index.mdx index f8b11b34f74c8..2dbea27f8c973 100644 --- a/develop-docs/sdk/telemetry/profiles/index.mdx +++ b/develop-docs/sdk/telemetry/profiles/index.mdx @@ -1,6 +1,6 @@ --- title: Profiles -sidebar_order: 4 +sidebar_order: 6 --- This document defines the Sample format used by Sentry to ingest profiles. This diff --git a/develop-docs/sdk/telemetry/replays.mdx b/develop-docs/sdk/telemetry/replays.mdx index 539653391d206..e3d8ec495be60 100644 --- a/develop-docs/sdk/telemetry/replays.mdx +++ b/develop-docs/sdk/telemetry/replays.mdx @@ -1,6 +1,6 @@ --- title: Replays -sidebar_order: 5 +sidebar_order: 7 --- This document defines the format used by Sentry to ingest replays. This diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index 29698b79548a2..9f0591396264d 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -1,6 +1,6 @@ --- title: Sessions -sidebar_order: 6 +sidebar_order: 8 --- diff --git a/develop-docs/sdk/telemetry/spans/index.mdx b/develop-docs/sdk/telemetry/spans/index.mdx index 6853b90e443fd..d20b702253ebf 100644 --- a/develop-docs/sdk/telemetry/spans/index.mdx +++ b/develop-docs/sdk/telemetry/spans/index.mdx @@ -1,6 +1,6 @@ --- title: Spans -sidebar_order: 8 +sidebar_order: 10 --- diff --git a/develop-docs/sdk/telemetry/traces/index.mdx b/develop-docs/sdk/telemetry/traces/index.mdx index c69f5111c4319..3ca2a342e2160 100644 --- a/develop-docs/sdk/telemetry/traces/index.mdx +++ b/develop-docs/sdk/telemetry/traces/index.mdx @@ -1,6 +1,6 @@ --- title: Traces -sidebar_order: 7 +sidebar_order: 9 --- This document covers how SDKs should add support for Performance Monitoring with [Distributed From 3cd9dc2960241cfff293e5da50ebcdec910b7444 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 10 Oct 2025 12:22:13 +0200 Subject: [PATCH 02/21] update resources --- develop-docs/sdk/telemetry/metrics.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index fbd805f7dcc6c..ed6ca95cfc457 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -545,7 +545,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should ## Related Resources -- [GitHub PR #17883 - Metrics API Implementation](https://github.com/getsentry/sentry-javascript/pull/17883/files) +- [Experimental JS SDK PR #17883 - Metrics API Implementation](https://github.com/getsentry/sentry-javascript/pull/17883/files) +- [Experimental Python SDK PR #4898 - Metrics API Implementation](https://github.com/getsentry/sentry-python/pull/4898) - [Batch Processor Specification](/sdk/telemetry/spans/batch-processor/) -- [Tracing without Performance](/sdk/telemetry/traces/tracing-without-performance) -- [Trace Origin](/sdk/telemetry/traces/trace-origin/) + From 4ca5e7bcb77ac2640f76338f2c7f9a8f5739cb99 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 10 Oct 2025 13:12:57 +0200 Subject: [PATCH 03/21] Update develop-docs/sdk/telemetry/metrics.mdx Co-authored-by: David Herberth --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index ed6ca95cfc457..d27faa6a2e064 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -86,7 +86,7 @@ Integers should be a 64-bit signed integer, while doubles should be a 64-bit flo `trace_id` -: **String, optional**. The trace id of the metric. The value should be 16 random bytes encoded as a hex string (32 characters long). The trace id should be grabbed from the current propagation context in the SDK. +: **String, required**. The trace id of the metric. The value should be 16 random bytes encoded as a hex string (32 characters long). The trace id should be grabbed from the current propagation context in the SDK. `span_id` From 8058f513313dc3811c9a3bb06e4de479add75829 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 10 Oct 2025 13:41:55 +0200 Subject: [PATCH 04/21] . --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index d27faa6a2e064..ea40a211e1739 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -432,7 +432,7 @@ New default attributes should only be added after significant feedback from user ### Data Category and Rate Limiting -TBD +A new data category for metrics has been added to Relay, `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 should not send any trace metrics until the limit expires (based on the communicated end timestamp). ### Buffering From 4eb6bc8ef2ceeb70ed4c47370ad484fc73232327 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 14 Oct 2025 18:25:36 +0200 Subject: [PATCH 05/21] use count --- develop-docs/sdk/telemetry/metrics.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index ea40a211e1739..fd7f557924d02 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -197,7 +197,7 @@ Sentry.init({ At minimum the SDK needs to implement the following methods for each metric type: -- `Sentry.metrics.increment(name, value, options)` - Increment a counter +- `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 @@ -218,7 +218,7 @@ Below are some example SDK implementations to get you started. These are not fin ```jsx // Increment a counter -Sentry.metrics.increment("button.clicks", 1, { +Sentry.metrics.count("button.clicks", 1, { attributes: { button_id: "submit", page: "checkout", @@ -248,7 +248,7 @@ Sentry.metrics.distribution("page.load_time", 245.7, { ```python # Increment a counter -Sentry.metrics.increment('button.clicks', 1, { +Sentry.metrics.count('button.clicks', 1, { 'attributes': {'button_id': 'submit', 'page': 'checkout'} }) @@ -270,7 +270,7 @@ Sentry.metrics.distribution('page.load_time', 245.7, { ```php use function Sentry\metrics; -metrics()->increment('button.clicks', 1, [ +metrics()->count('button.clicks', 1, [ 'attributes' => ['button_id' => 'submit', 'page' => 'checkout'] ]); @@ -290,7 +290,7 @@ metrics()->distribution('page.load_time', 245.7, [ ```java import io.sentry.Sentry; -Sentry.metrics().increment("button.clicks", 1, +Sentry.metrics().count("button.clicks", 1, Map.of("attributes", Map.of("button_id", "submit", "page", "checkout")) ); From 80f1227108e2cff6f790a5558f6c67c80bc6a1f8 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 14 Oct 2025 18:58:35 +0200 Subject: [PATCH 06/21] update docs for flag --- develop-docs/sdk/telemetry/metrics.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index fd7f557924d02..c64fddf5dbedb 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -181,14 +181,18 @@ API wise the SDKs are required to expose metrics methods which are to be defined The 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 via the Sentry SDK's Metrics APIs. If this flag is set to `false`, the SDK should not send metrics to Sentry. Defaults to `false`. +- `enableMetrics`/`enable_metrics`: A boolean flag to control if metric envelopes will be generated and sent to Sentry via the Sentry SDK's Metrics APIs. If this flag is set to `false`, the SDK should not send metrics to Sentry. Defaults to `true`. - `beforeSendMetric`/`before_send_metric`: A function that takes a metric object and returns a metric object. This function is called before sending the metric to Sentry. It can be used to modify the metric object or to prevent the metric from being sent to Sentry. This function is optional. -While the metrics functionality for an SDK is in an experimental state, SDKs should put these configuration options in an experimental namespace to avoid breaking changes. Also, since integrations will not send automatically generated metrics, the `enableMetrics` flag will not be needed after metrics are released and instead default to `true`. +While the metrics functionality for an SDK is in an experimental state, SDKs should put these configuration options in an experimental namespace to avoid breaking changes. ```js Sentry.init({ + // stable + enableMetrics: true, + + // experimental _experiments: { enableMetrics: true }, }); ``` From da457fc1de2557d0ef3d237ea49d82757ef00d80 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 14 Oct 2025 19:02:12 +0200 Subject: [PATCH 07/21] add note on sendDefaultPii --- develop-docs/sdk/telemetry/metrics.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index c64fddf5dbedb..57d3d9d106fa6 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -356,7 +356,7 @@ The threading and concurrency considerations for metrics are the same as for log In general metric processing should follow this order: 1. Capture metric via [Public APIs](#metrics-module) (e.g. `Sentry.metrics.increment`). -1. (While experimental) Check if metrics are enabled as per `enableMetrics`/`enable_metrics` configuration - if not, skip the rest of the steps. +1. Check if metrics are disabled as per `enableMetrics`/`enable_metrics` configuration - if so, skip the rest of the steps. 1. Process captured metric (attach default attributes as per [default attributes](#default-attributes)). 1. Run `beforeSendMetric`/`before_send_metric` to filter or modify the metric. 1. Add metric to buffer/batch processor as detailed in [buffering](#buffering). @@ -398,14 +398,12 @@ By default the SDK should attach the following attributes to a metric: #### User Attributes -SDKs may optionally attach user information as attributes: +SDKs may optionally attach user information as attributes (guarded by `sendDefaultPii`): 1. `user.id`: The user ID. Maps to `id` in the [User](/sdk/data-model/event-payloads/user/) payload. 2. `user.name`: The username. Maps to `username` in the [User](/sdk/data-model/event-payloads/user/) payload. 3. `user.email`: The email address. Maps to `email` in the [User](/sdk/data-model/event-payloads/user/) payload. -Note: Adding user information to metrics may significantly increase cardinality and should be done carefully. - ```json { "attributes": { From 7b06da11d4bc75c17f37e01bb02ed7905f629821 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 14 Oct 2025 19:04:21 +0200 Subject: [PATCH 08/21] user agent parsing --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 57d3d9d106fa6..068a96f028e40 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -414,7 +414,7 @@ SDKs may optionally attach user information as attributes (guarded by `sendDefau #### User Agent Parsing -By default, Relay should parse the user agent attached to an incoming log envelope to parse `browser` and `os` information for logs. These attributes should be attached by Relay, but SDKs can attach them if they do not forward a user agent when sending logs to Sentry. +By default, Relay should parse the user agent attached to an incoming metric envelope to parse `browser` and `os` information for metrics. These attributes should be attached by Relay, but client-side SDKs can 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 [Contexts](/sdk/data-model/event-payloads/contexts/#browser-context) payload. 2. `browser.version`: Version string of the browser. Maps to `version` in the [Contexts](/sdk/data-model/event-payloads/contexts/#browser-context) payload. From af220b6d8023930bce5dfbb9c51b6f047475a835 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 14 Oct 2025 19:05:32 +0200 Subject: [PATCH 09/21] one more increment leftover --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 068a96f028e40..e4fa45e623964 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -318,7 +318,7 @@ Sentry.metrics().distribution("page.load_time", 245.7, ```swift // Swift SentrySDK.metrics() - .increment( + .count( name: "button.clicks", value: 1, options: [ From eb385c0192a9d22132974d4d0c9b3e7f7371e749 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 17:57:38 +0100 Subject: [PATCH 10/21] rm aggregated --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index e4fa45e623964..fe946cefeb1b5 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -438,7 +438,7 @@ A new data category for metrics has been added to Relay, `trace_metric`. Rate li ### Buffering -Metrics should be buffered and aggregated before being sent. SDKs should keep a buffer of metrics on the client that flushes out based on some kind of condition. We recommend following the [batch processor specification](/sdk/telemetry/spans/batch-processor/) outlined in the develop docs, but you should choose the approach that works best for your platform. +Metrics should be buffered before being sent. SDKs should keep a buffer of metrics on the client that flushes out based on some kind of condition. We recommend following the [batch processor specification](/sdk/telemetry/spans/batch-processor/) outlined in the develop docs, but you should choose the approach that works best for your platform. - The aggregation window should be time and size based. - Flush triggers (e.g. SDK shutdown, size thresholds) should be considered based on the platform and use case. From fd54cf1e2f1261998750db39150e77f741f84244 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 18:03:43 +0100 Subject: [PATCH 11/21] fix content type --- develop-docs/sdk/telemetry/metrics.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index fe946cefeb1b5..f41d745b56ef2 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -29,7 +29,7 @@ The `trace_metric` envelope item is an object that contains an array of metric p { "type": "trace_metric", "item_count": 10, - "content_type": "application/vnd.sentry.items.trace_metric+json" + "content_type": "application/vnd.sentry.items.trace-metric+json" } { "items": [{..metric..}, {..metric..}, {..metric..}, {..metric..}, {..metric..}, ...] @@ -465,7 +465,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should { "type": "trace_metric", "item_count": 5, - "content_type": "application/vnd.sentry.items.trace_metric+json" + "content_type": "application/vnd.sentry.items.trace-metric+json" } { "items": [ From 66b8202cc927e7a85248ac0d51d9d99117780542 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 18:03:55 +0100 Subject: [PATCH 12/21] naming --- develop-docs/sdk/data-model/envelope-items.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 8fa9e5169bb4c..227ad26c3353e 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -461,7 +461,7 @@ _None_ Item type `"trace_metric"` contains an array of metric payloads encoded as JSON. This allows for multiple metric payloads to be sent in a single envelope item. -Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`. +Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace-metric+json`. Both the `item_count` and `content_type` fields are required. It's okay to mix metrics from different traces into the same trace_metric envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header. @@ -474,7 +474,7 @@ Example: { "type": "trace_metric", "item_count": 5, - "content_type": "application/vnd.sentry.items.trace_metric+json" + "content_type": "application/vnd.sentry.items.trace-metric+json" } { "items": [{..metric..}, {..metric..}, {..metric..}, {..metric..}, {..metric..}] @@ -497,7 +497,7 @@ _None_ `content_type` -: **string, required.** The content type of the metric entries. Must be `application/vnd.sentry.items.trace_metric+json`. +: **string, required.** The content type of the metric entries. Must be `application/vnd.sentry.items.trace-metric+json`. ### Reserved Types From 91d716ba88f515f3e14cc79f22c12196c5701f4f Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 18:04:36 +0100 Subject: [PATCH 13/21] Update develop-docs/sdk/data-model/envelope-items.mdx Co-authored-by: Alex Krawiec --- develop-docs/sdk/data-model/envelope-items.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 227ad26c3353e..2e2b5c2d84633 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -463,7 +463,7 @@ Item type `"trace_metric"` contains an array of metric payloads encoded as JSON. Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace-metric+json`. Both the `item_count` and `content_type` fields are required. -It's okay to mix metrics from different traces into the same trace_metric envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header. +It's okay to mix metrics from different traces into the same `trace_metric` envelope item, but if you do, you MUST NOT attach a DSC (dynamic sampling context) to the envelope header. See the Metrics documentation for the payload details. For an example `trace_metric` envelope, see [Appendix A of the Metrics documentation](/sdk/telemetry/metrics#appendix-a-example-trace_metric-envelope). From f54d5589074dbdc1f5cfa770a89097f0d799cdd6 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 18:07:19 +0100 Subject: [PATCH 14/21] consolidate --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index f41d745b56ef2..ab93f9645a103 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -23,7 +23,7 @@ Metrics are sent to Sentry via the `trace_metric` envelope item. Each `trace_met ### `trace_metric` Envelope Item -The `trace_metric` envelope item is an object that contains an array of metric payloads encoded as JSON. This allows for multiple metric payloads to be sent in a single envelope item. See [Appendix A](#appendix-a-example-trace_metric-envelope) for an example `trace_metric` envelope. +The `trace_metric` envelope item is an object that contains an array of metric payloads encoded as JSON. See [Appendix A](#appendix-a-example-trace_metric-envelope) for an example `trace_metric` envelope. ```json { From 7aa6ffc3c03a81976d3a2f5d22e038b8800c51a0 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 18:08:55 +0100 Subject: [PATCH 15/21] Update develop-docs/sdk/telemetry/metrics.mdx Co-authored-by: Alex Alderman Webb --- develop-docs/sdk/telemetry/metrics.mdx | 29 +++++++++++++++----------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index ab93f9645a103..df99376ce2438 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -252,22 +252,27 @@ Sentry.metrics.distribution("page.load_time", 245.7, { ```python # Increment a counter -Sentry.metrics.count('button.clicks', 1, { - 'attributes': {'button_id': 'submit', 'page': 'checkout'} -}) +Sentry.metrics.count( + 'button.clicks', + 1, + attributes={'button_id': 'submit', 'page': 'checkout'}, +) # Set a gauge value -Sentry.metrics.gauge('db.connection_pool.active', 42, { - 'unit': 'connection', - 'attributes': {'pool_name': 'main_db', 'database': 'postgres'} -}) +Sentry.metrics.gauge( + 'db.connection_pool.active', + 42, + unit='connection', + attributes={'pool_name': 'main_db', 'database': 'postgres'}, +) # Record a distribution -Sentry.metrics.distribution('page.load_time', 245.7, { - 'unit': 'millisecond', - 'attributes': {'page': '/dashboard', 'browser': 'chrome'} -}) -``` +Sentry.metrics.distribution( + 'page.load_time', + 245.7, + unit='millisecond', + attributes={'page': '/dashboard', 'browser': 'chrome'}, +) #### PHP From e31cf39ccf62d979bb02ee855dc3da27ab5982a8 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 18:10:10 +0100 Subject: [PATCH 16/21] Update develop-docs/sdk/telemetry/metrics.mdx Co-authored-by: Alex Alderman Webb --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index df99376ce2438..2324bb970b3dc 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -207,7 +207,7 @@ At minimum the SDK needs to implement the following methods for each metric type #### Method Signatures -The parameters for these methods are: +The parameters for these methods should be the following, or an equivalent form that is more natural for SDK's language: - `name` **String, required**: The name of the metric - `value` **Number, required**: The value of the metric From e903db479bbc2671095e37a31dafbc6f9f1358d6 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 29 Oct 2025 18:11:54 +0100 Subject: [PATCH 17/21] trailing --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 2324bb970b3dc..44705cd6d7236 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -501,7 +501,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should "endpoint": { "value": "/api/users", "type": "string" }, "method": { "value": "POST", "type": "string" }, "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, - "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, + "sentry.sdk.version": { "value": "10.17.0", "type": "string" } } }, { From 69816312c2f5327a12372f3e82e02377b9885faf Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 5 Nov 2025 09:54:50 +0100 Subject: [PATCH 18/21] specify span id --- develop-docs/sdk/telemetry/metrics.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 44705cd6d7236..b69f1931e102f 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -90,7 +90,7 @@ Integers should be a 64-bit signed integer, while doubles should be a 64-bit flo `span_id` -: **String, optional**. The span id for the metric. +: **String, optional**. The span id of the span that was active when the metric was emitted. The value should be 8 random bytes encoded as a hex string (16 characters long). The span id should be grabbed from the current active span in the SDK. `unit` From 4d83d9147819e8f05fcc07d9b13ce04720ba1bb5 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 5 Nov 2025 09:57:01 +0100 Subject: [PATCH 19/21] add span id to example --- develop-docs/sdk/telemetry/metrics.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index b69f1931e102f..08a115e697d8e 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -477,6 +477,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should { "timestamp": 1746456149.019, "trace_id": "624f66e93a04469f9992c7e9f1485056", + "span_id": "b0e6f15b45c36b12", "name": "api.requests", "value": 1, "type": "counter", @@ -493,6 +494,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should { "timestamp": 1746456149.019, "trace_id": "624f66e93a04469f9992c7e9f1485056", + "span_id": "b0e6f15b45c36b12", "name": "api.response_time", "value": 125.5, "unit": "millisecond", @@ -507,6 +509,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should { "timestamp": 1746456149.02, "trace_id": "624f66e93a04469f9992c7e9f1485056", + "span_id": "b0e6f15b45c36b12", "name": "cache.hit_rate", "value": 0.95, "unit": "ratio", @@ -521,6 +524,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should { "timestamp": 1746456149.02, "trace_id": "624f66e93a04469f9992c7e9f1485056", + "span_id": "b0e6f15b45c36b12", "name": "database.query.duration", "value": 42.3, "unit": "millisecond", @@ -536,6 +540,7 @@ If `debug` is set to `true` in SDK init, calls to the Sentry metrics API should { "timestamp": 1746456149.021, "trace_id": "624f66e93a04469f9992c7e9f1485056", + "span_id": "b0e6f15b45c36b12", "name": "active.users", "value": 12345, "type": "set", From 8a294f64351d726cc82a08a7605c20c6d38b83fd Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 11 Nov 2025 15:44:39 +0100 Subject: [PATCH 20/21] add note on unit for counter --- develop-docs/sdk/telemetry/metrics.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 08a115e697d8e..1f08c19997256 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -124,7 +124,7 @@ Example with multiple attribute types: #### Counter -Counters track the number of times an event occurs. They only increase and are useful for tracking things like requests, errors, or any other countable event. +Counters track the number of times an event occurs. They only increase and are useful for tracking things like requests, errors, or any other countable event. Note that the unit is defined by the `name` of the metric itself. ```json { @@ -212,7 +212,7 @@ The parameters for these methods should be the following, or an equivalent form - `name` **String, required**: The name of the metric - `value` **Number, required**: The value of the metric - `options` **Object, optional**: An object containing the following properties: - - `unit` **String, optional**: The unit of measurement (distribution and gauge only) + - `unit` **String, optional**: The unit of measurement (only for `distribution` and `gauge`, for `counter` the unit is defined by `name`) - `attributes` **Object, optional**: A dictionary of attributes (key-value pairs with type information) - `scope` **Scope, optional**: The scope to capture the metric with. From 3fb80e41a658f94a0489edd0c5d91dba80d4dc47 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Wed, 12 Nov 2025 14:49:57 +0100 Subject: [PATCH 21/21] simplify counter unit note --- develop-docs/sdk/telemetry/metrics.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 1f08c19997256..561fae8b2d81c 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -124,7 +124,7 @@ Example with multiple attribute types: #### Counter -Counters track the number of times an event occurs. They only increase and are useful for tracking things like requests, errors, or any other countable event. Note that the unit is defined by the `name` of the metric itself. +Counters track the number of times an event occurs. They only increase and are useful for tracking things like requests, errors, or any other countable event. ```json { @@ -212,7 +212,7 @@ The parameters for these methods should be the following, or an equivalent form - `name` **String, required**: The name of the metric - `value` **Number, required**: The value of the metric - `options` **Object, optional**: An object containing the following properties: - - `unit` **String, optional**: The unit of measurement (only for `distribution` and `gauge`, for `counter` the unit is defined by `name`) + - `unit` **String, optional**: The unit of measurement (only used for `distribution` and `gauge`) - `attributes` **Object, optional**: A dictionary of attributes (key-value pairs with type information) - `scope` **Scope, optional**: The scope to capture the metric with.