docs(apple): Add docs for structured logs (#14687)

Author: denrase

docs/platforms/apple/common/index.mdx

@@ -36,13 +36,13 @@ Select which Sentry features you'd like to install in addition to Error Monitori
 
 <PlatformSection notSupported={["apple.tvos", "apple.watchos", "apple.visionos"]}>
 
-<OnboardingOptionButtons options={['error-monitoring', 'performance', 'profiling', 'session-replay']}/>
+<OnboardingOptionButtons options={['error-monitoring', 'performance', 'profiling', 'session-replay', 'logs']}/>
 
 </PlatformSection>
 
 <PlatformSection notSupported={["apple.ios", "apple.macos"]}>
 
-<OnboardingOptionButtons options={['error-monitoring', 'performance']}/>
+<OnboardingOptionButtons options={['error-monitoring', 'performance', 'logs']}/>
 
 </PlatformSection>
 
@@ -104,25 +104,30 @@ func application(_ application: UIApplication,
         // Adds IP for users.
         // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/
         options.sendDefaultPii = true
-
         // ___PRODUCT_OPTION_START___ performance
+
         // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring.
         // We recommend adjusting this value in production.
         options.tracesSampleRate = 1
         // ___PRODUCT_OPTION_END___ performance
-
         // ___PRODUCT_OPTION_START___ profiling
+
         options.configureProfiling = {
             $0.lifecycle = .trace
             $0.sessionSampleRate = 1
         }
         // ___PRODUCT_OPTION_END___ profiling
-
         // ___PRODUCT_OPTION_START___ session-replay
+
         // Record session replays for 100% of errors and 10% of sessions
         options.sessionReplay.onErrorSampleRate = 1.0
         options.sessionReplay.sessionSampleRate = 0.1
         // ___PRODUCT_OPTION_END___ session-replay
+        // ___PRODUCT_OPTION_START___ logs
+
+        // Enable logs to be sent to Sentry
+        options.experimental.enableLogs = true
+        // ___PRODUCT_OPTION_END___ logs
     }
 
     return true
@@ -141,25 +146,30 @@ func application(_ application: UIApplication,
         // Adds IP for users.
         // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/
         options.sendDefaultPii = YES;
-
         // ___PRODUCT_OPTION_START___ performance
+
         // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring.
         // We recommend adjusting this value in production.
         options.tracesSampleRate = @1.f;
         // ___PRODUCT_OPTION_END___ performance
-
         // ___PRODUCT_OPTION_START___ profiling
+
         options.configureProfiling = ^(SentryProfileOptions *profiling) {
             profiling.lifecycle = SentryProfileLifecycleTrace;
             profiling.sessionSampleRate = 1.f;
         };
         // ___PRODUCT_OPTION_END___ profiling
-
         // ___PRODUCT_OPTION_START___ session-replay
+
         // Record session replays for 100% of errors and 10% of sessions
         options.sessionReplay.onErrorSampleRate = 1.0;
         options.sessionReplay.sessionSampleRate = 0.1;
         // ___PRODUCT_OPTION_END___ session-replay
+        // ___PRODUCT_OPTION_START___ logs
+
+        // Enable logs to be sent to Sentry
+        options.experimental.enableLogs = YES;
+        // ___PRODUCT_OPTION_END___ logs
     }];
 
     return YES;
@@ -179,25 +189,29 @@ struct SwiftUIApp: App {
             // Adds IP for users.
             // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/
             options.sendDefaultPii = true
-
             // ___PRODUCT_OPTION_START___ performance
+
             // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring.
             // We recommend adjusting this value in production.
             options.tracesSampleRate = 1
             // ___PRODUCT_OPTION_END___ performance
-
             // ___PRODUCT_OPTION_START___ profiling
+
             options.configureProfiling = {
                 $0.lifecycle = .trace
                 $0.sessionSampleRate = 1
             }
             // ___PRODUCT_OPTION_END___ profiling
-
             // ___PRODUCT_OPTION_START___ session-replay
             // Record session replays for 100% of errors and 10% of sessions
             options.sessionReplay.onErrorSampleRate = 1.0
             options.sessionReplay.sessionSampleRate = 0.1
             // ___PRODUCT_OPTION_END___ session-replay
+
+            // ___PRODUCT_OPTION_START___ logs
+            // Enable logs to be sent to Sentry
+            options.experimental.enableLogs = true
+            // ___PRODUCT_OPTION_END___ logs
         }
     }
 }
@@ -219,19 +233,24 @@ func application(_ application: UIApplication,
         // Adds IP for users.
         // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/
         options.sendDefaultPii = true
-
         // ___PRODUCT_OPTION_START___ performance
+
         // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring.
         // We recommend adjusting this value in production.
         options.tracesSampleRate = 1
         // ___PRODUCT_OPTION_END___ performance
-
         // ___PRODUCT_OPTION_START___ profiling
+
         options.configureProfiling = {
             $0.lifecycle = .trace
             $0.sessionSampleRate = 1
         }
         // ___PRODUCT_OPTION_END___ profiling
+        // ___PRODUCT_OPTION_START___ logs
+
+        // Enable logs to be sent to Sentry
+        options.experimental.enableLogs = true
+        // ___PRODUCT_OPTION_END___ logs
     }
 
     return true
@@ -263,6 +282,11 @@ func application(_ application: UIApplication,
             profiling.sessionSampleRate = 1.f;
         };
         // ___PRODUCT_OPTION_END___ profiling
+        // ___PRODUCT_OPTION_START___ logs
+
+        // Enable logs to be sent to Sentry
+        options.experimental.enableLogs = YES;
+        // ___PRODUCT_OPTION_END___ logs
     }];
 
     return YES;
@@ -282,19 +306,24 @@ struct SwiftUIApp: App {
             // Adds IP for users.
             // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/
             options.sendDefaultPii = true
-
             // ___PRODUCT_OPTION_START___ performance
+
             // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring.
             // We recommend adjusting this value in production.
             options.tracesSampleRate = 1
             // ___PRODUCT_OPTION_END___ performance
-
             // ___PRODUCT_OPTION_START___ profiling
+
             options.configureProfiling = {
                 $0.lifecycle = .trace
                 $0.sessionSampleRate = 1
             }
             // ___PRODUCT_OPTION_END___ profiling
+            // ___PRODUCT_OPTION_START___ logs
+
+            // Enable logs to be sent to Sentry
+            options.experimental.enableLogs = true
+            // ___PRODUCT_OPTION_END___ logs
         }
     }
 }
@@ -318,12 +347,17 @@ func applicationDidFinishLaunching() {
         // Adds IP for users.
         // For more information, visit: https://docs.sentry.io/platforms/apple/data-management/data-collected/
         options.sendDefaultPii = true
-
         // ___PRODUCT_OPTION_START___ performance
+
         // Set tracesSampleRate to 1 to capture 100% of transactions for performance monitoring.
         // We recommend adjusting this value in production.
         options.tracesSampleRate = 1
         // ___PRODUCT_OPTION_END___ performance
+        // ___PRODUCT_OPTION_START___ logs
+
+        // Enable logs to be sent to Sentry
+        options.experimental.enableLogs = true
+        // ___PRODUCT_OPTION_END___ logs
     }
 }
 ```

docs/platforms/apple/common/logs/index.mdx

@@ -0,0 +1,26 @@
+---
+title: Set Up Logs
+sidebar_title: Logs
+description: "Structured logs allow you to send, view and query logs sent from your applications within Sentry."
+sidebar_order: 5755
+---
+
+<Include name="feature-stage-beta-logs.mdx" />
+
+With Sentry Structured Logs, you can send text based log information from your applications to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes.
+
+## Requirements
+
+<PlatformContent includePath="logs/requirements" />
+
+## Setup
+
+<PlatformContent includePath="logs/setup" />
+
+## Usage
+
+<PlatformContent includePath="logs/usage" />
+
+## Options
+
+<PlatformContent includePath="logs/options" />

platform-includes/logs/options/apple.mdx

@@ -0,0 +1,46 @@
+#### beforeSendLog
+
+To filter logs, or update them before they are sent to Sentry, you can use the `beforeSendLog` option.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.experimental.enableLogs = true
+    
+    options.beforeSendLog = { log in
+        if log.level == .info {
+            // Filter out all info logs
+            return nil
+        }
+        return log
+    }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.experimental.enableLogs = YES;
+    
+    options.beforeSendLog = ^SentryLog* (SentryLog *log) {
+        if (log.level == SentryStructuredLogLevelInfo) {
+            // Filter out all info logs
+            return nil;
+        }
+        return log;
+    };
+}];
+```
+
+The `beforeSendLog` function receives a log object, and should return the log object if you want it to be sent to Sentry, or `nil` if you want to discard it.
+
+The log object has the following properties:
+
+- `level`: The log level (trace, debug, info, warn, error, fatal)
+- `message`: The message to be logged
+- `timestamp`: The timestamp of the log
+- `attributes`: The attributes of the log

platform-includes/logs/requirements/apple.mdx

@@ -0,0 +1 @@
+Logs for Apple platforms are supported in Sentry Cocoa SDK version `8.55.0` and above. Logs are still experimental and the API may change in the future.

platform-includes/logs/setup/apple.mdx

@@ -0,0 +1,21 @@
+To enable logging, you need to initialize the SDK with the experimental `enableLogs` option set to `true`.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    // Enable logs to be sent to Sentry
+    options.experimental.enableLogs = true
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    // Enable logs to be sent to Sentry
+    options.experimental.enableLogs = YES;
+}];
+```

platform-includes/logs/usage/apple.mdx

@@ -0,0 +1,86 @@
+Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `Sentry.logger` APIs.
+
+The `Sentry.logger` namespace exposes six methods that you can use to log messages at different log levels: `trace`, `debug`, `info`, `warn`, `error`, and `fatal`. Supported types for attributes are Strings, Int, Double, and Bool.
+
+```swift {tabTitle:Swift}
+import Sentry
+
+let logger = SentrySDK.logger
+
+// Log messages without attributes
+logger.trace("Starting database connection")
+logger.debug("Cache miss for user")
+logger.info("Updated profile")
+
+// Log messages with attributes
+logger.trace("Starting database connection", attributes: ["database": "users"])
+logger.debug("Cache miss for user", attributes: ["userId": 123])
+logger.info("Updated profile", attributes: ["profileId": 345])
+logger.warn("Rate limit reached for endpoint", attributes: [
+    "endpoint": "/api/results/",
+    "isEnterprise": false
+])
+logger.error("Failed to process payment", attributes: [
+    "orderId": "order_123",
+    "amount": 99.99
+])
+logger.fatal("Database connection pool exhausted", attributes: [
+    "database": "users",
+    "activeConnections": 100
+])
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+SentryLogger *logger = SentrySDK.logger;
+
+// Log messages without attributes
+[logger trace:@"Starting database connection"];
+[logger debug:@"Cache miss for user"];
+[logger info:@"Updated profile"];
+
+// Log messages with attributes
+[logger trace:@"Starting database connection" attributes:@{@"database": @"users"}];
+[logger debug:@"Cache miss for user" attributes:@{@"userId": @123}];
+[logger info:@"Updated profile" attributes:@{@"profileId": @345}];
+[logger warn:@"Rate limit reached for endpoint" attributes:@{
+    @"endpoint": @"/api/results/",
+    @"isEnterprise": @NO
+}];
+[logger error:@"Failed to process payment" attributes:@{
+    @"orderId": @"order_123",
+    @"amount": @99.99
+}];
+[logger fatal:@"Database connection pool exhausted" attributes:@{
+    @"database": @"users",
+    @"activeConnections": @100
+}];
+```
+
+### String Interpolation (Swift Only)
+
+Swift supports automatic extraction of interpolated values as attributes. When you use string interpolation in your log messages, supported types (Strings, Int, Double, and Bool) are automatically extracted and added as attributes with the key format `sentry.message.parameter.{index}`.
+
+```swift
+let userId = "user_123"
+let orderCount = 5
+let isPremium = true
+let totalAmount = 99.99
+
+// String interpolation automatically extracts values as attributes
+logger.info("User \(userId) placed \(orderCount) orders, premium: \(isPremium), total: $\(totalAmount)")
+
+// This is equivalent to manually specifying attributes:
+let message = "User \(userId) placed \(orderCount) orders, premium: \(isPremium), total: $\(totalAmount)"
+logger.info(
+  message,
+  attributes: [
+      "sentry.message.template": "User {0} placed {1} orders, premium: {2}, total: {3}",
+      "sentry.message.parameter.0": userId,
+      "sentry.message.parameter.1": orderCount,
+      "sentry.message.parameter.2": isPremium,
+      "sentry.message.parameter.3": totalAmount
+  ]
+)
+```