跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 sentry-react-native-sdk

Sentry React Native Sdk

全面哨兵SDK设置,用于回放原生和博览会. 用于被请求“ 添加哨兵重播原生” 、 “ 安装 @ 哨兵/ 反播原生” 、 “ 设置在 Expo 中的哨兵”, 或配置错误监测、 跟踪、 剖析、 会话重播, 或记录原生应用程序 。 支持博览会管理,博览会裸露,和香草反应土著.

494 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

用于反应原生和博览会的全哨SDK设置

何时用

请求添加 Sentry to React Native, “安装 @ sentry/ react-native”, “设置 Sentry in Expo”, 或配置错误监测, 追踪, 剖析, 会话重播, 或登录 react Native 应用程序 。 支持管理博览会、裸博会和香草反应土著

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Sentry React Native SDK、Invoke This Skill When、Phase 1: Detect、Detect project type and existing Sentry、Distinguish Expo managed vs bare vs vanilla RN、Check Expo SDK version (important: Expo SDK 50+ required for @sentry/react-native)。

文件分析

文件分析:除 SKILL.md 外,正文引用了 scripts/xcode/with-environment.sh、scripts/sentry-xcode.sh、scripts/sentry-xcode-debug-files.sh、references/error-monitoring.md、references/tracing.md、references/profiling.md,属于带资源的技能包,这些文件按需再读。 正文约 855 行,超过规范建议的 500 行,激活时仍会整份载入。

官方 description(原文)

Full Sentry SDK setup for React Native and Expo. Use when asked to "add Sentry to React Native", "install @sentry/react-native", "setup Sentry in Expo", or configure error monitoring, tracing, profiling, session replay, or logging for React Native applications. Supports Expo managed, Expo bare, and vanilla React Native.

Sentry React Native SDKInvoke This Skill WhenPhase 1: DetectDetect project type and existing SentryDistinguish Expo managed vs bare vs vanilla RNCheck Expo SDK version (important: Expo SDK 50+ required for @sentry/react-native)Detect navigation libraryDetect state management (Redux → breadcrumb integration available)Check for existing Sentry initializationDetect Hermes (affects source map handling)Detect Expo RouterDetect backend for cross-link

· 许可:Apache-2.0

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
sentry-react-native-sdk
description
Full Sentry SDK setup for React Native and Expo. Use when asked to "add Sentry to React Native", "install @sentry/react-native", "setup Sentry in Expo", or configure error monitoring, tracing, profiling, session replay, or logging for React Native applications. Supports Expo managed, Expo bare, and vanilla React Native.
许可
Apache-2.0
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 9
  • scripts/xcode/with-environment.sh
  • scripts/sentry-xcode.sh
  • scripts/sentry-xcode-debug-files.sh
  • references/error-monitoring.md
  • references/tracing.md
  • references/profiling.md
  • references/session-replay.md
  • references/logging.md
  • references/user-feedback.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「sentry-react-native-sdk」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-19f3838cd1ebfcd5-%E5%93%A8%E5%85%B5%E9%87%8D%E7%8E%B0%E5%8E%9F%E7%94%9F-Sdk.html
请存为 .cursor/skills/sentry-react-native-sdk/SKILL.md 或 .claude/skills/sentry-react-native-sdk/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/getsentry/sentry-agent-skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/getsentry/sentry-agent-skills' --list

npx skills add 'https://github.com/getsentry/sentry-agent-skills' --skill 'sentry-react-native-sdk'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: sentry-react-native-sdk description: Full Sentry SDK setup for React Native and Expo. Use when asked to "add Sentry to React Native", "install @sentry/react-native", "setup Sentry in Expo", or configure error monitoring, tracing, profiling, session replay, or logging for React Native applications. Supports Expo managed, Expo bare, and vanilla React Native. license: Apache-2.0 --- # Sentry React Native SDK Opinionated wizard that scans your React Native or Expo project and guides you through complete Sentry setup — error monitoring, tracing, profiling, session replay, logging, and more. ## Invoke This Skill When - User asks to "add Sentry to React Native" or "set up Sentry" in an RN or Expo app - User wants error monitoring, tracing, profiling, session replay, or logging in React Native - User mentions `@sentry/react-native`, mobile error tracking, or Sentry for Expo - User wants to monitor native crashes, ANRs, or app hangs on iOS/Android > **Note:** SDK versions and APIs below reflect current Sentry docs at time of writing (`@sentry/react-native` ≥6.0.0, minimum recommended ≥8.0.0). > Always verify against [docs.sentry.io/platforms/react-native/](https://docs.sentry.io/platforms/react-native/) before implementing. --- ## Phase 1: Detect Run these commands to understand the project before making any recommendations: ```bash # Detect project type and existing Sentry cat package.json | grep -E '"(react-native|expo|@expo|@sentry/react-native|sentry-expo)"' # Distinguish Expo managed vs bare vs vanilla RN ls app.json app.config.js app.config.ts 2>/dev/null cat app.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('Expo managed' if 'expo' in d else 'Bare/Vanilla')" 2>/dev/null # Check Expo SDK version (important: Expo SDK 50+ required for @sentry/react-native) cat package.json | grep '"expo"' # Detect navigation library grep -E '"(@react-navigation/native|react-native-navigation)"' package.json # Detect state management (Redux → breadcrumb integration available) grep -E '"(redux|@reduxjs/toolkit|zustand|mobx)"' package.json # Check for existing Sentry initialization grep -r "Sentry.init" src/ app/ App.tsx App.js _layout.tsx 2>/dev/null | head -5 # Detect Hermes (affects source map handling) cat android/app/build.gradle 2>/dev/null | grep -i hermes cat ios/Podfile 2>/dev/null | grep -i hermes # Detect Expo Router ls app/_layout.tsx app/_layout.js 2>/dev/null # Detect backend for cross-link ls backend/ server/ api/ 2>/dev/null find . -maxdepth 3 \( -name "go.mod" -o -name "requirements.txt" -o -name "Gemfile" -o -name "package.json" \) 2>/dev/null | grep -v node_modules | head -10 ``` **What to determine:** | Question | Impact | |----------|--------| | `expo` in `package.json`? | Expo path (config plugin + `getSentryExpoConfig`) vs bare/vanilla RN path | | Expo SDK ≥50? | `@sentry/react-native` directly; older = `sentry-expo` (legacy, do not use) | | `app.json` has `"expo"` key? | Managed Expo — wizard is simplest; config plugin handles all native config | | `app/_layout.tsx` present? | Expo Router project — init goes in `_layout.tsx` | | `@sentry/react-native` already in `package.json`? | Skip install, jump to feature config | | `@react-navigation/native` present? | Recommend `reactNavigationIntegration` for screen tracking | | `react-native-navigation` present? | Recommend `reactNativeNavigationIntegration` (Wix) | | Backend directory detected? | Trigger Phase 4 cross-link | --- ## Phase 2: Recommend Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal: **Recommended (core coverage — always set up these):** - ✅ **Error Monitoring** — captures JS exceptions, native crashes (iOS + Android), ANRs, and app hangs - ✅ **Tracing** — mobile performance is critical; auto-instruments navigation, app start, network requests - ✅ **Session Replay** — mobile replay captures screenshots and touch events for debugging user issues **Optional (enhanced observability):** - ⚡ **Profiling** — CPU profiling on iOS (JS profiling cross-platform); low overhead in production - ⚡ **Logging** — structured logs via `Sentry.logger.*`; links to traces for full context - ⚡ **User Feedback** — collect user-submitted bug reports directly from your app **Recommendation logic:** | Feature | Recommend when... | |---------|------------------| | Error Monitoring | **Always** — non-negotiable baseline for any mobile app | | Tracing | **Always for mobile** — app start, navigation, and network latency matter | | Session Replay | User-facing production app; debug user-reported issues visually | | Profiling | Performance-sensitive screens, startup time concerns, or production perf investigations | | Logging | App uses structured logging, or you want log-to-trace correlation in Sentry | | User Feedback | Beta or customer-facing app where you want user-submitted bug reports | Propose: *"For your [Expo managed / bare RN] app, I recommend setting up Error Monitoring + Tracing + Session Replay. Want me to also add Profiling and Logging?"* --- ## Phase 3: Guide ### Determine Your Setup Path | Project type | Recommended setup | Complexity | |-------------|------------------|------------| | Expo managed (SDK 50+) | Wizard CLI or manual with config plugin | Low — wizard does everything | | Expo bare (SDK 50+) | Wizard CLI recommended | Medium — handles iOS/Android config | | Vanilla React Native (0.69+) | Wizard CLI recommended | Medium — handles Xcode + Gradle | | Expo SDK <50 | Use `sentry-expo` (legacy) | See [legacy docs](https://docs.sentry.io/platforms/react-native/manual-setup/expo/) | --- ### Path A: Wizard CLI (Recommended for all project types) Run the wizard — it walks you through login, org/project selection, and auth token setup interactively. It then handles installation, native config, source map upload, and initial `Sentry.init()`: ```bash npx @sentry/wizard@latest -i reactNative ``` **What the wizard creates/modifies:** | File | Action | Purpose | |------|--------|---------| | `package.json` | Installs `@sentry/react-native` | Core SDK | | `metro.config.js` | Adds `@sentry/react-native/metro` serializer | Source map generation | | `app.json` | Adds `@sentry/react-native/expo` plugin (Expo only) | Config plugin for native builds | | `App.tsx` / `_layout.tsx` | Adds `Sentry.init()` and `Sentry.wrap()` | SDK initialization | | `ios/sentry.properties` | Stores org/project/token | iOS source map + dSYM upload | | `android/sentry.properties` | Stores org/project/token | Android source map upload | | `android/app/build.gradle` | Adds Sentry Gradle plugin | Android source maps + proguard | | `ios/[AppName].xcodeproj` | Wraps "Bundle RN" build phase + adds dSYM upload | iOS symbol upload | | `.env.local` | `SENTRY_AUTH_TOKEN` | Auth token (add to `.gitignore`) | After the wizard runs, skip to [Verification](#verification). --- ### Path B: Manual — Expo Managed (SDK 50+) **Step 1 — Install** ```bash npx expo install @sentry/react-native ``` **Step 2 — `metro.config.js`** ```javascript const { getSentryExpoConfig } = require("@sentry/react-native/metro"); const config = getSentryExpoConfig(__dirname); module.exports = config; ``` If `metro.config.js` doesn't exist yet: ```bash npx expo customize metro.config.js # Then replace contents with the above ``` **Step 3 — `app.json` — Add Expo config plugin** ```json { "expo": { "plugins": [ [ "@sentry/react-native/expo", { "url": "https://sentry.io/", "project": "YOUR_PROJECT_SLUG", "organization": "YOUR_ORG_SLUG" } ] ] } } ``` > **Note:** Set `SENTRY_AUTH_TOKEN` as an environment variable for native builds — never commit it to version control. **Step 4 — Initialize Sentry** For **Expo Router** (`app/_layout.tsx`): ```typescript import { Stack, useNavigationContainerRef } from "expo-router"; import { isRunningInExpoGo } from "expo"; import * as Sentry from "@sentry/react-native"; import React from "react"; const navigationIntegration = Sentry.reactNavigationIntegration({ enableTimeToInitialDisplay: !isRunningInExpoGo(), // disabled in Expo Go }); Sentry.init({ dsn: process.env.EXPO_PUBLIC_SENTRY_DSN ?? "YOUR_SENTRY_DSN", sendDefaultPii: true, // Tracing tracesSampleRate: 1.0, // lower to 0.1–0.2 in production // Profiling profilesSampleRate: 1.0, // Session Replay replaysOnErrorSampleRate: 1.0, replaysSessionSampleRate: 0.1, // Logging (SDK ≥7.0.0) enableLogs: true, // Navigation integrations: [ navigationIntegration, Sentry.mobileReplayIntegration(), ], enableNativeFramesTracking: !isRunningInExpoGo(), // slow/frozen frames environment: __DEV__ ? "development" : "production", }); function RootLayout() { const ref = useNavigationContainerRef(); React.useEffect(() => { if (ref) { navigationIntegration.registerNavigationContainer(ref); } }, [ref]); return ; } export default Sentry.wrap(RootLayout); ``` For **standard Expo** (`App.tsx`): ```typescript import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native"; import { isRunningInExpoGo } from "expo"; import * as Sentry from "@sentry/react-native"; const navigationIntegration = Sentry.reactNavigationIntegration({ enableTimeToInitialDisplay: !isRunningInExpoGo(), }); Sentry.init({ dsn: process.env.EXPO_PUBLIC_SENTRY_DSN ?? "YOUR_SENTRY_DSN", sendDefaultPii: true, tracesSampleRate: 1.0, profilesSampleRate: 1.0, replaysOnErrorSampleRate: 1.0, replaysSessionSampleRate: 0.1, enableLogs: true, integrations: [ navigationIntegration, Sentry.mobileReplayIntegration(), ], enableNativeFramesTracking: !isRunningInExpoGo(), environment: __DEV__ ? "development" : "production", }); const navigationRef = createNavigationContainerRef(); function App() { return ( { navigationIntegration.registerNavigationContainer(navigationRef); }} > {/* your navigation here */} ); } export default Sentry.wrap(App); ``` --- ### Path C: Manual — Bare React Native (0.69+) **Step 1 — Install** ```bash npm install @sentry/react-native --save cd ios && pod install ``` **Step 2 — `metro.config.js`** ```javascript const { getDefaultConfig } = require("@react-native/metro-config"); const { withSentryConfig } = require("@sentry/react-native/metro"); const config = getDefaultConfig(__dirname); module.exports = withSentryConfig(config); ``` **Step 3 — iOS: Modify Xcode build phase** Open `ios/[AppName].xcodeproj` in Xcode. Find the **"Bundle React Native code and images"** build phase and replace the script content with: ```bash # RN 0.81.1+ set -e WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh" SENTRY_XCODE="../node_modules/@sentry/react-native/scripts/sentry-xcode.sh" /bin/sh -c "$WITH_ENVIRONMENT $SENTRY_XCODE" ``` **Step 4 — iOS: Add "Upload Debug Symbols to Sentry" build phase** Add a new **Run Script** build phase in Xcode (after the bundle phase): ```bash /bin/sh ../node_modules/@sentry/react-native/scripts/sentry-xcode-debug-files.sh ``` **Step 5 — iOS: `ios/sentry.properties`** ```properties defaults.url=https://sentry.io/ defaults.org=YOUR_ORG_SLUG defaults.project=YOUR_PROJECT_SLUG auth.token=YOUR_ORG_AUTH_TOKEN ``` **Step 6 — Android: `android/app/build.gradle`** Add before the `android {}` block: ```groovy apply from: "../../node_modules/@sentry/react-native/sentry.gradle" ``` **Step 7 — Android: `android/sentry.properties`** ```properties defaults.url=https://sentry.io/ defaults.org=YOUR_ORG_SLUG defaults.project=YOUR_PROJECT_SLUG auth.token=YOUR_ORG_AUTH_TOKEN ``` **Step 8 — Initialize Sentry (`App.tsx` or entry point)** ```typescript import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native"; import * as Sentry from "@sentry/react-native"; const navigationIntegration = Sentry.reactNavigationIntegration({ enableTimeToInitialDisplay: true, }); Sentry.init({ dsn: "YOUR_SENTRY_DSN", sendDefaultPii: true, tracesSampleRate: 1.0, profilesSampleRate: 1.0, replaysOnErrorSampleRate: 1.0, replaysSessionSampleRate: 0.1, enableLogs: true, integrations: [ navigationIntegration, Sentry.mobileReplayIntegration(), ], enableNativeFramesTracking: true, environment: __DEV__ ? "development" : "production", }); const navigationRef = createNavigationContainerRef(); function App() { return ( { navigationIntegration.registerNavigationContainer(navigationRef); }} > {/* your navigation here */} ); } export default Sentry.wrap(App); ``` --- ### Quick Reference: Full-Featured `Sentry.init()` This is the recommended starting configuration with all features enabled: ```typescript import * as Sentry from "@sentry/react-native"; Sentry.init({ dsn: "YOUR_SENTRY_DSN", sendDefaultPii: true, // Tracing — lower to 0.1–0.2 in high-traffic production tracesSampleRate: 1.0, // Profiling — runs on a subset of traced transactions profilesSampleRate: 1.0, // Session Replay — always capture on error, sample 10% of all sessions replaysOnErrorSampleRate: 1.0, replaysSessionSampleRate: 0.1, // Logging — enable Sentry.logger.* API enableLogs: true, // Integrations — mobile replay is opt-in integrations: [ Sentry.mobileReplayIntegration({ maskAllText: true, // masks text by default for privacy maskAllImages: true, }), ], // Native frames tracking (disable in Expo Go) enableNativeFramesTracking: true, // Environment environment: __DEV__ ? "development" : "production", // Release — set from CI or build system // release: "[email protected]+1", // dist: "1", }); // REQUIRED: Wrap root component to capture React render errors export default Sentry.wrap(App); ``` --- ### Navigation Setup — React Navigation (v5+) ```typescript import { reactNavigationIntegration } from "@sentry/react-native"; import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native"; const navigationIntegration = reactNavigationIntegration({ enableTimeToInitialDisplay: true, // track TTID per screen routeChangeTimeoutMs: 1_000, // max wait for route change to settle ignoreEmptyBackNavigationTransactions: true, }); // Add to Sentry.init integrations array Sentry.init({ integrations: [navigationIntegration], // ... }); // In your component: const navigationRef = createNavigationContainerRef(); { navigationIntegration.registerNavigationContainer(navigationRef); }} > ``` ### Navigation Setup — Wix React Native Navigation ```typescript import * as Sentry from "@sentry/react-native"; import { Navigation } from "react-native-navigation"; Sentry.init({ integrations: [Sentry.reactNativeNavigationIntegration({ navigation: Navigation })], // ... }); ``` --- ### Wrap Your Root Component Always wrap your root component — this enables React error boundaries and ensures crashes at the component tree level are captured: ```typescript export default Sentry.wrap(App); ``` --- ### For Each Agreed Feature Walk through features one at a time. Load the reference file for each, follow its steps, then verify before moving on: | Feature | Reference | Load when... | |---------|-----------|-------------| | Error Monitoring | `${SKILL_ROOT}/references/error-monitoring.md` | Always (baseline) | | Tracing & Performance | `${SKILL_ROOT}/references/tracing.md` | Always for mobile (app start, navigation, network) | | Profiling | `${SKILL_ROOT}/references/profiling.md` | Performance-sensitive production apps | | Session Replay | `${SKILL_ROOT}/references/session-replay.md` | User-facing apps | | Logging | `${SKILL_ROOT}/references/logging.md` | Structured logging / log-to-trace correlation | | User Feedback | `${SKILL_ROOT}/references/user-feedback.md` | Collecting user-submitted reports | For each feature: `Read ${SKILL_ROOT}/references/.md`, follow steps exactly, verify it works. --- ## Configuration Reference ### Core `Sentry.init()` Options | Option | Type | Default | Purpose | |--------|------|---------|---------| | `dsn` | `string` | — | **Required.** Project DSN; SDK disabled if empty. Env: `SENTRY_DSN` | | `environment` | `string` | — | e.g., `"production"`, `"staging"`. Env: `SENTRY_ENVIRONMENT` | | `release` | `string` | — | App version, e.g., `"[email protected]+42"`. Env: `SENTRY_RELEASE` | | `dist` | `string` | — | Build number / variant identifier (max 64 chars) | | `sendDefaultPii` | `boolean` | `false` | Include PII: IP address, cookies, user data | | `sampleRate` | `number` | `1.0` | Error event sampling (0.0–1.0) | | `maxBreadcrumbs` | `number` | `100` | Max breadcrumbs per event | | `attachStacktrace` | `boolean` | `true` | Auto-attach stack traces to messages | | `attachScreenshot` | `boolean` | `false` | Capture screenshot on error (SDK ≥4.11.0) | | `attachViewHierarchy` | `boolean` | `false` | Attach JSON view hierarchy as attachment | | `debug` | `boolean` | `false` | Verbose SDK output. **Never use in production** | | `enabled` | `boolean` | `true` | Disable SDK entirely (e.g., for testing) | | `ignoreErrors` | `string[] \| RegExp[]` | — | Drop errors matching these patterns | | `ignoreTransactions` | `string[] \| RegExp[]` | — | Drop transactions matching these patterns | | `maxCacheItems` | `number` | `30` | Max offline-cached envelopes | | `defaultIntegrations` | `boolean` | `true` | Set `false` to disable all default integrations | | `integrations` | `array \| function` | — | Add or filter integrations | ### Tracing Options | Option | Type | Default | Purpose | |--------|------|---------|---------| | `tracesSampleRate` | `number` | `0` | Transaction sample rate (0–1). Use `1.0` in dev | | `tracesSampler` | `function` | — | Per-transaction sampling; overrides `tracesSampleRate` | | `tracePropagationTargets` | `(string \| RegExp)[]` | `[/.*/]` | Which API URLs receive distributed tracing headers | | `profilesSampleRate` | `number` | `0` | Profiling sample rate (applied to traced transactions) | ### Native / Mobile Options | Option | Type | Default | Purpose | |--------|------|---------|---------| | `enableNative` | `boolean` | `true` | Set `false` for JS-only (no native SDK) | | `enableNativeCrashHandling` | `boolean` | `true` | Capture native hard crashes (iOS/Android) | | `enableNativeFramesTracking` | `boolean` | — | Slow/frozen frames tracking. **Disable in Expo Go** | | `enableWatchdogTerminationTracking` | `boolean` | `true` | OOM kill detection (iOS) | | `enableAppHangTracking` | `boolean` | `true` | App hang detection (iOS, tvOS, macOS) | | `appHangTimeoutInterval` | `number` | `2` | Seconds before classifying as app hang (iOS) | | `enableAutoPerformanceTracing` | `boolean` | `true` | Auto performance instrumentation | | `enableNdkScopeSync` | `boolean` | `true` | Java→NDK scope sync (Android) | | `attachThreads` | `boolean` | `false` | Auto-attach all threads on crash (Android) | | `autoInitializeNativeSdk` | `boolean` | `true` | Set `false` for manual native init | | `onReady` | `function` | — | Callback after native SDKs initialize | ### Session & Release Health Options | Option | Type | Default | Purpose | |--------|------|---------|---------| | `autoSessionTracking` | `boolean` | `true` | Session tracking (crash-free users/sessions) | | `sessionTrackingIntervalMillis` | `number` | `30000` | ms of background before session ends | ### Replay Options | Option | Type | Default | Purpose | |--------|------|---------|---------| | `replaysSessionSampleRate` | `number` | `0` | Fraction of all sessions recorded | | `replaysOnErrorSampleRate` | `number` | `0` | Fraction of error sessions recorded | ### Logging Options (SDK ≥7.0.0) | Option | Type | Purpose | |--------|------|---------| | `enableLogs` | `boolean` | Enable `Sentry.logger.*` API | | `beforeSendLog` | `function` | Filter/modify logs before sending | | `logsOrigin` | `'native' \| 'js' \| 'all'` | Filter log source (SDK ≥7.7.0) | ### Hook Options | Option | Type | Purpose | |--------|------|---------| | `beforeSend` | `(event, hint) => event \| null` | Modify/drop JS error events. ⚠️ Does NOT apply to native crashes | | `beforeSendTransaction` | `(event) => event \| null` | Modify/drop transaction events | | `beforeBreadcrumb` | `(breadcrumb, hint) => breadcrumb \| null` | Process breadcrumbs before storage | --- ## Environment Variables | Variable | Purpose | Notes | |----------|---------|-------| | `SENTRY_DSN` | Data Source Name | Falls back from `dsn` option | | `SENTRY_AUTH_TOKEN` | Upload source maps and dSYMs | **Never commit — use CI secrets** | | `SENTRY_ORG` | Organization slug | Used by wizard and build plugins | | `SENTRY_PROJECT` | Project slug | Used by wizard and build plugins | | `SENTRY_RELEASE` | Release identifier | Falls back from `release` option | | `SENTRY_ENVIRONMENT` | Environment name | Falls back from `environment` option | | `SENTRY_DISABLE_AUTO_UPLOAD` | Skip source map upload | Set `true` during local builds | | `EXPO_PUBLIC_SENTRY_DSN` | Expo public env var for DSN | Safe to embed in client bundle | --- ## Source Maps & Debug Symbols Source maps and debug symbols are what transform minified stack traces into readable ones. When set up correctly, Sentry shows you the exact line of your source code that threw. ### How Uploads Work | Platform | What's uploaded | When | |----------|----------------|------| | **iOS** (JS) | Source maps (`.map` files) | During Xcode build | | **iOS** (Native) | dSYM bundles | During Xcode archive / Xcode Cloud | | **Android** (JS) | Source maps + Hermes `.hbc.map` | During Gradle build | | **Android** (Native) | Proguard mapping + NDK `.so` files | During Gradle build | ### Expo: Automatic Upload The `@sentry/react-native/expo` config plugin automatically sets up upload hooks for native builds. Source maps are uploaded during `eas build` and `expo run:ios/android` (release). ```bash SENTRY_AUTH_TOKEN=sntrys_... npx expo run:ios --configuration Release ``` ### Manual Upload (bare RN) If you need to manually upload source maps: ```bash npx sentry-cli sourcemaps upload \ --org YOUR_ORG \ --project YOUR_PROJECT \ --release "[email protected]+1" \ ./dist ``` --- ## Default Integrations (Auto-Enabled) These integrations are enabled automatically — no config needed: | Integration | What it does | |-------------|-------------| | `ReactNativeErrorHandlers` | Catches unhandled JS exceptions and promise rejections | | `Release` | Attaches release/dist to all events | | `Breadcrumbs` | Records console logs, HTTP requests, user gestures as breadcrumbs | | `HttpClient` | Adds HTTP request/response breadcrumbs | | `DeviceContext` | Attaches device/OS/battery info to events | | `AppContext` | Attaches app version, bundle ID, and memory info | | `CultureContext` | Attaches locale and timezone | | `Screenshot` | Captures screenshot on error (when `attachScreenshot: true`) | | `ViewHierarchy` | Attaches view hierarchy (when `attachViewHierarchy: true`) | | `NativeLinkedErrors` | Links JS errors to their native crash counterparts | ### Opt-In Integrations | Integration | How to enable | |-------------|--------------| | `mobileReplayIntegration()` | Add to `integrations` array | | `reactNavigationIntegration()` | Add to `integrations` array | | `reactNativeNavigationIntegration()` | Add to `integrations` array (Wix only) | | `feedbackIntegration()` | Add to `integrations` array (user feedback widget) | --- ## Expo Config Plugin Reference Configure the plugin in `app.json` or `app.config.js`: ```json { "expo": { "plugins": [ [ "@sentry/react-native/expo", { "url": "https://sentry.io/", "project": "my-project", "organization": "my-org", "note": "Set SENTRY_AUTH_TOKEN env var for native builds" } ] ] } } ``` Or in `app.config.js` (allows env var interpolation): ```javascript export default { expo: { plugins: [ [ "@sentry/react-native/expo", { url: "https://sentry.io/", project: process.env.SENTRY_PROJECT, organization: process.env.SENTRY_ORG, }, ], ], }, }; ``` --- ## Production Settings Lower sample rates and harden config before shipping to production: ```typescript Sentry.init({ dsn: process.env.EXPO_PUBLIC_SENTRY_DSN, environment: __DEV__ ? "development" : "production", // Trace 10–20% of transactions in high-traffic production tracesSampleRate: __DEV__ ? 1.0 : 0.1, // Profile 100% of traced transactions (profiling is always a subset of tracing) profilesSampleRate: 1.0, // Replay all error sessions, sample 5% of normal sessions replaysOnErrorSampleRate: 1.0, replaysSessionSampleRate: __DEV__ ? 1.0 : 0.05, // Set release and dist for accurate source map lookup release: "my-app@" + Application.nativeApplicationVersion, dist: String(Application.nativeBuildVersion), // Disable debug logging in production debug: __DEV__, }); ``` --- ## Verification After setup, test that Sentry is receiving events: ```typescript // Quick test — throws and Sentry.wrap(App) catches it { throw new Error("My first Sentry error!"); }} /> // Or capture manually { Sentry.captureMessage("Sentry test message", "info"); }} /> ``` **Check the Sentry dashboard:** - **Issues** → your test error should appear within seconds - **Traces** → look for a "main" transaction with child spans - **Replays** → session recording visible after app interaction (native build only — not Expo Go) - **Logs** → structured log entries if `enableLogs: true` > ⚠️ **Expo Go limitation:** Native crashes, session replay, slow/frozen frames, TTID, and TTFD only work in native builds (`eas build` or `expo run`). Expo Go runs in a JS-only mode. Set `enableNativeFramesTracking: !isRunningInExpoGo()` to avoid warnings. If nothing appears: 1. Set `debug: true` — SDK logs to Metro console 2. Verify DSN is correct and the Sentry project exists 3. Ensure `Sentry.wrap(App)` is applied to the root component 4. For native crashes, build a release build (crashes in debug mode may not forward) --- ## Phase 4: Cross-Link After completing React Native setup, check for a backend or web frontend missing Sentry coverage: ```bash # Adjacent backend directories ls ../backend ../server ../api 2>/dev/null cat ../go.mod 2>/dev/null | head -3 cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3 cat ../Gemfile 2>/dev/null | head -3 ls ../backend/package.json ../server/package.json 2>/dev/null # Web frontend in same or sibling repo ls ../web ../frontend ../dashboard 2>/dev/null cat ../web/package.json ../frontend/package.json 2>/dev/null | grep -E '"react"|"svelte"|"next"' # Check for OpenTelemetry (for distributed tracing interop) grep -r "opentelemetry" ../backend/go.mod ../server/requirements.txt 2>/dev/null ``` If a backend or web frontend exists without Sentry, suggest the matching skill: | Detected | Suggest skill | |----------|--------------| | Go backend (`go.mod`) | `sentry-go-sdk` | | Python backend (`requirements.txt`, `pyproject.toml`) | `sentry-python-sdk` | | Ruby backend (`Gemfile`) | `sentry-ruby-sdk` | | Node.js backend (Express, Fastify, etc.) | `@sentry/node` — see [docs.sentry.io/platforms/javascript/guides/express/](https://docs.sentry.io/platforms/javascript/guides/express/) | | React / Next.js web | `sentry-react-sdk` | | Svelte / SvelteKit web | `sentry-svelte-sdk` | **Distributed tracing setup** — if the backend skill is added, configure `tracePropagationTargets` in React Native to propagate trace context to your API: ```typescript Sentry.init({ tracePropagationTargets: [ "localhost", /^https:\/\/api\.yourapp\.com/, ], // ... }); ``` This links mobile transactions to backend traces in the Sentry waterfall view. --- ## Troubleshooting | Issue | Solution | |-------|----------| | Events not appearing in Sentry | Set `debug: true`, check Metro/Xcode console for SDK errors; verify DSN is correct | | `pod install` fails | Run `cd ios && pod install --repo-update`; check CocoaPods version | | iOS build fails with Sentry script | Verify the "Bundle React Native code and images" script was replaced (not appended to) | | Android build fails after adding `sentry.gradle` | Ensure `apply from` line is before the `android {}` block in `build.gradle` | | Android Gradle 8+ compatibility issue | Use `sentry-android-gradle-plugin` ≥4.0.0; check `sentry.gradle` version in your SDK | | Source maps not uploading | Verify `sentry.properties` has a valid `auth.token`; check build logs for `sentry-cli` output | | Source maps not resolving in Sentry | Confirm `release` and `dist` in `Sentry.init()` match the uploaded bundle metadata | | Hermes source maps not working | Hermes emits `.hbc.map` — the Gradle plugin handles this automatically; verify `sentry.gradle` is applied | | Session replay not recording | Must use a native build (not Expo Go); confirm `mobileReplayIntegration()` is in `integrations` | | Replay shows blank/black screens | Check that `maskAllText`/`maskAllImages` settings match your privacy requirements | | Slow/frozen frames not tracked | Set `enableNativeFramesTracking: true` and confirm you're on a native build (not Expo Go) | | TTID / TTFD not appearing | Requires `enableTimeToInitialDisplay: true` in `reactNavigationIntegration()` on a native build | | App crashes on startup after adding Sentry | Likely a native initialization error — check Xcode/Logcat logs; try `enableNative: false` to isolate | | Expo SDK 49 or older | Use `sentry-expo` (legacy package); `@sentry/react-native` requires Expo SDK 50+ | | `isRunningInExpoGo` import error | Import from `expo` package: `import { isRunningInExpoGo } from "expo"` | | Node not found during Xcode build | Add `export NODE_BINARY=$(which node)` to the Xcode build phase, or symlink: `ln -s $(which node) /usr/local/bin/node` | | Expo Go warning about native features | Use `isRunningInExpoGo()` guard: `enableNativeFramesTracking: !isRunningInExpoGo()` | | `beforeSend` not firing for native crashes | Expected — `beforeSend` only intercepts JS-layer errors; native crashes bypass it | | Android 15+ (16KB page size) crash | Upgrade to `@sentry/react-native` ≥6.3.0 | | Too many transactions in dashboard | Lower `tracesSampleRate` to `0.1` or use `tracesSampler` to drop health checks | | `SENTRY_AUTH_TOKEN` exposed in app bundle | `SENTRY_AUTH_TOKEN` is for build-time upload only — never pass it to `Sentry.init()` | | EAS Build: Sentry auth token missing | Set `SENTRY_AUTH_TOKEN` as an EAS secret: `eas secret:create --name SENTRY_AUTH_TOKEN` |

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…