sentry-cocoa-sdk

Q: How do I install sentry-cocoa-sdk?

Run npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-cocoa-sdk in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sentry-cocoa-sdk/ (personal) or .claude/skills/sentry-cocoa-sdk/ (project).

by getsentry OfficialDevOps & Cloud

Full Sentry SDK setup for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS). Use when asked to "add Sentry to iOS", "add Sentry to Swift", "install sentry-cocoa", or configure error monitoring, tracing, profiling, session replay, or logging for Apple applications. Supports SwiftUI and UIKit.

Installs: 329
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-cocoa-sdk

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads sentry-cocoa-sdk automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Sentry Cocoa SDK

Opinionated wizard that scans your Apple project and guides you through complete Sentry setup.

Invoke This Skill When

User asks to "add Sentry to iOS/macOS/tvOS" or "set up Sentry" in an Apple app
User wants error monitoring, tracing, profiling, session replay, or logging in Swift/ObjC
User mentions sentry-cocoa, SentrySDK, or the Apple/iOS Sentry SDK
User wants to monitor crashes, app hangs, watchdog terminations, or performance

Note: 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.

Phase 1: Detect

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:

Is sentry-cocoa already in Package.swift or Podfile? If yes, skip to Phase 2 (configure features).
SwiftUI (@main App struct) or UIKit (AppDelegate)? Determines init pattern.
Which Apple platforms? (Affects which features are available — see Platform Support Matrix.)
Existing logging library? (Enables structured log capture.)
Companion backend? (Triggers Phase 4 cross-link for distributed tracing.)

Phase 2: Recommend

Based on what you found, present a concrete recommendation. Don't ask open-ended questions — lead with a proposal:

Recommended (core coverage):

✅ Error Monitoring — always; crash reporting, app hangs, watchdog terminations, NSError/Swift errors
✅ Tracing — always for apps; auto-instruments app launch, network, UIViewController, file I/O, Core Data
✅ Profiling — production apps; continuous profiling with minimal overhead

Optional (enhanced observability):

⚡ Session Replay — user-facing apps; ⚠️ disabled by default on iOS 26+ (Liquid Glass rendering)
⚡ Logging — when structured log capture is needed
⚡ User Feedback — apps that want crash/error feedback forms from users

Not available for Cocoa:

❌ Metrics — use custom spans instead
❌ Crons — backend only
❌ AI Monitoring — JS/Python only

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?"

Phase 3: Guide

Install

Option 1 — Sentry Wizard (recommended): Walks you through login, org/project selection, and auth token setup interactively. Then installs the SDK, updates AppDelegate, adds dSYM/debug symbol upload build phases, and configures everything automatically.

brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios

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

⚠️ Xcode allows selecting multiple products — choose only one.

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.samba error → Target Settings → "Enable User Script Sandbox" → NO.

Quick Start — Recommended Init

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.

For Each Agreed Feature

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`	Structured log capture needed
User Feedback	`${SKILL_ROOT}/references/user-feedback.md`	In-app bug reporting wanted

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

Configuration Reference

Key `SentryOptions` Fields

Option	Type	Default	Purpose
`dsn`	`String`	`""`	SDK disabled if empty; reads `SENTRY_DSN` env var
`environment`	`String`	`""`	e.g., `"production"`; reads `SENTRY_ENVIRONMENT`
`releaseName`	`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

Environment Variables

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

Platform Feature Support Matrix

Feature	iOS	tvOS	macOS	watchOS	visionOS
Crash Reporting	✅	✅	✅	✅	✅
App Hangs V2	✅	✅	❌	❌	❌
Watchdog Termination	✅	✅	❌	❌	❌
App Start Tracing	✅	✅	❌	❌	✅
UIViewController Tracing	✅	✅	❌	❌	✅
SwiftUI Tracing	✅	✅	✅	❌	✅
Network Tracking	✅	✅	✅	❌	✅
Profiling	✅	✅	✅	❌	✅
Session Replay	✅	❌	❌	❌	❌
MetricKit	✅ (15+)	❌	✅ (12+)	❌	❌

Verification

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:

Set options.debug = true — prints SDK internals to Xcode console
Verify the DSN is correct and the project exists
Ensure initialization is on the main thread

Production Settings

Lower 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

Phase 4: Cross-Link

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`)	`sentry-node-sdk` (or `sentry-express-sdk`)	✅ automatic

Troubleshooting

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	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`
`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

FAQ

What does the sentry-cocoa-sdk skill do?

How do I install sentry-cocoa-sdk?

Run npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-cocoa-sdk in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sentry-cocoa-sdk/ (personal) or .claude/skills/sentry-cocoa-sdk/ (project).

Which AI agents can use sentry-cocoa-sdk?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is sentry-cocoa-sdk safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains sentry-cocoa-sdk?

It is published by getsentry in getsentry/sentry-agent-skills, and it is an official skill from the maker of the technology it covers. It has 329 recorded installs.

More from getsentry/sentry-agent-skills

View all →

sentry-fix-issues

getsentry/sentry-agent-skills

Find and fix issues from Sentry using MCP. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in Sentry. Methodically analyzes stack traces, breadcrumbs, traces, and context to identify root causes.

OfficialDevOps & Cloud2.6K installs

sentry-react-setup

getsentry/sentry-agent-skills

Setup Sentry in React apps. Use when asked to add Sentry to React, install @sentry/react, or configure error monitoring, error boundaries, session replay, or browser tracing for React applications.

OfficialDevOps & Cloud1.1K installs

sentry-setup-ai-monitoring

getsentry/sentry-agent-skills

Setup Sentry AI Agent Monitoring in any project. Use when asked to monitor LLM calls, track AI agents, or instrument OpenAI/Anthropic/Vercel AI/LangChain/Google GenAI/Pydantic AI. Detects installed AI SDKs and configures appropriate integrations.

OfficialDevOps & Cloud894 installs

sentry-nextjs-sdk

getsentry/sentry-agent-skills

Full Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay, logging, profiling, AI monitoring, or crons for Next.js applications. Supports Next.js 13+ with App Router and Pages Router.

OfficialDevOps & Cloud653 installs

sentry-pr-code-review

getsentry/sentry-agent-skills

Review a project's PRs to check for issues detected in code review by Seer Bug Prediction. Use when asked to review or fix issues identified by Sentry in PR comments, or to find recent PRs with Sentry feedback.

OfficialCode Quality & Workflow632 installs

sentry-create-alert

getsentry/sentry-agent-skills

Create Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow automations. Supports email, Slack, PagerDuty, Discord, and other notification actions.

OfficialDevOps & Cloud592 installs

Popular devops & cloud skills

View category →

microsoft-foundry

microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure

OfficialDevOps & Cloud579.1K installs

azure-diagnostics

microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.

OfficialDevOps & Cloud569.8K installs

azure-prepare

microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.

OfficialDevOps & Cloud569K installs

azure-ai

microsoft/azure-skills

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

OfficialDevOps & Cloud568.8K installs

azure-deploy

microsoft/azure-skills

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.

OfficialDevOps & Cloud568.6K installs

azure-validate

microsoft/azure-skills

Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.

OfficialDevOps & Cloud568K installs

sentry-cocoa-sdk

Install

Install

Describe the task

Review the result

SKILL.md

Sentry Cocoa SDK

Invoke This Skill When

Phase 1: Detect

Phase 2: Recommend

Phase 3: Guide

Install

Quick Start — Recommended Init

For Each Agreed Feature

Configuration Reference

Key SentryOptions Fields

Environment Variables

Platform Feature Support Matrix

Verification

Production Settings

Phase 4: Cross-Link

Troubleshooting

FAQ

More from getsentry/sentry-agent-skills

Popular devops & cloud skills

Key `SentryOptions` Fields