feat(apple): Add documentation for metrics

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`.
 
 </SdkOption>
+
+## Metrics Options
+
+<SdkOption name="enableMetrics" type="bool" defaultValue="false" availableSince="9.1.0">
+
+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 <PlatformLink to="/metrics/">Metrics documentation</PlatformLink>.
+
+</SdkOption>
+
+<SdkOption name="beforeSendMetric" type="function" availableSince="9.1.0">
+
+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
+    }
+}
+```
+
+</SdkOption>

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.
+
+<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" />

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.

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.

platform-includes/metrics/requirements/apple.mdx

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

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`.
+
+<Alert>
+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.
+</Alert>
+
+### 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"
+)
+```