sentry-cocoa-sdk by getsentry/sentry-for-ai
npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-cocoa-sdk一个智能向导,它会扫描您的 Apple 项目并指导您完成完整的 Sentry 设置。
sentry-cocoa、SentrySDK 或 Apple/iOS 的 Sentry SDK注意: 下文中的 SDK 版本和 API 反映了撰写本文时(sentry-cocoa 9.5.1)的 Sentry 文档。在实施前,请务必对照 docs.sentry.io/platforms/apple/ 进行验证。
在提出任何建议之前,运行以下命令来了解项目情况:
# 检查现有的 Sentry 依赖
grep -i sentry Package.swift Podfile Cartfile 2>/dev/null
# 检测 UI 框架 (SwiftUI vs UIKit)
grep -rE "@main|struct.*App.*:.*App" --include="*.swift" . 2>/dev/null | head -5
grep -rE "AppDelegate|UIApplicationMain" --include="*.swift" . 2>/dev/null | head -5
# 检测平台和部署目标
grep -E "platforms:|\.iOS|\.macOS|\.tvOS|\.watchOS|\.visionOS" Package.swift 2>/dev/null
grep -E "platform :ios|platform :osx|platform :tvos|platform :watchos" Podfile 2>/dev/null
# 检测日志记录
grep -rE "import OSLog|os\.log|CocoaLumberjack|DDLog" --include="*.swift" . 2>/dev/null | head -5
# 检测配套后端
ls ../backend ../server ../api 2>/dev/null
ls ../go.mod ../requirements.txt ../Gemfile ../package.json 2>/dev/null
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
需要注意的事项:
Package.swift 或 Podfile 中是否已存在 sentry-cocoa?如果是,则跳转到阶段 2(配置功能)。@main App 结构体) 还是 UIKit (AppDelegate)?这决定了初始化模式。根据您的发现,提出具体的建议。不要问开放式问题 — 直接给出方案:
推荐(核心覆盖):
可选(增强可观测性):
Cocoa 不可用:
推荐逻辑:
| 功能 | 推荐时机... |
|---|---|
| 错误监控 | 始终 — 不可或缺的基线 |
| 追踪 | 应用始终启用 — 开箱即用的丰富自动检测 |
| 性能分析 | 性能至关重要的生产环境应用 |
| 会话回放 | 仅限 iOS 面向用户的应用(检查 iOS 26+ 注意事项;不适用于 tvOS/macOS/watchOS/visionOS) |
| 日志记录 | 现有 os.log / CocoaLumberjack 使用,或需要结构化日志 |
| 用户反馈 | 希望获得带有截图的应用程序内错误报告的应用 |
建议措辞:"我推荐错误监控 + 追踪 + 性能分析。您希望我同时添加会话回放和日志记录吗?"
选项 1 — Sentry 向导(推荐):
您需要自己运行此命令 — 该向导会打开浏览器进行登录,并需要交互式输入,这是代理无法处理的。请复制粘贴到您的终端:
brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios它会处理登录、组织/项目选择、身份验证令牌设置、SDK 安装、AppDelegate 更新以及 dSYM/调试符号上传构建阶段。
一旦完成,请返回并跳转到验证部分。
如果用户跳过了向导,请继续执行选项 2(SPM/CocoaPods)和下面的手动设置。
选项 2 — Swift Package Manager: 文件 → 添加包 → 输入:
https://github.com/getsentry/sentry-cocoa.git
或在 Package.swift 中:
.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.5.1"),
SPM 产品 — 每个目标仅选择一项:
| 产品 | 使用场景 |
|---|---|
Sentry | 推荐 — 静态框架,应用启动快 |
Sentry-Dynamic | 动态框架替代方案 |
SentrySwiftUI | SwiftUI 视图性能追踪 (SentryTracedView) |
Sentry-WithoutUIKitOrAppKit | watchOS、应用扩展、CLI 工具 (Swift < 6.1) |
SentrySPM + NoUIFramework 特性 | watchOS、应用扩展、macOS CLI 工具 (仅限 Swift 6.1+ / Xcode 16.3+) |
⚠️ Xcode 允许选择多个产品 — 请只选择一个。
Swift 6.1+ 基于特性的 UIKit/AppKit 选择退出(需要 Package@swift-6.1.swift 清单):
// Package.swift (Swift 6.1+)
.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.5.1"),
// 在您目标的依赖项中:
.product(name: "SentrySPM", package: "sentry-cocoa", condition: .when(traits: ["NoUIFramework"]))
这是 Swift 6.1+ 上 macOS 命令行工具和应用扩展的首选退出路径。对于 Swift < 6.1,请继续使用 Sentry-WithoutUIKitOrAppKit。
注意: 从 Xcode 26.4+(目前处于测试版)开始,包特性在 Xcode UI 中可见。在较旧的 Xcode 版本上,特性在
Package.swift中声明时仍然有效,但不会出现在 GUI 中。
选项 3 — CocoaPods:
platform :ios, '11.0'
use_frameworks!
target 'YourApp' do
pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '9.5.1'
end
已知问题 (Xcode 14+): 沙盒
rsync.samba错误 → 目标设置 → "启用用户脚本沙盒" →NO。
完整的配置,以合理的默认值启用最多功能。在应用启动时,在任何其他代码之前添加。
SwiftUI — 应用入口点:
import SwiftUI
import Sentry
@main
struct MyApp: App {
init() {
SentrySDK.start { options in
options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
?? "https://examplePublicKey@o0.ingest.sentry.io/0"
options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
options.releaseName = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
// 错误监控(默认开启 — 为清晰起见显式声明)
options.enableCrashHandler = true
options.enableAppHangTrackingV2 = true
options.enableWatchdogTerminationTracking = true
options.attachScreenshot = true
options.attachViewHierarchy = true
options.sendDefaultPii = true
// 追踪
options.tracesSampleRate = 1.0 // 在高流量生产环境中降低到 0.2
// 性能分析 (SDK 9.0.0+ API)
options.configureProfiling = {
$0.sessionSampleRate = 1.0
$0.lifecycle = .trace
}
// 会话回放 (在 iOS 26+ 上默认禁用 — 配置是安全的)
options.sessionReplay.sessionSampleRate = 1.0
options.sessionReplay.onErrorSampleRate = 1.0
// 日志记录 (SDK 9.0.0+ 顶级选项;在 8.x 中使用 options.experimental.enableLogs)
options.enableLogs = true
}
}
var body: some Scene {
WindowGroup { ContentView() }
}
}
UIKit — AppDelegate:
import UIKit
import Sentry
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
SentrySDK.start { options in
options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
?? "https://examplePublicKey@o0.ingest.sentry.io/0"
options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
options.releaseName = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
options.enableCrashHandler = true
options.enableAppHangTrackingV2 = true
options.enableWatchdogTerminationTracking = true
options.attachScreenshot = true
options.attachViewHierarchy = true
options.sendDefaultPii = true
options.tracesSampleRate = 1.0
options.configureProfiling = {
$0.sessionSampleRate = 1.0
$0.lifecycle = .trace
}
options.sessionReplay.sessionSampleRate = 1.0
options.sessionReplay.onErrorSampleRate = 1.0
// 日志记录 (SDK 9.0.0+ 顶级选项;在 8.x 中使用 options.experimental.enableLogs)
options.enableLogs = true
}
return true
}
}
⚠️ SDK 初始化必须在主线程上进行。
逐个功能进行指导。为每个功能加载参考文件,按照其步骤操作,并在继续下一个之前进行验证:
| 功能 | 参考文件 | 加载时机... |
|---|---|---|
| 错误监控 | ${SKILL_ROOT}/references/error-monitoring.md | 始终(基线) |
| 追踪 | ${SKILL_ROOT}/references/tracing.md | 应用启动、网络、UIViewController 性能 |
| 性能分析 | ${SKILL_ROOT}/references/profiling.md | 生产环境对性能敏感的应用 |
| 会话回放 | ${SKILL_ROOT}/references/session-replay.md | 面向用户的 iOS/tvOS 应用 |
| 日志记录 | ${SKILL_ROOT}/references/logging.md | 需要结构化日志捕获时 |
| 用户反馈 | ${SKILL_ROOT}/references/user-feedback.md | 需要应用程序内错误报告时 |
对于每个功能:读取 ${SKILL_ROOT}/references/<feature>.md,严格按照步骤操作,验证其是否有效。
SentryOptions 字段| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
dsn | String | "" | 如果为空则 SDK 禁用;读取 SENTRY_DSN 环境变量 |
environment | String | "" | 例如,"production";读取 SENTRY_ENVIRONMENT 环境变量 |
releaseName | String | "" | 例如,"my-app@1.0.0";读取 SENTRY_RELEASE 环境变量 |
debug | Bool | false | 详细的 SDK 输出 — 在生产环境中禁用 |
sendDefaultPii | Bool | false | 包含来自活动集成的 IP、用户信息 |
enableCrashHandler | Bool | true | 崩溃报告的主开关 |
enableAppHangTrackingV2 | Bool | true (9.0+) | 区分完全/非完全阻塞的卡顿 |
appHangTimeoutInterval | Double | 2.0 | 在归类为卡顿之前的秒数 |
enableWatchdogTerminationTracking | Bool | true | 追踪看门狗终止 (iOS, tvOS, Mac Catalyst) |
attachScreenshot | Bool | false | 在错误时捕获屏幕截图 |
attachViewHierarchy | Bool | false | 在错误时捕获视图层次结构 |
tracesSampleRate | NSNumber? | nil | 事务采样率 (nil = 追踪禁用);Swift 自动装箱 Double 字面量 (例如 1.0 → NSNumber) |
tracesSampler | Closure | nil | 动态的每事务采样(覆盖采样率) |
enableAutoPerformanceTracing | Bool | true | 自动检测的主开关 |
tracePropagationTargets | [String] | [".*"] | 接收分布式追踪头信息的主机/正则表达式 |
enableCaptureFailedRequests | Bool | true | 自动将 HTTP 5xx 错误捕获为事件 |
enableNetworkBreadcrumbs | Bool | true | 为发出的 HTTP 请求添加面包屑 |
inAppInclude | [String] | [] | 被视为“应用内”代码的模块前缀 |
maxBreadcrumbs | Int | 100 | 每个事件的最大面包屑数量 |
sampleRate | Float | 1.0 | 错误事件采样率 |
beforeSend | Closure | nil | 用于修改/丢弃错误事件的钩子 |
onCrashedLastRun | Closure | nil | 在崩溃后的下一次启动时调用 |
| 变量 | 映射到 | 用途 |
|---|---|---|
SENTRY_DSN | dsn | 数据源名称 |
SENTRY_RELEASE | releaseName | 应用版本 (例如,my-app@1.0.0) |
SENTRY_ENVIRONMENT | environment | 部署环境 |
| 功能 | iOS | tvOS | macOS | watchOS | visionOS |
|---|---|---|---|---|---|
| 崩溃报告 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 应用卡顿 V2 | ✅ | ✅ | ❌ | ❌ | ❌ |
| 看门狗终止 | ✅ | ✅ | ❌ | ❌ | ❌ |
| 应用启动追踪 | ✅ | ✅ | ❌ | ❌ | ✅ |
| UIViewController 追踪 | ✅ | ✅ | ❌ | ❌ | ✅ |
| SwiftUI 追踪 | ✅ | ✅ | ✅ | ❌ | ✅ |
| 网络追踪 | ✅ | ✅ | ✅ | ❌ | ✅ |
| 性能分析 | ✅ | ✅ | ✅ | ❌ | ✅ |
| 会话回放 | ✅ | ❌ | ❌ | ❌ | ❌ |
| MetricKit | ✅ (15+) | ❌ | ✅ (12+) | ❌ | ❌ |
测试 Sentry 是否正在接收事件:
// 触发一个测试错误事件:
SentrySDK.capture(message: "Sentry Cocoa SDK test")
// 或者测试崩溃报告(不带调试器 — 崩溃会被调试器拦截):
// SentrySDK.crash() // 取消注释,不带调试器运行,重新启动以查看崩溃报告
在几秒钟内检查 Sentry 仪表板。如果没有出现任何内容:
options.debug = true — 将 SDK 内部信息打印到 Xcode 控制台降低生产环境的采样率以控制数据量和成本:
options.tracesSampleRate = 0.2 // 20% 的事务
options.configureProfiling = {
$0.sessionSampleRate = 0.1 // 10% 的会话
$0.lifecycle = .trace
}
options.sessionReplay.sessionSampleRate = 0.1 // 10% 连续采样
options.sessionReplay.onErrorSampleRate = 1.0 // 错误时 100% 采样(保持高位)
options.debug = false // 生产环境绝不要启用
完成 Apple 端设置后,检查是否有配套后端缺少 Sentry 覆盖:
# 检测配套后端
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod 2>/dev/null | head -5
cat ../requirements.txt ../Pipfile 2>/dev/null | head -5
cat ../Gemfile 2>/dev/null | head -5
cat ../package.json 2>/dev/null | grep -E '"name"|"dependencies"' | head -5
如果发现后端,请配置 tracePropagationTargets 以启用端到端的分布式追踪,并建议使用匹配的技能:
| 检测到的后端 | 建议技能 | 追踪头支持 |
|---|---|---|
Go (go.mod) | sentry-go-sdk | ✅ 自动 |
Python (requirements.txt) | sentry-python-sdk | ✅ 自动 |
Ruby (Gemfile) | sentry-ruby-sdk | ✅ 自动 |
Node.js 后端 (package.json) | sentry-node-sdk (或 sentry-express-sdk) | ✅ 自动 |
| 问题 | 解决方案 |
|---|---|
| 事件未出现 | 设置 debug: true,验证 DSN 格式,确保在主线程初始化 |
| 崩溃未捕获 | 在没有调试器附加的情况下运行 — 调试器会拦截信号 |
| 应用卡顿未报告 | 当调试器附加时自动禁用;检查 appHangTimeoutInterval |
| 会话回放未录制 | 检查 iOS 版本 — 在 iOS 26+ (Liquid Glass) 上默认禁用;验证 sessionSampleRate > 0 |
| 追踪数据缺失 | 确认 tracesSampleRate > 0;检查 enableAutoPerformanceTracing = true |
| 性能分析数据缺失 | 验证 configureProfiling 中的 sessionSampleRate > 0;对于 .trace 生命周期,必须启用追踪 |
rsync.samba 构建错误 (CocoaPods) | 目标设置 → "启用用户脚本沙盒" → NO |
| 选择了多个 SPM 产品 | 仅选择一项:Sentry、Sentry-Dynamic、SentrySwiftUI、Sentry-WithoutUIKitOrAppKit 或 SentrySPM(在 Swift 6.1+ 上带有 NoUIFramework 特性) |
inAppExclude 编译错误 | 在 SDK 9.0.0 中已移除 — 仅使用 inAppInclude |
| 看门狗终止未追踪 | 需要 enableCrashHandler = true(默认已启用) |
| 网络面包屑缺失 | 需要 enableSwizzling = true(默认已启用) |
profilesSampleRate 编译错误 | 在 SDK 9.0.0 中已移除 — 改用 configureProfiling 闭包 |
每周安装量
164
代码库
GitHub 星标数
82
首次出现
2026年3月1日
安全审计
安装于
codex163
gemini-cli160
cursor160
github-copilot159
kimi-cli159
opencode159
All Skills > SDK Setup > Cocoa SDK
Opinionated wizard that scans your Apple project and guides you through complete Sentry setup.
sentry-cocoa, SentrySDK, or the Apple/iOS Sentry SDKNote: SDK versions and APIs below reflect Sentry docs at time of writing (sentry-cocoa 9.5.1). Always verify against docs.sentry.io/platforms/apple/ before implementing.
Run these commands to understand the project before making any recommendations:
# Check existing Sentry dependency
grep -i sentry Package.swift Podfile Cartfile 2>/dev/null
# Detect UI framework (SwiftUI vs UIKit)
grep -rE "@main|struct.*App.*:.*App" --include="*.swift" . 2>/dev/null | head -5
grep -rE "AppDelegate|UIApplicationMain" --include="*.swift" . 2>/dev/null | head -5
# Detect platform and deployment targets
grep -E "platforms:|\.iOS|\.macOS|\.tvOS|\.watchOS|\.visionOS" Package.swift 2>/dev/null
grep -E "platform :ios|platform :osx|platform :tvos|platform :watchos" Podfile 2>/dev/null
# Detect logging
grep -rE "import OSLog|os\.log|CocoaLumberjack|DDLog" --include="*.swift" . 2>/dev/null | head -5
# Detect companion backend
ls ../backend ../server ../api 2>/dev/null
ls ../go.mod ../requirements.txt ../Gemfile ../package.json 2>/dev/null
What to note:
sentry-cocoa already in Package.swift or Podfile? If yes, skip to Phase 2 (configure features).@main App struct) or UIKit (AppDelegate)? Determines init pattern.Based on what you found, present a concrete recommendation. Don't ask open-ended questions — lead with a proposal:
Recommended (core coverage):
Optional (enhanced observability):
Not available for Cocoa:
Recommendation logic:
| Feature | Recommend when... |
|---|---|
| Error Monitoring | Always — non-negotiable baseline |
| Tracing | Always for apps — rich auto-instrumentation out of the box |
| Profiling | Production apps where performance matters |
| Session Replay | iOS only user-facing apps (check iOS 26+ caveat; not tvOS/macOS/watchOS/visionOS) |
| Logging | Existing os.log / CocoaLumberjack usage, or structured logs needed |
| User Feedback | Apps wanting in-app bug reports with screenshots |
Propose: "I recommend Error Monitoring + Tracing + Profiling. Want me to also add Session Replay and Logging?"
Option 1 — Sentry Wizard (recommended):
You need to run this yourself — the wizard opens a browser for login and requires interactive input that the agent can't handle. Copy-paste into your terminal:
brew install getsentry/tools/sentry-wizard && sentry-wizard -i iosIt handles login, org/project selection, auth token setup, SDK installation, AppDelegate updates, and dSYM/debug symbol upload build phases.
Once it finishes, come back and skip toVerification.
If the user skips the wizard, proceed with Option 2 (SPM/CocoaPods) and manual setup below.
Option 2 — Swift Package Manager: File → Add Packages → enter:
https://github.com/getsentry/sentry-cocoa.git
Or in Package.swift:
.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.5.1"),
SPM Products — choose exactly one per target:
| Product | Use Case |
|---|---|
Sentry | Recommended — static framework, fast app start |
Sentry-Dynamic | Dynamic framework alternative |
SentrySwiftUI | SwiftUI view performance tracking (SentryTracedView) |
Sentry-WithoutUIKitOrAppKit | watchOS, app extensions, CLI tools (Swift < 6.1) |
SentrySPM + NoUIFramework trait |
⚠️ Xcode allows selecting multiple products — choose only one.
Swift 6.1+ trait-based opt-out of UIKit/AppKit (requires Package@swift-6.1.swift manifest):
// Package.swift (Swift 6.1+)
.package(url: "https://github.com/getsentry/sentry-cocoa", from: "9.5.1"),
// In your target's dependencies:
.product(name: "SentrySPM", package: "sentry-cocoa", condition: .when(traits: ["NoUIFramework"]))
This is the preferred opt-out path for macOS command-line tools and app extensions on Swift 6.1+. For Swift < 6.1 continue using Sentry-WithoutUIKitOrAppKit.
Note: Package traits are visible in the Xcode UI starting with Xcode 26.4+ (currently in beta). On older Xcode versions, traits still work when declared in
Package.swiftbut won't appear in the GUI.
Option 3 — CocoaPods:
platform :ios, '11.0'
use_frameworks!
target 'YourApp' do
pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '9.5.1'
end
Known issue (Xcode 14+): Sandbox
rsync.sambaerror → Target Settings → "Enable User Script Sandbox" →NO.
Full config enabling the most features with sensible defaults. Add before any other code at app startup.
SwiftUI — App entry point:
import SwiftUI
import Sentry
@main
struct MyApp: App {
init() {
SentrySDK.start { options in
options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
?? "https://examplePublicKey@o0.ingest.sentry.io/0"
options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
options.releaseName = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
// Error monitoring (on by default — explicit for clarity)
options.enableCrashHandler = true
options.enableAppHangTrackingV2 = true
options.enableWatchdogTerminationTracking = true
options.attachScreenshot = true
options.attachViewHierarchy = true
options.sendDefaultPii = true
// Tracing
options.tracesSampleRate = 1.0 // lower to 0.2 in high-traffic production
// Profiling (SDK 9.0.0+ API)
options.configureProfiling = {
$0.sessionSampleRate = 1.0
$0.lifecycle = .trace
}
// Session Replay (disabled on iOS 26+ by default — safe to configure)
options.sessionReplay.sessionSampleRate = 1.0
options.sessionReplay.onErrorSampleRate = 1.0
// Logging (SDK 9.0.0+ top-level; use options.experimental.enableLogs in 8.x)
options.enableLogs = true
}
}
var body: some Scene {
WindowGroup { ContentView() }
}
}
UIKit — AppDelegate:
import UIKit
import Sentry
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
SentrySDK.start { options in
options.dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"]
?? "https://examplePublicKey@o0.ingest.sentry.io/0"
options.environment = ProcessInfo.processInfo.environment["SENTRY_ENVIRONMENT"]
options.releaseName = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
options.enableCrashHandler = true
options.enableAppHangTrackingV2 = true
options.enableWatchdogTerminationTracking = true
options.attachScreenshot = true
options.attachViewHierarchy = true
options.sendDefaultPii = true
options.tracesSampleRate = 1.0
options.configureProfiling = {
$0.sessionSampleRate = 1.0
$0.lifecycle = .trace
}
options.sessionReplay.sessionSampleRate = 1.0
options.sessionReplay.onErrorSampleRate = 1.0
// Logging (SDK 9.0.0+ top-level; use options.experimental.enableLogs in 8.x)
options.enableLogs = true
}
return true
}
}
⚠️ SDK initialization must occur on the main thread.
Walk through features one at a time. Load the reference file for each, follow its steps, and verify before moving to the next:
| Feature | Reference file | Load when... |
|---|---|---|
| Error Monitoring | ${SKILL_ROOT}/references/error-monitoring.md | Always (baseline) |
| Tracing | ${SKILL_ROOT}/references/tracing.md | App launch, network, UIViewController perf |
| Profiling | ${SKILL_ROOT}/references/profiling.md | Production perf-sensitive apps |
| Session Replay | ${SKILL_ROOT}/references/session-replay.md | User-facing iOS/tvOS apps |
| Logging | ${SKILL_ROOT}/references/logging.md |
For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.
SentryOptions Fields| Option | Type | Default | Purpose |
|---|---|---|---|
dsn | String | "" | SDK disabled if empty; reads SENTRY_DSN env var |
environment | String | "" | e.g., "production"; reads |
| Variable | Maps to | Purpose |
|---|---|---|
SENTRY_DSN | dsn | Data Source Name |
SENTRY_RELEASE | releaseName | App version (e.g., my-app@1.0.0) |
SENTRY_ENVIRONMENT | environment | Deployment environment |
| Feature | iOS | tvOS | macOS | watchOS | visionOS |
|---|---|---|---|---|---|
| Crash Reporting | ✅ | ✅ | ✅ | ✅ | ✅ |
| App Hangs V2 | ✅ | ✅ | ❌ | ❌ | ❌ |
| Watchdog Termination | ✅ | ✅ | ❌ | ❌ | ❌ |
| App Start Tracing | ✅ | ✅ | ❌ | ❌ | ✅ |
| UIViewController Tracing | ✅ | ✅ | ❌ | ❌ |
Test that Sentry is receiving events:
// Trigger a test error event:
SentrySDK.capture(message: "Sentry Cocoa SDK test")
// Or test crash reporting (without debugger — crashes are intercepted by debugger):
// SentrySDK.crash() // uncomment, run without debugger, relaunch to see crash report
Check the Sentry dashboard within a few seconds. If nothing appears:
options.debug = true — prints SDK internals to Xcode consoleLower sample rates for production to control volume and cost:
options.tracesSampleRate = 0.2 // 20% of transactions
options.configureProfiling = {
$0.sessionSampleRate = 0.1 // 10% of sessions
$0.lifecycle = .trace
}
options.sessionReplay.sessionSampleRate = 0.1 // 10% continuous
options.sessionReplay.onErrorSampleRate = 1.0 // 100% on error (keep high)
options.debug = false // never in production
After completing Apple setup, check for a companion backend missing Sentry coverage:
# Detect companion backend
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod 2>/dev/null | head -5
cat ../requirements.txt ../Pipfile 2>/dev/null | head -5
cat ../Gemfile 2>/dev/null | head -5
cat ../package.json 2>/dev/null | grep -E '"name"|"dependencies"' | head -5
If a backend is found, configure tracePropagationTargets to enable distributed tracing end-to-end, and suggest the matching skill:
| Backend detected | Suggest skill | Trace header support |
|---|---|---|
Go (go.mod) | sentry-go-sdk | ✅ automatic |
Python (requirements.txt) | sentry-python-sdk | ✅ automatic |
Ruby (Gemfile) | sentry-ruby-sdk | ✅ automatic |
Node.js backend (package.json) |
| Issue | Solution |
|---|---|
| Events not appearing | Set debug: true, verify DSN format, ensure init is on main thread |
| Crashes not captured | Run without debugger attached — debugger intercepts signals |
| App hangs not reported | Auto-disabled when debugger attached; check appHangTimeoutInterval |
| Session Replay not recording | Check iOS version — disabled by default on iOS 26+ (Liquid Glass); verify sessionSampleRate > 0 |
| Tracing data missing | Confirm tracesSampleRate > 0; check enableAutoPerformanceTracing = true |
| Profiling data missing |
Weekly Installs
164
Repository
GitHub Stars
82
First Seen
Mar 1, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex163
gemini-cli160
cursor160
github-copilot159
kimi-cli159
opencode159
Electron应用自动化指南:使用agent-browser通过CDP实现桌面应用自动化
13,200 周安装
| watchOS, app extensions, macOS CLI tools (Swift 6.1+ / Xcode 16.3+ only) |
| Structured log capture needed |
| User Feedback | ${SKILL_ROOT}/references/user-feedback.md | In-app bug reporting wanted |
SENTRY_ENVIRONMENTreleaseName | String | "" | e.g., "my-app@1.0.0"; reads SENTRY_RELEASE |
debug | Bool | false | Verbose SDK output — disable in production |
sendDefaultPii | Bool | false | Include IP, user info from active integrations |
enableCrashHandler | Bool | true | Master switch for crash reporting |
enableAppHangTrackingV2 | Bool | true (9.0+) | Differentiates fully/non-fully blocked hangs |
appHangTimeoutInterval | Double | 2.0 | Seconds before classifying as hang |
enableWatchdogTerminationTracking | Bool | true | Track watchdog kills (iOS, tvOS, Mac Catalyst) |
attachScreenshot | Bool | false | Capture screenshot on error |
attachViewHierarchy | Bool | false | Capture view hierarchy on error |
tracesSampleRate | NSNumber? | nil | Transaction sample rate (nil = tracing disabled); Swift auto-boxes Double literals (e.g. 1.0 → NSNumber) |
tracesSampler | Closure | nil | Dynamic per-transaction sampling (overrides rate) |
enableAutoPerformanceTracing | Bool | true | Master switch for auto-instrumentation |
tracePropagationTargets | [String] | [".*"] | Hosts/regex that receive distributed trace headers |
enableCaptureFailedRequests | Bool | true | Auto-capture HTTP 5xx errors as events |
enableNetworkBreadcrumbs | Bool | true | Breadcrumbs for outgoing HTTP requests |
inAppInclude | [String] | [] | Module prefixes treated as "in-app" code |
maxBreadcrumbs | Int | 100 | Max breadcrumbs per event |
sampleRate | Float | 1.0 | Error event sample rate |
beforeSend | Closure | nil | Hook to mutate/drop error events |
onCrashedLastRun | Closure | nil | Called on next launch after a crash |
| ✅ |
| SwiftUI Tracing | ✅ | ✅ | ✅ | ❌ | ✅ |
| Network Tracking | ✅ | ✅ | ✅ | ❌ | ✅ |
| Profiling | ✅ | ✅ | ✅ | ❌ | ✅ |
| Session Replay | ✅ | ❌ | ❌ | ❌ | ❌ |
| MetricKit | ✅ (15+) | ❌ | ✅ (12+) | ❌ | ❌ |
sentry-node-sdk (or sentry-express-sdk) |
| ✅ automatic |
Verify sessionSampleRate > 0 in configureProfiling; for .trace lifecycle, tracing must be enabled |
rsync.samba build error (CocoaPods) | Target Settings → "Enable User Script Sandbox" → NO |
| Multiple SPM products selected | Choose only one of Sentry, Sentry-Dynamic, SentrySwiftUI, Sentry-WithoutUIKitOrAppKit, or SentrySPM (with NoUIFramework trait on Swift 6.1+) |
inAppExclude compile error | Removed in SDK 9.0.0 — use inAppInclude only |
| Watchdog termination not tracked | Requires enableCrashHandler = true (it is by default) |
| Network breadcrumbs missing | Requires enableSwizzling = true (it is by default) |
profilesSampleRate compile error | Removed in SDK 9.0.0 — use configureProfiling closure instead |