From 597b5f7f5636b2a1674e46d35bf9abbf35efdc3f Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Mon, 15 Dec 2025 17:00:59 +0100 Subject: [PATCH 1/5] feat(apple): Add documentation for metrics --- .../apple/common/configuration/options.mdx | 46 ++++++++++ docs/platforms/apple/common/metrics/index.mdx | 30 +++++++ .../metrics/default-attributes/apple.mdx | 21 +++++ platform-includes/metrics/options/apple.mdx | 61 ++++++++++++++ .../metrics/requirements/apple.mdx | 1 + platform-includes/metrics/usage/apple.mdx | 83 +++++++++++++++++++ 6 files changed, 242 insertions(+) create mode 100644 docs/platforms/apple/common/metrics/index.mdx create mode 100644 platform-includes/metrics/default-attributes/apple.mdx create mode 100644 platform-includes/metrics/options/apple.mdx create mode 100644 platform-includes/metrics/requirements/apple.mdx create mode 100644 platform-includes/metrics/usage/apple.mdx diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index 74e3c45eee058d..57ebf54271df40 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -323,3 +323,49 @@ This feature is experimental and may have bugs. It's available from [version 8.4 When enabled, the SDK finishes the ongoing transaction bound to the scope and links them to the crash event when your app crashes. The SDK skips adding profiles to increase the chance of keeping the transaction. This option defaults to `false`. + +## Metrics Options + + + +When enabled, the SDK sends metrics to Sentry. Metrics can be captured using the `SentrySDK.metrics` API, which allows you to send, view and query counters, gauges and measurements. + +This option is available as of [version 9.1.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#910). + +This option defaults to `false`. Learn more in the Metrics documentation. + + + + + +Use this callback to filter or modify metrics before they're sent to Sentry. Return `nil` to drop the metric. + +This option is available as of [version 9.1.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#910). + +The callback receives a metric object and must return either a modified metric or `nil` to drop it. Attributes use the `Attributable` protocol, so you can only assign valid types (`String`, `Bool`, `Int`, `Double`, `Float`, or arrays of these types). + +```swift +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.enableMetrics = true + options.beforeSendMetric = { metric in + // Create a local mutable variable since metric is a data value + var metric = metric + + // Drop metrics with specific attributes + if let dropMe = metric.attributes["dropMe"] as? Bool, dropMe == true { + return nil + } + + // Modify metric attributes (only Attributable types are allowed) + metric.attributes["processed"] = true + metric.attributes["processed_at"] = "2024-01-01" + + return metric + } +} +``` + + diff --git a/docs/platforms/apple/common/metrics/index.mdx b/docs/platforms/apple/common/metrics/index.mdx new file mode 100644 index 00000000000000..7b3e58b2424f95 --- /dev/null +++ b/docs/platforms/apple/common/metrics/index.mdx @@ -0,0 +1,30 @@ +--- +title: Set Up Metrics +sidebar_title: Metrics +description: "Metrics allow you to send, view and query counters, gauges and measurements from your Sentry-configured apps to track application health and drill down into related traces, logs, and errors." +sidebar_order: 7 +sidebar_section: features +beta: true +--- + +With Sentry Metrics, you can send counters, gauges, distributions, and sets from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes. + + +This feature is currently in open beta. Please reach out on [GitHub](https://github.com/getsentry/sentry-cocoa/discussions) if you have feedback or questions. Features in beta are still in-progress and may have bugs. We recognize the irony. + + +## Requirements + + + +## Usage + + + +## Options + + + +## Default Attributes + + diff --git a/platform-includes/metrics/default-attributes/apple.mdx b/platform-includes/metrics/default-attributes/apple.mdx new file mode 100644 index 00000000000000..5eea79f91e0649 --- /dev/null +++ b/platform-includes/metrics/default-attributes/apple.mdx @@ -0,0 +1,21 @@ +By default the SDK will attach the following attributes to a metric: + +- `environment`: The environment set in the SDK if defined. This is sent from the SDK as `sentry.environment`. +- `release`: The release set in the SDK if defined. This is sent from the SDK as `sentry.release`. +- `sdk.name`: The name of the SDK that sent the metric. This is sent from the SDK as `sentry.sdk.name`. +- `sdk.version`: The version of the SDK that sent the metric. This is sent from the SDK as `sentry.sdk.version`. + +### User Attributes + +If user information is available in the current scope, the following attributes are added to the metric: + +- `user.id`: The user ID. +- `user.name`: The username. +- `user.email`: The email address. + +### Trace Attributes + +If there is an active trace or span when the metric is recorded, the following attributes are added: + +- `trace_id`: The trace ID of the active trace. +- `span_id`: The span ID of the active span, if available. diff --git a/platform-includes/metrics/options/apple.mdx b/platform-includes/metrics/options/apple.mdx new file mode 100644 index 00000000000000..1004999405f0dd --- /dev/null +++ b/platform-includes/metrics/options/apple.mdx @@ -0,0 +1,61 @@ +The Sentry Cocoa SDK provides several options to configure how metrics are captured and sent to Sentry. + +### Enabling Metrics + +Metrics are disabled by default. To enable metrics, set `enableMetrics` to `true` when initializing the SDK: + +```swift +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.enableMetrics = true +} +``` + +### Filtering and Modifying Metrics + +Use the `beforeSendMetric` callback to filter or modify metrics before they're sent to Sentry. This is useful for: + +- Removing sensitive data from metric attributes +- Dropping metrics you don't want to send +- Adding or modifying attributes + +The callback receives a metric object and must return either a modified metric or `nil` to drop it. Attributes use the `Attributable` protocol, so you can only assign valid types (`String`, `Bool`, `Int`, `Double`, `Float`, or arrays of these types). + +```swift +import Sentry + +SentrySDK.start { options in + options.dsn = "___PUBLIC_DSN___" + options.enableMetrics = true + options.beforeSendMetric = { metric in + // Create a local mutable variable since metric is a data value + var metric = metric + + // Drop metrics with specific attributes + // Note: Access attributes through the Attributable protocol + if let dropMe = metric.attributes["dropMe"] as? Bool, dropMe == true { + return nil + } + + // Modify metric attributes (only Attributable types are allowed) + metric.attributes["processed"] = true + metric.attributes["processed_at"] = "2024-01-01" + + return metric + } +} +``` + +### Flushing Metrics + +By default, metrics are buffered and flushed depending on buffer size and time. If you need to manually flush metrics before the automatic interval, you can use the `flush` method: + +```swift +import Sentry + +SentrySDK.flush(timeout: 5.0) +``` + +This will flush all pending metrics and events to Sentry. diff --git a/platform-includes/metrics/requirements/apple.mdx b/platform-includes/metrics/requirements/apple.mdx new file mode 100644 index 00000000000000..be1d6dfdfd1bf5 --- /dev/null +++ b/platform-includes/metrics/requirements/apple.mdx @@ -0,0 +1 @@ +Metrics are supported in Sentry Cocoa SDK version `9.1.0` and above. diff --git a/platform-includes/metrics/usage/apple.mdx b/platform-includes/metrics/usage/apple.mdx new file mode 100644 index 00000000000000..3feef55e6509a5 --- /dev/null +++ b/platform-includes/metrics/usage/apple.mdx @@ -0,0 +1,83 @@ +Once the SDK is initialized with metrics enabled, you can send metrics using the `SentrySDK.metrics` APIs. + +The `metrics` namespace exposes three methods that you can use to capture different types of metric information: `count`, `gauge` and `distribution`. + + +Objective-C support for metrics is not currently available. If you need Objective-C support, please [open an issue](https://github.com/getsentry/sentry-cocoa/issues) to show demand for this feature. + + +### Counter + +Use `count` to track an incrementing value, such as the number of times a button was clicked or a function was called. + +```swift +import Sentry + +SentrySDK.metrics.count(key: "button_click", value: 1) +``` + +### Gauge + +Use `gauge` to track a value that can go up and down, such as the current memory usage or the number of items in a queue. + +```swift +import Sentry + +SentrySDK.metrics.gauge(key: "queue_depth", value: 42.0) +``` + +### Distribution + +Use `distribution` to track the distribution of a value, such as the response time of a request. + +```swift +import Sentry + +SentrySDK.metrics.distribution(key: "response_time", value: 187.5) +``` + +### Adding Attributes + +You can also pass additional attributes to any of the metric methods via the `attributes` parameter. Attributes allow you to filter and group metrics. Attributes use the `Attributable` protocol, which provides type safety by only allowing valid types. + +Supported attribute types: +- **Scalar types**: `String`, `Bool`, `Int`, `Double`, `Float` +- **Array types**: `[String]`, `[Bool]`, `[Int]`, `[Double]` + +```swift +import Sentry + +SentrySDK.metrics.count( + key: "button_click", + value: 1, + unit: nil, + attributes: [ + "browser": "Firefox", // String + "app_version": "1.0.0", // String + "build_number": 123, // Int + "is_premium": true, // Bool + "success_rate": 0.95, // Double + "tags": ["production", "v2"] // [String] + ] +) +``` + +### Specifying Units + +For `gauge` and `distribution` metrics, you can specify a unit using the `unit` parameter. This helps Sentry display the metric value in a human-readable format. + +```swift +import Sentry + +SentrySDK.metrics.distribution( + key: "response_time", + value: 187.5, + unit: "millisecond" +) + +SentrySDK.metrics.gauge( + key: "memory_usage", + value: 1024.0, + unit: "byte" +) +``` From 20e68fd8ece912deedd37ebaba20edafe94d4010 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 14 Jan 2026 13:59:40 +0100 Subject: [PATCH 2/5] expanded metrics documentation --- .../common/features/experimental-features.mdx | 1 + platform-includes/metrics/options/apple.mdx | 50 +++++++--- platform-includes/metrics/usage/apple.mdx | 95 ++++++++++++++++--- 3 files changed, 119 insertions(+), 27 deletions(-) diff --git a/docs/platforms/apple/common/features/experimental-features.mdx b/docs/platforms/apple/common/features/experimental-features.mdx index c5c70e2a24d30b..2bdaae7cc384b4 100644 --- a/docs/platforms/apple/common/features/experimental-features.mdx +++ b/docs/platforms/apple/common/features/experimental-features.mdx @@ -21,5 +21,6 @@ Do you want to try some new experimental features? On the latest version of the - If you use Swift concurrency, stitch together stack traces of your async code with the `swiftAsyncStacktraces` option. Note that you can enable this in your Objective-C project, but only async code written in Swift will be stitched together. - Enable the `enablePersistingTracesWhenCrashing` option to link ongoing transactions to a crash event when your app crashes. - Enable the `enableUnhandledCPPExceptionsV2` option to capture fatal CPPExceptions via hooking into `cxa_throw` +- Enable Metrics to send counters, gauges, and distributions from your application to track application health and drill down into related traces, logs, and errors. Let us know if you have feedback through [GitHub issues](https://github.com/getsentry/sentry-cocoa/issues). diff --git a/platform-includes/metrics/options/apple.mdx b/platform-includes/metrics/options/apple.mdx index 1004999405f0dd..3ca75f75d54c35 100644 --- a/platform-includes/metrics/options/apple.mdx +++ b/platform-includes/metrics/options/apple.mdx @@ -2,14 +2,14 @@ The Sentry Cocoa SDK provides several options to configure how metrics are captu ### Enabling Metrics -Metrics are disabled by default. To enable metrics, set `enableMetrics` to `true` when initializing the SDK: +Metrics are disabled by default. To enable metrics, set `enableMetrics` to `true` in the experimental options when initializing the SDK: ```swift import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableMetrics = true + options.experimental.enableMetrics = true } ``` @@ -20,28 +20,54 @@ Use the `beforeSendMetric` callback to filter or modify metrics before they're s - Removing sensitive data from metric attributes - Dropping metrics you don't want to send - Adding or modifying attributes +- Changing metric names or units -The callback receives a metric object and must return either a modified metric or `nil` to drop it. Attributes use the `Attributable` protocol, so you can only assign valid types (`String`, `Bool`, `Int`, `Double`, `Float`, or arrays of these types). +The callback receives a `SentryMetric` struct and must return either a modified metric or `nil` to drop it. + +**Available `SentryMetric` properties:** +- `name`: The metric name (e.g., "api.response_time") +- `value`: The metric value (counter, distribution, or gauge) +- `unit`: The unit of measurement (`SentryMetricsUnit?`) +- `attributes`: Dictionary of attributes (`[String: SentryAttributeContent]`) +- `timestamp`: When the metric was recorded +- `traceId`: Associated trace ID + +When modifying `attributes`, you can assign values directly using literals thanks to Swift's `ExpressibleBy...Literal` protocols. The SDK supports `String`, `Bool`, `Int`, `Double`, and arrays of these types. ```swift import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableMetrics = true - options.beforeSendMetric = { metric in - // Create a local mutable variable since metric is a data value + options.experimental.enableMetrics = true + options.experimental.beforeSendMetric = { metric in + // Create a mutable copy (SentryMetric is a struct) var metric = metric - // Drop metrics with specific attributes - // Note: Access attributes through the Attributable protocol - if let dropMe = metric.attributes["dropMe"] as? Bool, dropMe == true { + // Drop metrics based on attributes + if case .boolean(let dropMe) = metric.attributes["dropMe"], dropMe { + return nil + } + + // Drop metrics by name + if metric.name.hasPrefix("internal.") { return nil } - // Modify metric attributes (only Attributable types are allowed) - metric.attributes["processed"] = true - metric.attributes["processed_at"] = "2024-01-01" + // Modify or add attributes using literals (recommended) + metric.attributes["processed"] = true // Boolean literal + metric.attributes["environment"] = "production" // String literal + metric.attributes["retry_count"] = 3 // Integer literal + metric.attributes["latency"] = 42.5 // Double literal + + // You can also use enum cases for explicitness + metric.attributes["explicit"] = .boolean(true) + metric.attributes["tags"] = .stringArray(["tag1", "tag2"]) + + // Change the metric name + if metric.name == "legacy_metric" { + metric.name = "new_metric_name" + } return metric } diff --git a/platform-includes/metrics/usage/apple.mdx b/platform-includes/metrics/usage/apple.mdx index 3feef55e6509a5..5b7a86c3323f12 100644 --- a/platform-includes/metrics/usage/apple.mdx +++ b/platform-includes/metrics/usage/apple.mdx @@ -8,41 +8,86 @@ Objective-C support for metrics is not currently available. If you need Objectiv ### Counter -Use `count` to track an incrementing value, such as the number of times a button was clicked or a function was called. +Counters track discrete occurrence counts. Use this to increment or set a count associated with a metric key, such as the number of events, requests, or errors. + +**Key characteristics:** +- Values are typically non-negative integers +- Use descriptive, lowercase, dot-delimited names (e.g., `"network.request.count"`) ```swift import Sentry +// Simple counter SentrySDK.metrics.count(key: "button_click", value: 1) + +// Counter with unit and attributes +SentrySDK.metrics.count( + key: "network.request.count", + value: 1, + unit: .generic("request"), + attributes: ["endpoint": "/api/users", "method": "POST"] +) ``` ### Gauge -Use `gauge` to track a value that can go up and down, such as the current memory usage or the number of items in a queue. +Gauges track values that can go up and down over time, representing a current state rather than an incrementing counter. Use this for metrics like current memory usage, queue depth, or active connections. + +**Key characteristics:** +- Values can increase or decrease +- Represents the state at the time of recording +- Supports aggregates like min, max, avg, sum, and count +- Cannot be used to calculate percentiles (use distributions for that) ```swift import Sentry +// Simple gauge SentrySDK.metrics.gauge(key: "queue_depth", value: 42.0) + +// Gauge with unit +SentrySDK.metrics.gauge( + key: "memory.usage", + value: 1024.0, + unit: .megabyte +) ``` ### Distribution -Use `distribution` to track the distribution of a value, such as the response time of a request. +Distributions track the distribution of a value over time, allowing you to analyze statistical properties like mean, median, and percentiles. Use this for measurable quantities like response times or request durations. + +**Key characteristics:** +- Enables percentile calculations (p50, p90, p99, etc.) +- Best for analyzing statistical properties of measurements +- Use for values where you need to understand distribution, not just aggregates ```swift import Sentry +// Simple distribution SentrySDK.metrics.distribution(key: "response_time", value: 187.5) + +// Distribution with unit and attributes +SentrySDK.metrics.distribution( + key: "http.request.duration", + value: 187.5, + unit: .millisecond, + attributes: ["endpoint": "/api/data", "cached": false] +) ``` ### Adding Attributes -You can also pass additional attributes to any of the metric methods via the `attributes` parameter. Attributes allow you to filter and group metrics. Attributes use the `Attributable` protocol, which provides type safety by only allowing valid types. +You can also pass additional attributes to any of the metric methods via the `attributes` parameter. Attributes allow you to filter and group metrics. + +The SDK uses the `SentryAttributeValue` protocol to provide **compile-time type safety** for attribute values. This means you can pass native Swift types directly without wrapping them, and the compiler will ensure only valid types are accepted. -Supported attribute types: +**Supported attribute types:** - **Scalar types**: `String`, `Bool`, `Int`, `Double`, `Float` -- **Array types**: `[String]`, `[Bool]`, `[Int]`, `[Double]` +- **Array types**: `[String]`, `[Bool]`, `[Int]`, `[Double]`, `[Float]` + +The protocol automatically handles type conversion and validation, so you can use Swift's native types directly in your code. Invalid types will be caught at compile time, preventing runtime errors. ```swift import Sentry @@ -52,32 +97,52 @@ SentrySDK.metrics.count( value: 1, unit: nil, attributes: [ - "browser": "Firefox", // String - "app_version": "1.0.0", // String - "build_number": 123, // Int - "is_premium": true, // Bool - "success_rate": 0.95, // Double - "tags": ["production", "v2"] // [String] + "browser": "Firefox", // String - passed directly + "app_version": "1.0.0", // String - passed directly + "build_number": 123, // Int - passed directly + "is_premium": true, // Bool - passed directly + "success_rate": 0.95, // Double - passed directly + "tags": ["production", "v2"] // [String] - passed directly ] ) ``` +The `SentryAttributeValue` protocol ensures that all these types are automatically converted to the correct internal representation, providing both type safety and a clean, idiomatic Swift API. + ### Specifying Units -For `gauge` and `distribution` metrics, you can specify a unit using the `unit` parameter. This helps Sentry display the metric value in a human-readable format. +All metric types (`count`, `gauge`, and `distribution`) support the optional `unit` parameter. Units help Sentry display metric values in a human-readable format. + +The SDK provides the `SentryMetricsUnit` enum with type-safe unit values: ```swift import Sentry +// Use enum cases for type safety (recommended) SentrySDK.metrics.distribution( key: "response_time", value: 187.5, - unit: "millisecond" + unit: .millisecond ) SentrySDK.metrics.gauge( key: "memory_usage", value: 1024.0, - unit: "byte" + unit: .byte +) + +SentrySDK.metrics.distribution( + key: "cache_latency", + value: 42.3, + unit: .microsecond ) ``` + +**Available unit categories:** + +- **Duration**: `.nanosecond`, `.microsecond`, `.millisecond`, `.second`, `.minute`, `.hour`, `.day`, `.week` +- **Information**: `.bit`, `.byte`, `.kilobyte`, `.kibibyte`, `.megabyte`, `.mebibyte`, `.gigabyte`, `.gibibyte`, `.terabyte`, `.tebibyte`, `.petabyte`, `.pebibyte`, `.exabyte`, `.exbibyte` +- **Fraction**: `.ratio`, `.percent` +- **Custom**: `.generic("custom_unit")` for any other unit + +You can also use string literals (e.g., `unit: "millisecond"`), which are automatically converted to the corresponding enum case. However, using enum cases is recommended for compile-time safety. From e96674ec86952073259a8b876ca5470fd81a4983 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 16 Jan 2026 10:22:26 +0100 Subject: [PATCH 3/5] updated docs with latest changes --- docs/platforms/apple/common/metrics/index.mdx | 4 +- .../metrics/default-attributes/apple.mdx | 41 ++++++++++++++----- platform-includes/metrics/options/apple.mdx | 14 +++---- platform-includes/metrics/usage/apple.mdx | 4 +- 4 files changed, 41 insertions(+), 22 deletions(-) diff --git a/docs/platforms/apple/common/metrics/index.mdx b/docs/platforms/apple/common/metrics/index.mdx index 7b3e58b2424f95..8bc22fce95bc58 100644 --- a/docs/platforms/apple/common/metrics/index.mdx +++ b/docs/platforms/apple/common/metrics/index.mdx @@ -1,13 +1,13 @@ --- title: Set Up Metrics sidebar_title: Metrics -description: "Metrics allow you to send, view and query counters, gauges and measurements from your Sentry-configured apps to track application health and drill down into related traces, logs, and errors." +description: "Metrics allow you to send, view and query counters, gauges, and distributions from your Sentry-configured apps to track application health and drill down into related traces, logs, and errors." sidebar_order: 7 sidebar_section: features beta: true --- -With Sentry Metrics, you can send counters, gauges, distributions, and sets from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes. +With Sentry Metrics, you can send counters, gauges, and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, traces, and logs, and searched using their individual attributes. This feature is currently in open beta. Please reach out on [GitHub](https://github.com/getsentry/sentry-cocoa/discussions) if you have feedback or questions. Features in beta are still in-progress and may have bugs. We recognize the irony. diff --git a/platform-includes/metrics/default-attributes/apple.mdx b/platform-includes/metrics/default-attributes/apple.mdx index 5eea79f91e0649..152b20cef864fb 100644 --- a/platform-includes/metrics/default-attributes/apple.mdx +++ b/platform-includes/metrics/default-attributes/apple.mdx @@ -1,21 +1,40 @@ By default the SDK will attach the following attributes to a metric: -- `environment`: The environment set in the SDK if defined. This is sent from the SDK as `sentry.environment`. -- `release`: The release set in the SDK if defined. This is sent from the SDK as `sentry.release`. -- `sdk.name`: The name of the SDK that sent the metric. This is sent from the SDK as `sentry.sdk.name`. -- `sdk.version`: The version of the SDK that sent the metric. This is sent from the SDK as `sentry.sdk.version`. +### SDK Attributes + +- `sentry.sdk.name`: The name of the SDK that sent the metric (e.g., "sentry.cocoa"). +- `sentry.sdk.version`: The version of the SDK that sent the metric. +- `sentry.environment`: The environment set in the SDK. +- `sentry.release`: The release set in the SDK, if defined. + +### Device and OS Attributes + +- `device.brand`: Always "Apple" for Apple devices. +- `device.model`: The device model (e.g., "iPhone14,2"). +- `device.family`: The device family (e.g., "iPhone"). +- `os.name`: The operating system name (e.g., "iOS"). +- `os.version`: The operating system version. ### User Attributes -If user information is available in the current scope, the following attributes are added to the metric: +User attributes are only added when `options.sendDefaultPii` is set to `true`: -- `user.id`: The user ID. -- `user.name`: The username. -- `user.email`: The email address. +- `user.id`: The user ID from the current scope. Falls back to the installation ID if no user is set. +- `user.name`: The username from the current scope. +- `user.email`: The email address from the current scope. ### Trace Attributes -If there is an active trace or span when the metric is recorded, the following attributes are added: +If there is an active span when the metric is recorded, the following attribute is added: + +- `span_id`: The span ID of the active span. + + +The `trace_id` is set as a top-level field on the metric (not as an attribute) to enable distributed tracing correlation. When a span is active, the SDK uses that span's trace ID; otherwise, it falls back to the propagation context's trace ID. + + +### Session Replay Attributes + +If Session Replay is enabled and active (iOS and tvOS only): -- `trace_id`: The trace ID of the active trace. -- `span_id`: The span ID of the active span, if available. +- `sentry.replay_id`: The current replay session ID. diff --git a/platform-includes/metrics/options/apple.mdx b/platform-includes/metrics/options/apple.mdx index 3ca75f75d54c35..8753945b43a488 100644 --- a/platform-includes/metrics/options/apple.mdx +++ b/platform-includes/metrics/options/apple.mdx @@ -1,15 +1,15 @@ The Sentry Cocoa SDK provides several options to configure how metrics are captured and sent to Sentry. -### Enabling Metrics +### Enabling/Disabling Metrics -Metrics are disabled by default. To enable metrics, set `enableMetrics` to `true` in the experimental options when initializing the SDK: +Metrics are enabled by default. If you need to disable metrics, set `enableMetrics` to `false` in the experimental options when initializing the SDK: ```swift import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.experimental.enableMetrics = true + options.experimental.enableMetrics = false // Metrics are enabled by default } ``` @@ -26,11 +26,11 @@ The callback receives a `SentryMetric` struct and must return either a modified **Available `SentryMetric` properties:** - `name`: The metric name (e.g., "api.response_time") -- `value`: The metric value (counter, distribution, or gauge) -- `unit`: The unit of measurement (`SentryMetricsUnit?`) +- `value`: The metric value (`SentryMetricValue` - counter, distribution, or gauge) +- `unit`: The unit of measurement (`SentryUnit?`) - `attributes`: Dictionary of attributes (`[String: SentryAttributeContent]`) - `timestamp`: When the metric was recorded -- `traceId`: Associated trace ID +- `traceId`: Associated trace ID for distributed tracing correlation When modifying `attributes`, you can assign values directly using literals thanks to Swift's `ExpressibleBy...Literal` protocols. The SDK supports `String`, `Bool`, `Int`, `Double`, and arrays of these types. @@ -39,7 +39,7 @@ import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.experimental.enableMetrics = true + // Metrics are enabled by default, no need to set enableMetrics = true options.experimental.beforeSendMetric = { metric in // Create a mutable copy (SentryMetric is a struct) var metric = metric diff --git a/platform-includes/metrics/usage/apple.mdx b/platform-includes/metrics/usage/apple.mdx index 5b7a86c3323f12..02b971abfcb5a6 100644 --- a/platform-includes/metrics/usage/apple.mdx +++ b/platform-includes/metrics/usage/apple.mdx @@ -1,4 +1,4 @@ -Once the SDK is initialized with metrics enabled, you can send metrics using the `SentrySDK.metrics` APIs. +Once the SDK is initialized, you can send metrics using the `SentrySDK.metrics` APIs. Metrics are enabled by default. The `metrics` namespace exposes three methods that you can use to capture different types of metric information: `count`, `gauge` and `distribution`. @@ -113,7 +113,7 @@ The `SentryAttributeValue` protocol ensures that all these types are automatical All metric types (`count`, `gauge`, and `distribution`) support the optional `unit` parameter. Units help Sentry display metric values in a human-readable format. -The SDK provides the `SentryMetricsUnit` enum with type-safe unit values: +The SDK provides the `SentryUnit` enum with type-safe unit values: ```swift import Sentry From cfc1676576f68faa8df4d8aa71fd35b23c93aeaf Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 16 Jan 2026 10:29:37 +0100 Subject: [PATCH 4/5] update min available and default values --- .../apple/common/configuration/options.mdx | 24 ++++++++----------- .../metrics/requirements/apple.mdx | 2 +- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index 12e2321b0435a6..8ff74a6a9d7fef 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -881,40 +881,36 @@ This option is only used when is s ## Metrics Options - + -When enabled, the SDK sends metrics to Sentry. Metrics can be captured using the `SentrySDK.metrics` API, which allows you to send, view and query counters, gauges and measurements. +When enabled, the SDK sends metrics to Sentry. Metrics can be captured using the `SentrySDK.metrics` API, which allows you to send, view and query counters, gauges and distributions. -This option is available as of [version 9.1.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#910). - -This option defaults to `false`. Learn more in the Metrics documentation. +Learn more in the Metrics documentation. - + Use this callback to filter or modify metrics before they're sent to Sentry. Return `nil` to drop the metric. -This option is available as of [version 9.1.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#910). - -The callback receives a metric object and must return either a modified metric or `nil` to drop it. Attributes use the `Attributable` protocol, so you can only assign valid types (`String`, `Bool`, `Int`, `Double`, `Float`, or arrays of these types). +The callback receives a `SentryMetric` struct and must return either a modified metric or `nil` to drop it. Attributes use the `SentryAttributeValue` protocol, so you can assign valid types directly (`String`, `Bool`, `Int`, `Double`, `Float`, or arrays of these types). ```swift import Sentry SentrySDK.start { options in options.dsn = "___PUBLIC_DSN___" - options.enableMetrics = true - options.beforeSendMetric = { metric in - // Create a local mutable variable since metric is a data value + // Metrics are enabled by default, no need to set enableMetrics = true + options.experimental.beforeSendMetric = { metric in + // Create a mutable copy (SentryMetric is a struct) var metric = metric // Drop metrics with specific attributes - if let dropMe = metric.attributes["dropMe"] as? Bool, dropMe == true { + if case .boolean(let dropMe) = metric.attributes["dropMe"], dropMe { return nil } - // Modify metric attributes (only Attributable types are allowed) + // Modify metric attributes using literals metric.attributes["processed"] = true metric.attributes["processed_at"] = "2024-01-01" diff --git a/platform-includes/metrics/requirements/apple.mdx b/platform-includes/metrics/requirements/apple.mdx index be1d6dfdfd1bf5..8dd85884cccca1 100644 --- a/platform-includes/metrics/requirements/apple.mdx +++ b/platform-includes/metrics/requirements/apple.mdx @@ -1 +1 @@ -Metrics are supported in Sentry Cocoa SDK version `9.1.0` and above. +Metrics are supported in Sentry Cocoa SDK version `9.2.0` and above. From 92b211ace78470aefd4cd9a134fc9dc9a6a9f650 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Fri, 23 Jan 2026 10:04:43 +0100 Subject: [PATCH 5/5] docs(apple): update note to alert for trace_id usage in metrics Replaced the `` tag with an `` tag to emphasize the importance of the `trace_id` being set as a top-level field for distributed tracing correlation in the Apple SDK documentation. --- platform-includes/metrics/default-attributes/apple.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/platform-includes/metrics/default-attributes/apple.mdx b/platform-includes/metrics/default-attributes/apple.mdx index 152b20cef864fb..8a79cb03c65753 100644 --- a/platform-includes/metrics/default-attributes/apple.mdx +++ b/platform-includes/metrics/default-attributes/apple.mdx @@ -29,9 +29,9 @@ If there is an active span when the metric is recorded, the following attribute - `span_id`: The span ID of the active span. - + The `trace_id` is set as a top-level field on the metric (not as an attribute) to enable distributed tracing correlation. When a span is active, the SDK uses that span's trace ID; otherwise, it falls back to the propagation context's trace ID. - + ### Session Replay Attributes