@danieljvdm/dev-kit 1.0.1 → 2.0.0

package/skills/sentry/references/sdks/cocoa/logging.md

@@ -0,0 +1,209 @@
+# Logging — Sentry Cocoa SDK
+
+> Minimum SDK (experimental): `sentry-cocoa` v8.55.0+ Minimum SDK (stable):
+> `sentry-cocoa` v9.0.0+
+
+## Configuration
+
+| Option                    | Type                           | Default | Description                                                |
+| ------------------------- | ------------------------------ | ------- | ---------------------------------------------------------- |
+| `enableLogs`              | `Bool`                         | `false` | Enable structured logging (v9.0.0+, stable)                |
+| `experimental.enableLogs` | `Bool`                         | `false` | Enable structured logging (v8.55.0–8.x, experimental)      |
+| `beforeSendLog`           | `((SentryLog) -> SentryLog?)?` | `nil`   | Filter or modify logs before sending; return `nil` to drop |
+
+## Code Examples
+
+### Enable logging
+
+**SDK v9.0.0+ (stable, recommended):**
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.enableLogs = true
+}
+```
+
+**SDK v8.55.0–8.x (experimental):**
+
+```swift
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.experimental.enableLogs = true
+}
+```
+
+### All log levels
+
+```swift
+import Sentry
+
+let logger = SentrySDK.logger
+
+// Without attributes
+logger.trace("Starting database connection")
+logger.debug("Cache miss for user")
+logger.info("Profile updated successfully")
+logger.warn("Rate limit nearly reached")
+logger.error("Failed to process payment")
+logger.fatal("Database connection pool exhausted")
+
+// With structured attributes
+logger.trace("Starting DB connection",    attributes: ["database": "users"])
+logger.debug("Cache miss for user",       attributes: ["userId": 123])
+logger.info("Profile updated",            attributes: ["profileId": 345])
+logger.warn("Rate limit reached",         attributes: ["endpoint": "/api/results/"])
+logger.error("Payment failed",            attributes: ["amount": 99.99])
+logger.fatal("Connection pool exhausted", attributes: ["activeConnections": 100])
+```
+
+Supported Swift attribute value types include `String`, `Bool`, `Int`, `Double`,
+`Float`, arrays, and sets; other values are converted to strings.
+
+### Log levels (severity order)
+
+| Level     | Method              | Typical Use                         |
+| --------- | ------------------- | ----------------------------------- |
+| 1 — Trace | `logger.trace(...)` | Very fine-grained diagnostic events |
+| 2 — Debug | `logger.debug(...)` | Debugging information               |
+| 3 — Info  | `logger.info(...)`  | General informational messages      |
+| 4 — Warn  | `logger.warn(...)`  | Potentially harmful situations      |
+| 5 — Error | `logger.error(...)` | Error events; app may continue      |
+| 6 — Fatal | `logger.fatal(...)` | Severe errors; likely app abort     |
+
+### Swift string interpolation as structured attributes
+
+When you use Swift string interpolation in the message, the SDK automatically extracts
+the interpolated values as named attributes using the key pattern
+`sentry.message.parameter.{index}`:
+
+```swift
+let userId = "user_123"
+let orderCount = 5
+
+logger.info("User \(userId) placed \(orderCount) orders")
+
+// Sentry receives:
+//   message template: "User %s placed %d orders"
+//   sentry.message.parameter.0 = "user_123"
+//   sentry.message.parameter.1 = 5
+```
+
+This preserves the ability to search and filter by the template while retaining the
+individual values as queryable attributes.
+
+### beforeSendLog filter hook
+
+```swift
+SentrySDK.start { options in
+    options.enableLogs = true
+    options.beforeSendLog = { log in
+        // Drop trace-level logs
+        if log.level == .trace { return nil }
+
+        // Drop debug logs in production
+        if log.level == .debug && options.environment == "production" { return nil }
+
+        // Enrich all logs with app version
+        if let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String {
+            log.attributes["app.version"] = SentryAttribute(string: version)
+        }
+        return log
+    }
+}
+```
+
+Available on `SentryLog`:
+
+- `log.level` — `SentryLog.Level` (`.trace`, `.debug`, `.info`, `.warn`, `.error`,
+  `.fatal`)
+- `log.body` — `String`
+- `log.timestamp` — `Date`
+- `log.attributes` — `[String: SentryAttribute]`
+
+### Automatic default attributes
+
+The SDK automatically attaches the following to every log entry:
+
+- `environment` and `release`
+- SDK name and version
+- User ID, name, email (if set via `SentrySDK.setUser(...)`)
+- Message template and `sentry.message.parameter.*` interpolated values
+- Integration origin marker
+
+### Using alongside Apple os.log
+
+`SentrySDK.logger` is a standalone Sentry telemetry system — it is **not** a bridge to
+`os.log` / `Logger`. To write to both:
+
+```swift
+import OSLog
+import Sentry
+
+private let osLog = Logger(subsystem: "com.myapp", category: "network")
+
+func fetchData() {
+    osLog.info("Fetching data")                        // → system log / Console.app
+    SentrySDK.logger.info("Fetching data",             // → Sentry Logs
+                          attributes: ["subsystem": "network"])
+}
+```
+
+There is no built-in bridge to automatically forward `OSLog` entries to Sentry.
+
+### Full initialization example with logging
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.environment = "production"
+    options.enableLogs = true   // v9.0.0+
+    options.beforeSendLog = { log in
+        // Drop trace and debug in production
+        guard log.level != .trace && log.level != .debug else { return nil }
+        return log
+    }
+}
+
+// Anywhere in your app:
+SentrySDK.logger.info("User signed in",
+                      attributes: ["userId": currentUser.id, "method": "oauth"])
+```
+
+## Known Limitations
+
+- Logs can be **lost in crash scenarios** if the SDK cannot flush the buffer before the
+  app terminates — this is a known limitation of the current implementation
+- Logs are a **separate pipeline** from error events — they are not attached to
+  breadcrumbs or spans automatically
+- Attribute values are limited to `String`, `Int`, `Double`, and `Bool` — other types
+  must be converted
+
+## Best Practices
+
+- Prefer `logger.error(...)` or `logger.fatal(...)` over `SentrySDK.capture(message:)`
+  for application-level log lines — structured logs are easier to search and filter in
+  Sentry
+- Use structured attributes instead of embedding values in the message string directly;
+  attributes are indexed and queryable
+- Use Swift string interpolation to let the SDK extract attribute values automatically
+- Set `beforeSendLog` to drop `trace` and `debug` in production to reduce noise and
+  volume
+- Set the user via `SentrySDK.setUser(...)` before logging to automatically correlate
+  logs with user identities
+
+## Troubleshooting
+
+| Issue                             | Solution                                                                                                      |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Logs not appearing in Sentry      | Verify `options.enableLogs = true` (v9+) or `options.experimental.enableLogs = true` (v8.55+)                 |
+| Logs only partially appearing     | Logs may be lost during crashes; this is a known SDK limitation                                               |
+| `SentrySDK.logger` not found      | Requires v8.55.0+; check SPM/CocoaPods version                                                                |
+| Attributes not queryable          | Prefer `String`, `Bool`, `Int`, `Double`, `Float`, arrays, or sets; convert complex objects to stable strings |
+| `beforeSendLog` not called        | Ensure you set it before `SentrySDK.start` completes and `enableLogs = true`                                  |
+| Too many logs overwhelming Sentry | Use `beforeSendLog` to filter by level; set minimum level for production                                      |
+| Logs missing user context         | Call `SentrySDK.setUser(...)` before logging to attach user identity automatically                            |

package/skills/sentry/references/sdks/cocoa/metrics.md

@@ -0,0 +1,136 @@
+# Metrics — Sentry Cocoa SDK
+
+> Minimum SDK: experimental in v9.4.0+, generally available in v9.12.0+ Swift only;
+> Objective-C metrics API is not currently available.
+> Metrics are enabled by default in v9.12.0+.
+
+Use metrics for aggregate counters, gauges, and distributions that should not create
+Sentry issues. Do not duplicate automatic tracing, app hangs, MetricKit diagnostics, or
+error events.
+
+## Configuration
+
+| Option             | Type                                 | Default | Description                                                |
+| ------------------ | ------------------------------------ | ------- | ---------------------------------------------------------- |
+| `enableMetrics`    | `Bool`                               | `true`  | Enable or disable metrics                                  |
+| `beforeSendMetric` | `((SentryMetric) -> SentryMetric?)?` | `nil`   | Filter or mutate metrics before send; return `nil` to drop |
+
+For SDK 9.4.0-9.11.x, metrics used `options.experimental.enableMetrics` and
+`options.experimental.beforeSendMetric`. Those experimental options were removed in
+9.12.0; use the top-level options above.
+
+## Code Examples
+
+### Basic setup
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.enableMetrics = true  // default in SDK 9.12+
+}
+```
+
+### Counter
+
+Counters track discrete occurrences.
+`count` does not accept a unit.
+
+```swift
+SentrySDK.metrics.count(key: "button.click")
+
+SentrySDK.metrics.count(
+    key: "link.created",
+    value: 1,
+    attributes: [
+        "source": "share_extension",
+        "is_favorite": false
+    ]
+)
+```
+
+### Gauge
+
+Gauges track current state.
+
+```swift
+SentrySDK.metrics.gauge(
+    key: "queue.depth",
+    value: 42,
+    attributes: ["queue": "sync"]
+)
+```
+
+### Distribution
+
+Distributions track measured values where percentiles are useful.
+
+```swift
+SentrySDK.metrics.distribution(
+    key: "qr.render.duration",
+    value: 187.5,
+    unit: .millisecond,
+    attributes: [
+        "cache_hit": true,
+        "image_size": "1024"
+    ]
+)
+```
+
+### beforeSendMetric
+
+```swift
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.beforeSendMetric = { metric in
+        var metric = metric
+
+        if case let .boolean(drop)? = metric.attributes["drop_me"], drop {
+            return nil
+        }
+
+        metric.attributes["processed"] = .boolean(true)
+        metric.attributes["app_area"] = .string("links")
+        return metric
+    }
+}
+```
+
+## Attribute Types
+
+Metric attributes use `SentryAttributeValue` at the capture API and
+`SentryAttributeContent` inside `beforeSendMetric`.
+
+Supported capture values:
+
+- Scalar: `String`, `Bool`, `Int`, `Double`, `Float`
+- Arrays: `[String]`, `[Bool]`, `[Int]`, `[Double]`, `[Float]`
+- Sets: `Set<String>`, `Set<Bool>`, `Set<Int>`, `Set<Double>`, `Set<Float>` (SDK 9.13+)
+
+Use stable, low-cardinality attributes.
+Avoid URLs, IDs, user-entered names, or unbounded strings unless they are intentionally
+scrubbed and useful for grouping.
+
+## Best Practices
+
+- Use metrics for aggregate product and app-health signals, not exceptions or stack
+  traces.
+- Keep metric names lowercase and dot-delimited, such as `link.created` or
+  `network.reachability.changed`.
+- Prefer distributions for durations and sizes, gauges for current state, and counters
+  for occurrences.
+- Avoid metrics that duplicate automatic spans, failed request events, app hangs,
+  watchdog terminations, or MetricKit diagnostics.
+- Keep `enableMetrics = true` unless the app has a policy or volume reason to disable
+  metrics.
+
+## Troubleshooting
+
+| Issue                         | Solution                                                                           |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `enableMetrics` compile error | Requires SDK 9.12+; on 9.4-9.11 use `experimental.enableMetrics` or upgrade        |
+| Metric not sent               | Verify `SentrySDK.start` ran and `enableMetrics` is true                           |
+| Count with `unit` fails       | `count` has no `unit` parameter; use `gauge` or `distribution` if units are needed |
+| Objective-C compile issue     | Metrics are Swift-only                                                             |
+| Too many unique series        | Reduce high-cardinality attributes and metric names                                |

package/skills/sentry/references/sdks/cocoa/profiling.md

@@ -0,0 +1,223 @@
+# Profiling — Sentry Cocoa SDK
+
+> Minimum SDK for UI Profiling (`configureProfiling`): `sentry-cocoa` v8.49.0+ Minimum
+> SDK for stable `configureProfiling` API: v9.0.0+ Supported platforms: iOS and macOS.
+> Not supported on tvOS, watchOS, or visionOS. **All legacy profiling APIs
+> (`profilesSampleRate`, `enableAppLaunchProfiling`, continuous beta) were removed in
+> v9.0.0.**
+
+## Configuration
+
+| Option               | Type                                | Default   | Description                                                       |
+| -------------------- | ----------------------------------- | --------- | ----------------------------------------------------------------- |
+| `configureProfiling` | `((SentryProfileOptions) -> Void)?` | `nil`     | Closure to configure UI Profiling (v8.49.0+)                      |
+| `sessionSampleRate`  | `Float` (0.0–1.0)                   | `0`       | Fraction of user sessions to profile; evaluated once per session  |
+| `lifecycle`          | `SentryProfileLifecycle`            | `.manual` | `.trace` (auto) or `.manual` (explicit start/stop)                |
+| `profileAppStarts`   | `Bool`                              | `false`   | Profile from the earliest possible lifecycle stage on next launch |
+
+## Code Examples
+
+### Basic setup — trace lifecycle (recommended)
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+
+    // Tracing must be enabled for .trace lifecycle
+    options.tracesSampleRate = 1.0
+
+    options.configureProfiling = {
+        $0.sessionSampleRate = 1.0   // 100% of sessions; lower for production
+        $0.lifecycle = .trace        // profiler runs while a root span is active
+    }
+}
+```
+
+### Manual lifecycle — explicit start/stop
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.configureProfiling = {
+        $0.sessionSampleRate = 1.0
+        $0.lifecycle = .manual   // default if omitted
+    }
+}
+
+// Profile a specific operation
+@IBAction func onSyncTapped() {
+    SentrySDK.startProfiler()
+
+    URLSession.shared.dataTask(with: syncRequest) { data, _, _ in
+        self.processData(data)
+        DispatchQueue.main.async {
+            self.tableView.performBatchUpdates({
+                // update cells
+            }) { _ in
+                SentrySDK.stopProfiler()
+            }
+        }
+    }.resume()
+}
+```
+
+### App launch profiling (trace lifecycle)
+
+```swift
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.tracesSampleRate = 1.0
+    options.configureProfiling = {
+        $0.sessionSampleRate = 1.0
+        $0.lifecycle = .trace
+        $0.profileAppStarts = true   // profile from earliest lifecycle stage
+    }
+}
+```
+
+Launch profile attaches to a special `app.launch` transaction (shown as **“launch”** in
+the Sentry UI). The profiler stops automatically when:
+
+1. `SentrySDK.startWithOptions` is called, OR
+2. TTID/TTFD is reached (if TTID/TTFD tracking is enabled)
+
+### Manual lifecycle — app launch profiling
+
+With `.manual` lifecycle, a launch profile starts on the **next app launch** and
+continues until you explicitly call `SentrySDK.stopProfiler()`.
+
+### Compound sampling example
+
+```swift
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.tracesSampleRate = 0.5   // 50% of transactions traced
+    options.configureProfiling = {
+        $0.sessionSampleRate = 0.5   // 50% of those sessions profiled
+        $0.lifecycle = .trace
+        // Result: ~25% of root span creations will produce profile data (0.5 × 0.5)
+    }
+}
+```
+
+`sessionSampleRate` is evaluated **once per session**, not per span.
+The same decision applies to all profiler start attempts for the duration of that
+session.
+
+## SentryProfileLifecycle Values
+
+| Value     | Behaviour                                                                                      |
+| --------- | ---------------------------------------------------------------------------------------------- |
+| `.manual` | Profiler runs only between `SentrySDK.startProfiler()` and `SentrySDK.stopProfiler()`          |
+| `.trace`  | Profiler starts automatically when a new root span is created; stops when no root spans remain |
+
+## Manual Profiler Control
+
+```swift
+SentrySDK.startProfiler()   // begin profiling (manual lifecycle)
+SentrySDK.stopProfiler()    // end profiling and flush data to Sentry
+```
+
+## dSYM Upload Requirement
+
+Profiling data in Sentry shows symbolicated stack frames.
+Without dSYM files, frames appear as memory addresses.
+
+Upload dSYMs via the Sentry Wizard build phase (added automatically during wizard
+setup):
+
+```bash
+# Verify the build phase exists in Xcode:
+# Target → Build Phases → "Upload Debug Symbols to Sentry"
+# or manually:
+sentry-cli --auth-token YOUR_TOKEN debug-files upload \
+    --org YOUR_ORG \
+    --project YOUR_PROJECT \
+    path/to/dSYMs/
+```
+
+For CI/CD, set `SENTRY_AUTH_TOKEN` as an environment variable.
+
+## API History / Migration
+
+| API                                 | Introduced | Removed   | Notes                                           |
+| ----------------------------------- | ---------- | --------- | ----------------------------------------------- |
+| `profilesSampleRate`                | 8.12.0     | **9.0.0** | Transaction-based profiling                     |
+| `profilesSampler`                   | 8.12.0     | **9.0.0** | Dynamic transaction-based profiling             |
+| `enableAppLaunchProfiling`          | 8.21.0     | **9.0.0** | Launch profiling (old)                          |
+| Continuous profiling beta           | 8.36.0     | **9.0.0** | Standalone `startProfiler`/`stopProfiler` (old) |
+| `configureProfiling` (UI Profiling) | **8.49.0** | —         | **Current API**                                 |
+
+### Migrating from legacy `profilesSampleRate`
+
+```swift
+// BEFORE (removed in v9.0.0)
+SentrySDK.start { options in
+    options.tracesSampleRate = 1.0
+    options.profilesSampleRate = 1.0   // Removed: no longer exists
+}
+
+// AFTER (v9.0.0+)
+SentrySDK.start { options in
+    options.tracesSampleRate = 1.0
+    options.configureProfiling = {
+        $0.sessionSampleRate = 1.0
+        $0.lifecycle = .trace          // Equivalent behavior
+    }
+}
+```
+
+## MetricKit App Hang Reports
+
+MetricKit delivers hang diagnostic payloads on iOS 15+ and macOS 12+. Starting with
+**sentry-cocoa v9.x** (merged via PR #7185), the SDK captures the **full call-tree
+flamegraph** from a MetricKit hang report instead of a single stack sample.
+
+- **No configuration required** — the improvement is automatic for all apps with
+  MetricKit-compatible OS versions
+- In the Sentry UI, MetricKit hang issues now display a flamegraph showing all samples
+  collected during the hang, improving both diagnosis and issue grouping accuracy
+- MetricKit reports are delivered by the OS after the hang ends (typically on next
+  launch); they complement — but do not replace — real-time app hang detection
+  (automatic in SDK v9+)
+
+| Platform | MetricKit Availability |
+| -------- | ---------------------- |
+| iOS      | 15+                    |
+| macOS    | 12+                    |
+| tvOS     | No                     |
+| watchOS  | No                     |
+| visionOS | No                     |
+
+## Best Practices
+
+- Always set `sessionSampleRate > 0` — it defaults to `0`, so no profiling data is
+  collected unless you explicitly set it
+- Use `.trace` lifecycle in production: the profiler only runs during active
+  transactions, minimising overhead
+- Use `.manual` lifecycle to profile targeted operations (e.g., a specific button tap, a
+  batch import)
+- Lower `sessionSampleRate` in production (e.g., `0.1`) — profiling adds CPU overhead on
+  older devices
+- Upload dSYMs for every build; without them, profile data shows raw addresses
+- `profileAppStarts = true` is most valuable for identifying slow
+  `+[AppDelegate application:didFinishLaunchingWithOptions:]` work
+- Do not combine the old `profilesSampleRate` with `configureProfiling` — the old APIs
+  are removed in v9.0.0
+
+## Troubleshooting
+
+| Issue                                   | Solution                                                                                            |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| No profiling data in Sentry             | Verify `sessionSampleRate > 0`; it defaults to `0`                                                  |
+| Profiles missing for `.trace` lifecycle | Verify `tracesSampleRate > 0`; profiles only appear when transactions are sent                      |
+| Stack frames show memory addresses      | Upload dSYMs; verify build phase runs in both Debug and Release                                     |
+| Profiling not starting on app launch    | Use `profileAppStarts = true`; SDK must be initialised with `SentrySDK.startWithOptions`            |
+| `configureProfiling` not available      | Requires v8.49.0+; check your SPM/CocoaPods version                                                 |
+| Old `profilesSampleRate` not compiling  | Removed in v9.0.0; migrate to `configureProfiling`                                                  |
+| Manual profiler never stops             | Ensure `SentrySDK.stopProfiler()` is called on all code paths, including error branches             |
+| Excessive CPU overhead                  | Lower `sessionSampleRate`; switch to `.trace` lifecycle; avoid `.manual` with long-running sessions |