feat(apple): Add documentation for metrics

docs/platforms/apple/common/configuration/options.mdx

@@ -878,3 +878,48 @@ The Spotlight URL for local development.
 This option is only used when <PlatformIdentifier name="enableSpotlight" /> is set to `true`.
 
 </SdkOption>
+
+## Metrics Options
+<Alert>
+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.
+</Alert>
+
+<SdkOption name="experimental.enableMetrics" type="bool" defaultValue="true" availableSince="9.2.0">
+
+When enabled, the SDK can send metrics to Sentry. Note that metrics are not collected automatically — you must manually call the `SentrySDK.metrics` API to record counters, gauges, and distributions.
+
+Learn more in the <PlatformLink to="/metrics/">Metrics documentation</PlatformLink>.
+
+</SdkOption>
+
+<SdkOption name="experimental.beforeSendMetric" type="function" availableSince="9.2.0">
+
+Use this callback to filter or modify metrics before they're sent to Sentry. Return `nil` to drop the metric.
+
+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___"
+    // 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 case .boolean(let dropMe) = metric.attributes["dropMe"], dropMe {
+            return nil
+        }
+
+        // Modify metric attributes using literals
+        metric.attributes["processed"] = true
+        metric.attributes["processed_at"] = "2024-01-01"
+
+        return metric
+    }
+}
+```
+
+</SdkOption>

docs/platforms/apple/common/features/experimental-features.mdx

@@ -71,6 +71,22 @@ Indicators for reliable environments include:
 
 Learn more in the <PlatformLink to="/session-replay/">Session Replay</PlatformLink> documentation.
 
+## Metrics
+
+Use <PlatformLink to="/metrics/">Metrics</PlatformLink> to send counters, gauges, and distributions from your application to Sentry. Once in Sentry, these metrics can be viewed alongside related errors, traces, and logs, and searched using their individual attributes.
+
+The metrics feature is enabled by default, but metrics are not collected automatically. You must manually call the `SentrySDK.metrics` API to record metrics (e.g., `SentrySDK.metrics.count(key: "my_counter", value: 1)`). To disable the feature entirely:
+
+```swift
+options.experimental.enableMetrics = false
+```
+
+```objc {tabTitle:Objective-C}
+options.experimental.enableMetrics = NO;
+```
+
+Learn more in the <PlatformLink to="/metrics/">Metrics documentation</PlatformLink>.
+
 ## Providing Feedback
 
 Let us know if you have feedback through [GitHub issues](https://github.com/getsentry/sentry-cocoa/issues). Your feedback helps us improve these experimental features and move them toward stable releases.

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 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, 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.
+
+<Alert>
+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.
+</Alert>
+
+## Requirements
+
+<PlatformContent includePath="metrics/requirements" />
+
+## Usage
+
+<PlatformContent includePath="metrics/usage" />
+
+## Options
+
+<PlatformContent includePath="metrics/options" />
+
+## Default Attributes
+
+<PlatformContent includePath="metrics/default-attributes" />

docs/product/explore/metrics/getting-started/index.mdx

@@ -198,6 +198,31 @@ To set up Sentry Metrics, use the links below for supported SDKs. After it's bee
     label="Android"
     url="/platforms/android/metrics/"
   />
+- <LinkWithPlatformIcon
+    platform="apple.ios"
+    label="iOS"
+    url="/platforms/apple/guides/ios/metrics/"
+  />
+- <LinkWithPlatformIcon
+    platform="apple.macos"
+    label="macOS"
+    url="/platforms/apple/guides/macos/metrics/"
+  />
+- <LinkWithPlatformIcon
+    platform="apple.tvos"
+    label="tvOS"
+    url="/platforms/apple/guides/tvos/metrics/"
+  />
+- <LinkWithPlatformIcon
+    platform="apple.watchos"
+    label="watchOS"
+    url="/platforms/apple/guides/watchos/metrics/"
+  />
+- <LinkWithPlatformIcon
+    platform="apple.visionos"
+    label="visionOS"
+    url="/platforms/apple/guides/visionos/metrics/"
+  />
 
 ### Python
 

platform-includes/metrics/default-attributes/apple.mdx

@@ -0,0 +1,40 @@
+By default the SDK will attach the following attributes to a metric:
+
+### 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
+
+User attributes are only added when `options.sendDefaultPii` is set to `true`:
+
+- `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.
+
+### 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.
+
+### Trace Attributes
+
+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.
+
+<Alert type="info">
+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.
+</Alert>
+
+### Session Replay Attributes
+
+If Session Replay is enabled and active (iOS and tvOS only):
+
+- `sentry.replay_id`: The current replay session ID.

platform-includes/metrics/options/apple.mdx

@@ -0,0 +1,96 @@
+The Sentry Cocoa SDK provides several options to configure how metrics are captured and sent to Sentry.
+
+### Enabling/Disabling Metrics
+
+Metrics are enabled by default, but are not collected automatically. You must manually call the `SentrySDK.metrics` API to record metrics. If you need to disable metrics entirely, set `options.experimental.enableMetrics` to `false` when initializing the SDK:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.experimental.enableMetrics = false // Metrics are enabled by default
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.experimental.enableMetrics = NO; // Metrics are enabled by default
+}];
+```
+
+### 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
+- Changing metric names or units
+
+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 (`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 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.
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    // 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 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 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
+    }
+}
+```
+
+### 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. Note that this is a **blocking** call that will wait until all pending data is sent or the timeout is reached:
+
+```swift
+import Sentry
+
+SentrySDK.flush(timeout: 5.0)
+```
+
+This will flush all pending metrics and events to Sentry.

platform-includes/metrics/requirements/apple.mdx

@@ -0,0 +1 @@
+Metrics are supported in Sentry Cocoa SDK version `9.2.0` and above.