From ef57592f08263023198ddb43a851df02adecd544 Mon Sep 17 00:00:00 2001 From: Evan Purkhiser Date: Mon, 13 Jul 2026 15:51:57 -0400 Subject: [PATCH] ref(skills): remove sentry-sdk-upgrade and dissolve the workflow router Major-version SDK upgrades are a rare, low-frequency task and don't fit the task-shaped skill set the getting-started redesign is converging on. Removing sentry-sdk-upgrade empties the sentry-workflow router (its only remaining child after the code-review skills were removed in #283), so drop the router too. Delete both skills, the README/AGENTS listings, and the workflow entries in the AGENTS skill-tree navigation, then regenerate SKILL_TREE.md. sentry-feature-setup is now the last router as the library migrates toward flat standalone skills. --- AGENTS.md | 5 +- README.md | 8 +- src/SKILL_TREE.md | 1 - src/skills/sentry-sdk-upgrade/SKILL.md | 238 --------------- .../references/upgrade-patterns.md | 176 ----------- .../sentry-sdk-upgrade/references/v7-to-v8.md | 251 ---------------- .../sentry-sdk-upgrade/references/v8-to-v9.md | 277 ------------------ .../references/v9-to-v10.md | 40 --- src/skills/sentry-workflow/SKILL.md | 32 -- 9 files changed, 2 insertions(+), 1026 deletions(-) delete mode 100644 src/skills/sentry-sdk-upgrade/SKILL.md delete mode 100644 src/skills/sentry-sdk-upgrade/references/upgrade-patterns.md delete mode 100644 src/skills/sentry-sdk-upgrade/references/v7-to-v8.md delete mode 100644 src/skills/sentry-sdk-upgrade/references/v8-to-v9.md delete mode 100644 src/skills/sentry-sdk-upgrade/references/v9-to-v10.md delete mode 100644 src/skills/sentry-workflow/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 5b381edc..a860c74f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,7 +67,6 @@ Skills use YAML frontmatter with `allowed-tools` — this is required by Cursor | Skill | Description | |-------|-------------| | `sentry-fix-issues` | Find and fix Sentry issues using MCP | -| `sentry-sdk-upgrade` | Upgrade the Sentry JavaScript SDK across major versions | | `sentry-create-alert` | Create Sentry alerts using the workflow engine API | ### Authoring Skills @@ -87,15 +86,13 @@ Sentry MCP server configured at `https://mcp.sentry.dev/mcp`. The source of trut ## Skill Tree Navigation **How it works:** -- 3 router skills (always visible in agent metadata): `sentry-sdk-setup`, `sentry-workflow`, `sentry-feature-setup` +- Router skills (always visible in agent metadata) group related skills; `sentry-feature-setup` is the last remaining one as the library migrates to flat standalone skills - All other skills are hidden with `disable-model-invocation: true` — loaded on-demand when a router points to them - `src/SKILL_TREE.md` is the flat sitemap listing every skill - This keeps startup metadata at ~300 tokens instead of ~1,600+ as the library grows - Tools that don't support `disable-model-invocation` simply see all skills (same as before) **Categories:** -- `sdk-setup` — platform/language SDK setup wizards (router: `sentry-sdk-setup`) -- `workflow` — debugging, code review, issue management (router: `sentry-workflow`) - `feature-setup` — specific feature configuration (router: `sentry-feature-setup`) - `internal` — contributor tools, no router diff --git a/README.md b/README.md index eb0deafb..b9f0474f 100644 --- a/README.md +++ b/README.md @@ -99,12 +99,6 @@ To build any target locally, run `src/plugins//build.sh ` | `sentry-instrument` | Add Sentry to a project, or wire up any signal — error monitoring, tracing, logging, metrics, profiling, session replay, user feedback, cron check-ins, and AI/LLM monitoring. Detects your platform and pulls the code from the reference library. | | `sentry-debug-issue` | Find a Sentry issue, pull full context, optionally run Seer root-cause / autofix, apply the fix, and resolve it | -### Workflow - -| Skill | What it does | -|-------|--------------| -| `sentry-sdk-upgrade` | Upgrade the Sentry JavaScript SDK across major versions | - ### Feature Setup | Skill | What it does | @@ -127,7 +121,7 @@ To build any target locally, run `src/plugins//build.sh ` The plugin configures the [Sentry MCP server](https://mcp.sentry.dev) automatically on install. No extra setup needed. -Some workflow skills require the [GitHub CLI](https://cli.github.com/): +Some skills require the [GitHub CLI](https://cli.github.com/): ```bash brew install gh # macOS diff --git a/src/SKILL_TREE.md b/src/SKILL_TREE.md index 85d236c4..ab1e9214 100644 --- a/src/SKILL_TREE.md +++ b/src/SKILL_TREE.md @@ -37,7 +37,6 @@ Debug production issues and maintain code quality with Sentry context. | Use when | Skill | |---|---| -| Upgrade the Sentry JavaScript SDK across major versions | [`sentry-sdk-upgrade`](skills/sentry-sdk-upgrade/SKILL.md) | ## Feature Setup diff --git a/src/skills/sentry-sdk-upgrade/SKILL.md b/src/skills/sentry-sdk-upgrade/SKILL.md deleted file mode 100644 index d3fdc55d..00000000 --- a/src/skills/sentry-sdk-upgrade/SKILL.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -name: sentry-sdk-upgrade -description: Upgrade the Sentry JavaScript SDK across major versions. Use when asked to upgrade Sentry, migrate to a newer version, fix deprecated Sentry APIs, or resolve breaking changes after a Sentry version bump. -license: Apache-2.0 -category: workflow -parent: sentry-workflow -disable-model-invocation: true ---- - -> [All Skills](../../SKILL_TREE.md) > [Workflow](../sentry-workflow/SKILL.md) > SDK Upgrade - -# Sentry JavaScript SDK Upgrade - -Upgrade the Sentry JavaScript SDK across major versions with AI-guided migration. - -## Invoke This Skill When - -- User asks to "upgrade Sentry" or "migrate Sentry SDK" -- User mentions deprecated Sentry APIs or breaking changes after a version bump -- User wants to move from v7 to v8, v8 to v9, or any major version jump -- User encounters errors after updating `@sentry/*` package versions -- User asks about Sentry migration guides or changelogs - -## Phase 1: Detect - -Identify the current Sentry SDK version, target version, and framework. - -### 1.1 Read package.json - -```bash -cat package.json | grep -E '"@sentry/' | head -20 -``` - -Extract: -- All `@sentry/*` packages and their current versions -- The current major version (e.g., `7.x`, `8.x`, `9.x`) - -### 1.2 Detect Framework - -Check `package.json` dependencies for framework indicators: - -| Dependency | Framework | Sentry Package | -|---|---|---| -| `next` | Next.js | `@sentry/nextjs` | -| `nuxt` or `@nuxt/kit` | Nuxt | `@sentry/nuxt` | -| `@sveltejs/kit` | SvelteKit | `@sentry/sveltekit` | -| `@remix-run/node` | Remix | `@sentry/remix` | -| `react` (no Next/Remix) | React SPA | `@sentry/react` | -| `@angular/core` | Angular | `@sentry/angular` | -| `vue` (no Nuxt) | Vue | `@sentry/vue` | -| `express` | Express | `@sentry/node` | -| `@nestjs/core` | NestJS | `@sentry/nestjs` | -| `@solidjs/start` | SolidStart | `@sentry/solidstart` | -| `astro` | Astro | `@sentry/astro` | -| `bun` types or runtime | Bun | `@sentry/bun` | -| `@cloudflare/workers-types` | Cloudflare | `@sentry/cloudflare` | -| None of above (Node.js) | Node.js | `@sentry/node` | - -### 1.3 Find Sentry Config Files - -```bash -grep -rn "from '@sentry/\|require('@sentry/" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" --include="*.cjs" -l -``` - -```bash -find . -name "sentry.*" -o -name "*.sentry.*" -o -name "instrumentation.*" | grep -v node_modules | grep -v .next | grep -v .nuxt -``` - -### 1.4 Detect Deprecated Patterns - -Scan for patterns that indicate which migration steps are needed: - -```bash -# v7 patterns (need v7→v8 migration) -grep -rn "from '@sentry/hub'\|from '@sentry/tracing'\|from '@sentry/integrations'\|from '@sentry/serverless'\|from '@sentry/replay'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l -grep -rn "new BrowserTracing\|new Replay\|startTransaction\|configureScope\|Handlers\.requestHandler\|Handlers\.errorHandler" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l - -# v8 patterns (need v8→v9 migration) -grep -rn "from '@sentry/utils'\|from '@sentry/types'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l -grep -rn "getCurrentHub\|enableTracing\|captureUserFeedback\|@WithSentry\|autoSessionTracking" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l -``` - -### 1.5 Determine Target Version - -If the user didn't specify a target version, recommend the latest major version (v9 as of this writing). If the user has already bumped package versions but has broken code, detect the target from `package.json`. - -## Phase 2: Recommend - -Present a migration summary based on detected state. - -### 2.1 Calculate Migration Path - -- **Single hop**: e.g., v8 to v9 -- **Multi-hop**: e.g., v7 to v9 (apply v7→v8 changes first, then v8→v9) - -For multi-hop migrations, apply code changes incrementally but update package versions once to the final target. - -### 2.2 Present Breaking Changes Summary - -Load the appropriate version-specific reference: -- v7→v8: [references/v7-to-v8.md](references/v7-to-v8.md) -- v8→v9: [references/v8-to-v9.md](references/v8-to-v9.md) -- v9→v10: [references/v9-to-v10.md](references/v9-to-v10.md) - -Present a concrete summary of changes needed, categorized by complexity: - -**Auto-fixable** (apply directly): -- Package import renames (e.g., `@sentry/utils` to `@sentry/core`) -- Simple method renames (e.g., `@WithSentry` to `@SentryExceptionCaptured`) -- Config option swaps (e.g., `enableTracing` to `tracesSampleRate`) - -**AI-assisted** (explain and propose): -- Hub removal with variable storage patterns -- Performance API migration (transactions to spans) -- Complex config restructuring (Vue tracing options, Next.js config merging) -- Sampler `transactionContext` flattening - -**Manual review** (flag for user): -- Removed APIs with no equivalent -- Behavioral changes (sampling, source maps defaults) -- Custom transport modifications - -### 2.3 Confirm Scope - -Ask the user: -- Confirm the migration path (e.g., "v8 to v9") -- Confirm whether to proceed with all changes or specific categories -- Note: `npx @sentry/wizard -i upgrade` exists as a CLI alternative for v8→v9 but may not handle all patterns - -## Phase 3: Guide - -Step through changes file by file. - -### 3.1 Process Each File with Sentry Imports - -For each file identified in Phase 1.3: - -1. **Read the file** to understand current Sentry usage -2. **Apply auto-fixable changes** directly: - - Package import renames - - Method/function renames - - Simple config option swaps -3. **For AI-assisted changes**, explain what needs to change and why, then propose the specific edit -4. **For uncertain changes**, show the code and ask the user to confirm - -### 3.2 Apply Changes by Category - -Work through changes in this order: - -#### Step 1: Package Import Updates -Replace removed/renamed package imports. Reference the version-specific migration file for the complete mapping. - -#### Step 2: API Renames -Apply mechanical method and function renames. - -#### Step 3: Config Changes -Update `Sentry.init()` options and build configuration. - -#### Step 4: Complex Pattern Migration -Handle patterns requiring understanding of context: -- Hub usage stored in variables -- Transaction-based performance code -- Custom integration classes -- Framework-specific wrappers - -#### Step 5: Update package.json Versions - -Update all `@sentry/*` packages to the target version. All packages must be on the same major version. - -```bash -# Detect package manager -if [ -f "yarn.lock" ]; then - echo "yarn" -elif [ -f "pnpm-lock.yaml" ]; then - echo "pnpm" -else - echo "npm" -fi -``` - -Install updated dependencies using the detected package manager. - -#### Step 6: Verify Build - -```bash -# Check for type errors -npx tsc --noEmit 2>&1 | head -50 - -# Run build -npm run build 2>&1 | tail -20 -``` - -Fix any remaining type errors or build failures. - -### 3.3 Framework-Specific Steps - -Consult [references/upgrade-patterns.md](references/upgrade-patterns.md) for framework-specific config file locations and validation steps. - -**Next.js**: Check `instrumentation.ts`, `next.config.ts` wrapper, both client and server configs. -**Nuxt**: Check Nuxt module config and both plugin files. -**SvelteKit**: Check hooks files and Vite config. -**Express/Node**: Verify early initialization order. -**NestJS**: Check for decorator and filter renames. - -## Phase 4: Cross-Link - -### 4.1 Verify - -- [ ] All `@sentry/*` packages on same version -- [ ] No import errors from removed packages -- [ ] TypeScript compilation passes -- [ ] Build succeeds -- [ ] Tests pass (if they exist) - -Suggest adding a test error: - -```js -// Add temporarily to verify Sentry is working after upgrade -setTimeout(() => { - throw new Error('Sentry upgrade verification - safe to delete'); -}, 3000); -``` - -### 4.2 New Features in Target Version - -Mention features available in the new version that the user might want to enable: - -**v8 new features**: OpenTelemetry-based Node tracing, automatic database/HTTP instrumentation, functional integrations, new span APIs - -**v9 new features**: Structured logging (`Sentry.logger.*`), improved source maps handling, simplified configuration - -### 4.3 Related Resources - -- [Official Migration Guide (v7→v8)](https://docs.sentry.io/platforms/javascript/migration/v7-to-v8/) -- [Official Migration Guide (v8→v9)](https://docs.sentry.io/platforms/javascript/migration/v8-to-v9/) -- [Sentry JavaScript SDK Changelog](https://github.com/getsentry/sentry-javascript/blob/develop/CHANGELOG.md) - -If the user has other Sentry SDKs (Python, Ruby, Go, etc.) that also need upgrading, note that this skill covers JavaScript SDK only. diff --git a/src/skills/sentry-sdk-upgrade/references/upgrade-patterns.md b/src/skills/sentry-sdk-upgrade/references/upgrade-patterns.md deleted file mode 100644 index 0f3c7fe0..00000000 --- a/src/skills/sentry-sdk-upgrade/references/upgrade-patterns.md +++ /dev/null @@ -1,176 +0,0 @@ -# Sentry SDK Upgrade — General Patterns - -Version-agnostic guidance for upgrading the Sentry JavaScript SDK across any major version. - -## Finding Sentry Code in a Project - -### Grep for All Sentry Imports - -```bash -grep -rn "from '@sentry/\|require('@sentry/" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" --include="*.cjs" -``` - -### Find Sentry Config Files - -```bash -# Common config file patterns -find . -name "sentry.*" -o -name "*.sentry.*" -o -name "instrumentation.*" | grep -v node_modules | grep -v .next -``` - -### Check Current Sentry Version - -```bash -# npm/yarn -cat package.json | grep -E '"@sentry/' | head -20 - -# Actual installed version -ls node_modules/@sentry/*/package.json 2>/dev/null | head -5 | xargs -I{} sh -c 'echo "--- {} ---" && grep "\"version\"" {}' -``` - -## Common Config File Locations by Framework - -| Framework | Client Config | Server Config | Build Config | Other | -|---|---|---|---|---| -| **Next.js** | `instrumentation-client.ts` | `sentry.server.config.ts` | `next.config.ts` (wrapped with `withSentryConfig`) | `instrumentation.ts`, `sentry.edge.config.ts` | -| **Nuxt** | `sentry.client.config.ts` | `sentry.server.config.ts` | `nuxt.config.ts` | — | -| **SvelteKit** | `src/hooks.client.ts` | `src/hooks.server.ts` | `vite.config.ts` | — | -| **Remix** | `entry.client.tsx` | `entry.server.tsx` | — | — | -| **React (SPA)** | `src/index.tsx` or `src/main.tsx` | — | — | — | -| **Angular** | `src/main.ts` | — | — | — | -| **Vue** | `src/main.ts` | — | — | — | -| **Express/Node** | — | `app.ts` or `server.ts` | — | `instrument.ts` | -| **NestJS** | — | `main.ts` | — | `instrument.ts` | -| **Astro** | `astro.config.mjs` | — | — | — | - -## Package Manager Commands for Version Bumps - -### npm - -```bash -# Upgrade all @sentry packages to latest -npm install @sentry/browser@latest @sentry/node@latest # list all packages - -# Or use npm-check-updates -npx npm-check-updates -f '@sentry/*' -u && npm install -``` - -### yarn - -```bash -# Upgrade all @sentry packages -yarn add @sentry/browser@latest @sentry/node@latest # list all packages - -# Or use yarn upgrade-interactive -yarn upgrade-interactive --latest -``` - -### pnpm - -```bash -# Upgrade all @sentry packages -pnpm update @sentry/browser@latest @sentry/node@latest # list all packages - -# Or update all Sentry packages at once -pnpm update '@sentry/*' --latest -``` - -## Validation Steps After Upgrade - -### 1. Install Dependencies - -```bash -# Remove lockfile and node_modules for clean install (if needed) -rm -rf node_modules -npm install # or yarn / pnpm install -``` - -### 2. Check for Type Errors - -```bash -npx tsc --noEmit -``` - -### 3. Run Tests - -```bash -npm test # or yarn test / pnpm test -``` - -### 4. Build the Project - -```bash -npm run build # or yarn build / pnpm build -``` - -### 5. Verify Sentry Is Working - -Add a test error to verify events reach Sentry: - -```js -// Temporarily add to any entry point -setTimeout(() => { - throw new Error('Sentry SDK upgrade test - safe to delete'); -}, 3000); -``` - -Check the Sentry dashboard for the test error, then remove it. - -## Framework-Specific Upgrade Considerations - -### Next.js - -- Check both client and server Sentry configs -- Verify `withSentryConfig` wrapper in `next.config.ts` -- Ensure `instrumentation.ts` exists and loads Sentry server config -- Test both dev and production builds (`next dev` and `next build`) -- Check source maps upload in production build output - -### Nuxt - -- Sentry module config in `nuxt.config.ts` may need updating -- Check both client and server plugin files -- Verify source maps configuration - -### SvelteKit - -- Check `sentryHandle()` in hooks files -- Verify Vite plugin configuration -- Check `sentryHandleError()` setup - -### React (SPA) - -- Verify browser tracing integration -- Check React Router integration version compatibility -- Test error boundary components - -### Express/Node - -- Ensure Sentry is initialized before other imports (v8+) -- Verify error handler placement (`setupExpressErrorHandler`) -- Check custom middleware for Sentry scope usage - -### NestJS - -- Verify `@sentry/nestjs` package (moved from `@sentry/node` in v9) -- Check decorators and filters for renames -- Remove deprecated `SentryService` and `SentryTracingInterceptor` - -## Multi-Hop Migrations - -When upgrading across multiple major versions (e.g., v7 to v9): - -1. **Upgrade one major version at a time** — apply v7→v8 changes, verify, then v8→v9 -2. **Update package versions once** — bump to the final target version but apply code changes incrementally -3. **Use the version-specific grep patterns** to find code needing changes at each step -4. **Test after each logical migration step** — don't wait until all changes are made - -## Common Pitfalls - -| Pitfall | Solution | -|---|---| -| Forgetting to update all `@sentry/*` packages to same version | Use package manager bulk update commands | -| Missing type errors because TypeScript is too old | Check minimum TypeScript version for target SDK version | -| Build works but runtime errors | Test with actual requests/errors, not just build | -| Source maps broken after upgrade | Check `sourcemaps` config options changed between versions | -| Node SDK not capturing server errors | Verify early initialization (must be first import in v8+) | -| Next.js missing server-side errors | Verify `instrumentation.ts` file exists and is configured | diff --git a/src/skills/sentry-sdk-upgrade/references/v7-to-v8.md b/src/skills/sentry-sdk-upgrade/references/v7-to-v8.md deleted file mode 100644 index 44f6a076..00000000 --- a/src/skills/sentry-sdk-upgrade/references/v7-to-v8.md +++ /dev/null @@ -1,251 +0,0 @@ -# Sentry JavaScript SDK: v7 to v8 Migration Reference - -This is the largest migration. v8 overhauled performance monitoring APIs, moved to OpenTelemetry, removed deprecated packages, and switched integrations from classes to functions. - -Recommend upgrading to latest v7 first and removing deprecated v7 APIs before jumping to v8. - -## Version Support Changes - -| Runtime | v7 | v8 | -|---|---|---| -| Node.js (CJS) | 8+ | 14.18+ | -| Node.js (ESM) | 8+ | 18.19.1+ | -| Browsers | IE11+ | ES2018+ (Chrome 71, Edge 79, Safari 12.1, Firefox 65) | -| Next.js | 10+ | 13.2.0+ | -| Angular | 12+ | 14+ | -| React | 15+ | 16+ | - -## Package Removals - -These packages were removed entirely in v8. Update imports accordingly. - -| Removed Package | Replacement | Notes | -|---|---|---| -| `@sentry/hub` | `@sentry/core` | All exports moved to `@sentry/core` | -| `@sentry/tracing` | Direct SDK imports | See browser/node sections below | -| `@sentry/integrations` | `@sentry/browser` or `@sentry/node` | Integrations are now functions, not classes | -| `@sentry/serverless` | `@sentry/aws-serverless` or `@sentry/google-cloud-serverless` | Split into two packages | -| `@sentry/replay` | `@sentry/browser` | Import `replayIntegration` from browser SDK | -| `@sentry/angular-ivy` | `@sentry/angular` | Angular package now supports Ivy by default | - -### `@sentry/tracing` Removal - -**Browser** - Replace `BrowserTracing` class with `browserTracingIntegration()` function: - -```diff -- import { BrowserTracing } from '@sentry/tracing'; - import * as Sentry from '@sentry/browser'; - - Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -- integrations: [new BrowserTracing()], -+ integrations: [Sentry.browserTracingIntegration()], - }); -``` - -**Node** - Simply remove the `@sentry/tracing` import: - -```diff - const Sentry = require('@sentry/node'); -- require('@sentry/tracing'); - - Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - }); -``` - -### `@sentry/integrations` Removal - -All integrations moved to `@sentry/browser` or `@sentry/node` and became functions: - -| Old (v7) | New (v8) | Available In | -|---|---|---| -| `new CaptureConsole()` | `captureConsoleIntegration()` | browser + node | -| `new Debug()` | `debugIntegration()` | browser + node | -| `new ExtraErrorData()` | `extraErrorDataIntegration()` | browser + node | -| `new RewriteFrames()` | `rewriteFramesIntegration()` | browser + node | -| `new SessionTiming()` | `sessionTimingIntegration()` | browser + node | -| `new Dedupe()` | `dedupeIntegration()` | browser + node (default) | -| `new HTTPClient()` | `httpClientIntegration()` | browser | -| `new ContextLines()` | `contextLinesIntegration()` | browser | -| `new ReportingObserver()` | `reportingObserverIntegration()` | browser | - -### `@sentry/serverless` Removal - -```diff -- const Sentry = require('@sentry/serverless'); -- Sentry.AWSLambda.init({ dsn: '__DSN__' }); -+ const Sentry = require('@sentry/aws-serverless'); -+ Sentry.init({ dsn: '__DSN__' }); -``` - -```diff -- const Sentry = require('@sentry/serverless'); -- Sentry.GCPFunction.init({ dsn: '__DSN__' }); -+ const Sentry = require('@sentry/google-cloud-serverless'); -+ Sentry.init({ dsn: '__DSN__' }); -``` - -## Integration API Overhaul - -All integrations changed from classes to functions: - -```diff -- integrations: [new Sentry.Replay()] -+ integrations: [Sentry.replayIntegration()] -``` - -```diff -- integrations: [new Sentry.BrowserTracing()] -+ integrations: [Sentry.browserTracingIntegration()] -``` - -Accessing integrations changed: - -```diff -- const replay = Sentry.getIntegration(Replay); -+ const replay = Sentry.getClient().getIntegrationByName('Replay'); -``` - -## Performance Monitoring API Changes - -The transaction-based API was replaced with OpenTelemetry-aligned span API: - -```diff -- const transaction = Sentry.startTransaction({ name: 'my-transaction' }); -- const span = transaction.startChild({ op: 'task' }); -- span.finish(); -- transaction.finish(); -+ const result = Sentry.startSpan({ name: 'my-transaction' }, () => { -+ return Sentry.startSpan({ name: 'task', op: 'task' }, () => { -+ return doWork(); -+ }); -+ }); -``` - -New span APIs: -- `Sentry.startSpan()` - Active span with callback (recommended) -- `Sentry.startInactiveSpan()` - Inactive span without callback -- `Sentry.startSpanManual()` - Manual span end control - -Removed: `startTransaction`, `span.startChild`, `scope.getSpan`, `scope.setSpan`, `getActiveTransaction` - -## Scope API Changes - -| Removed (v7) | Replacement (v8) | -|---|---| -| `Sentry.configureScope(cb)` | `Sentry.getCurrentScope().setTag(...)` directly | -| `addGlobalEventProcessor(fn)` | `Sentry.getGlobalScope().addEventProcessor(fn)` | -| `runWithAsyncContext(fn)` | `Sentry.withIsolationScope(fn)` | -| `makeMain(hub)` | Removed, use new init patterns | -| `pushScope()` / `popScope()` | `Sentry.withScope(fn)` | - -## Hub Deprecation - -In v8, `Hub` and `getCurrentHub()` still exist but are deprecated (fully removed in v9): - -```diff -- const hub = Sentry.getCurrentHub(); -- hub.captureException(error); -+ Sentry.captureException(error); -``` - -## Config Option Changes - -| Removed Option | Replacement | -|---|---| -| `tracingOrigins` | `tracePropagationTargets` (moved to `Sentry.init()`) | -| `interactionsSampleRate` | Use `tracesSampler` to filter by `sentry.op` | -| `Severity` enum | `SeverityLevel` type (use string literals) | -| `metricsAggregator` experiment | Metrics now work without configuration | - -## Node.js SDK Initialization Changes - -v8 Node SDK uses OpenTelemetry, requiring early initialization. SDK must be initialized before other imports: - -```js -// Must be the first import -import * as Sentry from '@sentry/node'; - -Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, -}); - -// Other imports after Sentry.init() -import express from 'express'; -``` - -## Express/Connect Handler Changes - -```diff -- Sentry.Handlers.requestHandler() -- Sentry.Handlers.tracingHandler() -- Sentry.Handlers.errorHandler() -+ Sentry.setupExpressErrorHandler(app) // Only error handler needed -``` - -```diff -- Sentry.Handlers.trpcMiddleware() -+ Sentry.trpcMiddleware() -``` - -## Next.js Specific Changes - -- `withSentryConfig` now takes 2 args (not 3). Plugin options and SDK options merged into second arg. -- `sentry` property in `next.config.js` removed. Use `withSentryConfig` second arg. -- New `instrumentation.ts` file required for server-side initialization. -- `transpileClientSDK` option removed (IE11 no longer supported). -- Removed: `nextRouterInstrumentation`, `withSentryApi`, `withSentryGetServerSideProps`, etc. - -## SvelteKit Specific Changes - -- `@sentry/vite-plugin` upgraded from 0.x to 2.x -- `sourceMapsUploadOptions` restructured (release/sourcemaps nested objects) - -## Other Removed APIs - -| Removed | Replacement | -|---|---| -| `spanStatusfromHttpCode` | `getSpanStatusFromHttpCode` | -| `Span` class export | No longer exported (internal `SentrySpan`) | -| `enableAnrDetection` / `Anr` class | Use `anrIntegration()` | -| `deepReadDirSync` | No replacement | -| `Apollo` integration | Automatic via `graphqlIntegration` | -| `Offline` integration | Use offline transport wrapper | -| `makeXHRTransport` | Use `makeFetchTransport` | -| `wrap` method | No replacement | - -## Grep Patterns to Find v7 Code - -```bash -# Package imports that need updating -grep -rn "from '@sentry/hub'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "from '@sentry/tracing'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "from '@sentry/integrations'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "from '@sentry/serverless'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "from '@sentry/replay'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "from '@sentry/angular-ivy'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" - -# Deprecated API usage -grep -rn "new BrowserTracing\|new Replay\|new Integrations\." --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "startTransaction\|\.startChild\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "configureScope\|getCurrentHub\|addGlobalEventProcessor" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "Handlers\.requestHandler\|Handlers\.tracingHandler\|Handlers\.errorHandler" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "tracingOrigins" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "Severity\." --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -``` - -## Migration Complexity Rating - -| Category | Complexity | Notes | -|---|---|---| -| Package renames | Low | Mechanical find-and-replace | -| Integration class → function | Low | Mechanical pattern change | -| Performance API overhaul | High | Requires understanding new span model | -| Hub → Scope API | Medium | Pattern-dependent complexity | -| Node.js early init | Medium | Requires restructuring imports | -| Next.js changes | Medium | Config restructuring + instrumentation file | -| Express handler changes | Low | Simplified API | diff --git a/src/skills/sentry-sdk-upgrade/references/v8-to-v9.md b/src/skills/sentry-sdk-upgrade/references/v8-to-v9.md deleted file mode 100644 index 7f2335ae..00000000 --- a/src/skills/sentry-sdk-upgrade/references/v8-to-v9.md +++ /dev/null @@ -1,277 +0,0 @@ -# Sentry JavaScript SDK: v8 to v9 Migration Reference - -v9 focuses on API cleanup: removing deprecated v8 APIs, package consolidation, and dropping support for older runtimes. This update contains behavioral changes not caught by type checkers. - -Compatible with Sentry self-hosted 24.4.2+ (unchanged from v8). - -## Version Support Changes - -| Runtime | v8 | v9 | -|---|---|---| -| Node.js | 14.18+ | 18.0.0+ (ESM-only SDKs: 18.19.1+) | -| Browsers | ES2018+ | ES2020+ (Chrome 80, Edge 80, Safari 14, Firefox 74) | -| TypeScript | 4.9.3+ | 5.0.4+ | -| Deno | 1.x | 2.0.0+ | - -### Framework Support Dropped - -- **Remix** 1.x (minimum: 2.x) -- **TanStack Router** 1.63.0 and lower -- **SvelteKit** 1.x (minimum: 2.x) -- **Ember.js** 3.x and lower (minimum: 4.x) -- **Prisma** 5.x (default: 6.x, older via `prismaInstrumentation` option) - -## Package Consolidation - -| Removed Package | Replacement | -|---|---| -| `@sentry/utils` | `@sentry/core` (all exports moved) | -| `@sentry/types` | `@sentry/core` (deprecated, still published but won't be in next major) | - -```diff -- import { something } from '@sentry/utils'; -+ import { something } from '@sentry/core'; -``` - -```diff -- import { SomeType } from '@sentry/types'; -+ import { SomeType } from '@sentry/core'; -``` - -## Removed APIs — All SDKs (`@sentry/core`) - -### Hub Removal (Final) - -`getCurrentHub()`, `Hub`, and `getCurrentHubShim()` are **fully removed** (were deprecated in v8). - -| v8 (deprecated) | v9 | -|---|---| -| `getCurrentHub().captureException(e)` | `Sentry.captureException(e)` | -| `getCurrentHub().captureMessage(m)` | `Sentry.captureMessage(m)` | -| `getCurrentHub().captureEvent(e)` | `Sentry.captureEvent(e)` | -| `getCurrentHub().addBreadcrumb(b)` | `Sentry.addBreadcrumb(b)` | -| `getCurrentHub().setTag(k, v)` | `Sentry.getCurrentScope().setTag(k, v)` | -| `getCurrentHub().setExtra(k, v)` | `Sentry.getCurrentScope().setExtra(k, v)` | -| `getCurrentHub().setUser(u)` | `Sentry.setUser(u)` | -| `getCurrentHub().getClient()` | `Sentry.getClient()` | -| `getCurrentHub().getScope()` | `Sentry.getCurrentScope()` | - -### Metrics API Removed - -The Sentry metrics beta ended. The entire metrics API was removed from the SDK. - -### `enableTracing` Option Removed - -```diff - Sentry.init({ -- enableTracing: true, -+ tracesSampleRate: 1, - }); -``` - -### `autoSessionTracking` Option Removed - -To disable session tracking, remove `browserSessionIntegration` (browser) or configure `httpIntegration` with `trackIncomingRequestsAsSessions: false` (server). - -### `transactionContext` Flattened in Samplers - -```diff - Sentry.init({ - tracesSampler: samplingContext => { -- if (samplingContext.transactionContext.name === '/health-check') { -+ if (samplingContext.name === '/health-check') { - return 0; - } - return 0.5; - }, - }); -``` - -Also applies to `profilesSampler`. - -### Other Removed APIs - -| Removed | Replacement | -|---|---| -| `addOpenTelemetryInstrumentation(inst)` | `Sentry.init({ openTelemetryInstrumentations: [inst] })` | -| `debugIntegration` | Use hook options (`beforeSend`, etc.) | -| `sessionTimingIntegration` | Use `Sentry.setContext()` | -| `generatePropagationContext()` | `generateTraceId()` | -| `IntegrationClass` type | `Integration` or `IntegrationFn` | -| `BAGGAGE_HEADER_NAME` | Use `"baggage"` string directly | -| `extractRequestData` | Manually extract request data | -| `addRequestDataToEvent` | Use `httpRequestToRequestData` | -| `DEFAULT_USER_INCLUDES` | No replacement | -| `SessionFlusher` | No replacement | - -## Removed APIs — Browser (`@sentry/browser`) - -| Removed | Replacement | -|---|---| -| `captureUserFeedback({ comments })` | `captureFeedback({ message })` | - -```diff -- Sentry.captureUserFeedback({ -- event_id: eventId, -- name: 'User', -- email: 'user@example.com', -- comments: 'Something broke', -- }); -+ Sentry.captureFeedback({ -+ name: 'User', -+ email: 'user@example.com', -+ message: 'Something broke', -+ associatedEventId: eventId, -+ }); -``` - -## Removed APIs — Node (`@sentry/node`) - -| Removed | Replacement | -|---|---| -| `nestIntegration` | Use `@sentry/nestjs` package | -| `setupNestErrorHandler` | Use `@sentry/nestjs` package | -| `registerEsmLoaderHooks` options | Only accepts `true \| false \| undefined` | - -### Integration Renames - -| v8 Name | v9 Name | -|---|---| -| `processThreadBreadcrumbIntegration` | `childProcessIntegration` | - -### Behavior Changes - -- `tracesSampler` no longer called for every span (only root spans). -- `requestDataIntegration` no longer auto-sets user from `request.user` in Express. Use `Sentry.setUser()` manually. -- `samplingContext.request` removed; use `samplingContext.normalizedRequest`. -- `skipOpenTelemetrySetup: true` now auto-configures `httpIntegration({ spans: false })`. - -## Removed APIs — React (`@sentry/react`) - -| Removed | Replacement | -|---|---| -| `wrapUseRoutes` | `wrapUseRoutesV6` or `wrapUseRoutesV7` | -| `wrapCreateBrowserRouter` | `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` | - -## Removed APIs — NestJS (`@sentry/nestjs`) - -| Removed | Replacement | -|---|---| -| `@WithSentry` decorator | `@SentryExceptionCaptured` | -| `SentryService` | Remove (no longer needed) | -| `SentryTracingInterceptor` | Remove (no longer needed) | -| `SentryGlobalGenericFilter` | `SentryGlobalFilter` | -| `SentryGlobalGraphQLFilter` | `SentryGlobalFilter` | - -## Removed APIs — Vue (`@sentry/vue`) - -Vue tracing options removed from `Sentry.init()`. Use `vueIntegration()` instead: - -```diff - Sentry.init({ -- tracingOptions: { trackComponents: true }, -+ integrations: [ -+ Sentry.vueIntegration({ -+ tracingOptions: { -+ trackComponents: true, -+ timeout: 1000, -+ hooks: ['mount', 'update', 'unmount'], -+ }, -+ }), -+ ], - }); -``` - -`logErrors` option removed from `vueIntegration` (error handler always propagates). - -## Removed APIs — Nuxt (`@sentry/nuxt`) - -- `tracingOptions` in `Sentry.init()` removed. Use `vueIntegration()`. -- `stateTransformer` in `piniaIntegration` now receives full state from all stores (top-level keys = store IDs). - -## Removed APIs — Next.js (`@sentry/nextjs`) - -| Removed | Notes | -|---|---| -| `hideSourceMaps` option | SDK emits hidden sourcemaps by default | -| `sentry` property in next config | Pass options to `withSentryConfig` directly | - -Behavior changes: -- Client source maps auto-deleted after upload (opt out via `sourcemaps.deleteSourcemapsAfterUpload: false`). -- Next.js Build ID no longer used as release fallback. Set `release.name` manually if needed. -- Source maps auto-enabled for both client and server builds. - -## Removed APIs — Other Frameworks - -| Package | Removed | Replacement | -|---|---|---| -| `@sentry/remix` | `autoInstrumentRemix` option | Always behaves as `true` | -| `@sentry/sveltekit` | `fetchProxyScriptNonce` option | Use script hash in CSP or disable fetch proxy | -| `@sentry/solidstart` | `sentrySolidStartVite` | `withSentry()` wrapper | - -## Behavior Changes — All SDKs - -- `beforeSendSpan`: Cannot return `null` (dropping spans). Now also receives root spans. -- `startSpan` with custom `scope`: Scope is now cloned (was set directly in v8 for non-Node SDKs). -- `tracesSampleRate: undefined` now defers sampling to downstream SDKs. -- `captureConsoleIntegration` with `attachStackTrace: true`: Console messages now `handled: true`. -- Browser SDK no longer instructs backend to infer IP by default. Set `sendDefaultPii: true` to restore. - -## Behavior Changes — Vue/Nuxt - -- Component tracking "update" spans no longer created by default. Add `'update'` to `tracingOptions.hooks` to restore. - -## Type Changes - -- `Scope` usages now require `Scope` instances (not interface-compatible objects). -- `Client` usages now require `BaseClient` instances. Abstract `Client` class removed. - -## Grep Patterns to Find v8 Code Needing Updates - -```bash -# Package imports that need updating -grep -rn "from '@sentry/utils'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "from '@sentry/types'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" - -# Hub usage (fully removed) -grep -rn "getCurrentHub\|getCurrentHubShim\|new Hub(" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" - -# Removed options -grep -rn "enableTracing\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "autoSessionTracking\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "hideSourceMaps\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "autoInstrumentRemix\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" - -# Removed methods -grep -rn "captureUserFeedback\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "addOpenTelemetryInstrumentation\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "transactionContext\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" - -# Method renames -grep -rn "@WithSentry\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "SentryGlobalGenericFilter\|SentryGlobalGraphQLFilter" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "wrapUseRoutes[^V]" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "wrapCreateBrowserRouter[^V]" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -grep -rn "processThreadBreadcrumbIntegration" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" - -# Metrics API (removed) -grep -rn "Sentry\.metrics\." --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" - -# Vue/Nuxt tracing options at init level -grep -rn "tracingOptions.*trackComponents\|trackComponents.*true" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -``` - -## Migration Complexity Rating - -| Category | Complexity | Notes | -|---|---|---| -| Package consolidation (`utils`/`types` to `core`) | Low | Mechanical import replacement | -| Hub removal | Medium | Depends on how deeply Hub was used; variable storage patterns require manual review | -| `enableTracing` removal | Low | Simple option swap | -| Method renames | Low | Mechanical find-and-replace | -| React Router wrappers | Low | Version-specific rename | -| NestJS decorator rename | Low | Simple rename | -| Vue tracing options restructure | Medium | Requires restructuring init config | -| `captureUserFeedback` to `captureFeedback` | Low | Field rename (`comments` to `message`) | -| Next.js source maps behavior | Low | Understand new defaults | -| Behavioral changes (`beforeSendSpan`, sampling) | Medium | Review existing hooks for compatibility | diff --git a/src/skills/sentry-sdk-upgrade/references/v9-to-v10.md b/src/skills/sentry-sdk-upgrade/references/v9-to-v10.md deleted file mode 100644 index ace14779..00000000 --- a/src/skills/sentry-sdk-upgrade/references/v9-to-v10.md +++ /dev/null @@ -1,40 +0,0 @@ -# Sentry JavaScript SDK: v9 to v10 Migration Reference - -v10 has not been released yet. This reference will be populated when the v10 migration guide is published. - -## Current Status - -As of March 2026, v9 is the latest major version of the Sentry JavaScript SDK. No v10 migration guide exists yet. - -## Known v9 Deprecations (Likely Removed in v10) - -These were deprecated in v9 and will likely be removed in v10: - -| Deprecated | Replacement | -|---|---| -| `logger` export from `@sentry/core` (internal SDK logger) | `debug` export (`debug.log`, `debug.warn`, `debug.error`) | -| `@sentry/types` package | `@sentry/core` (all types available there) | - -```diff -- import { logger } from '@sentry/core'; -- logger.info('message'); -+ import { debug } from '@sentry/core'; -+ debug.log('message'); -``` - -## Preparation - -To prepare for v10: -1. Upgrade to latest v9 -2. Fix all deprecation warnings -3. Replace `@sentry/types` imports with `@sentry/core` -4. Replace internal `logger` usage with `debug` - -## When v10 Is Released - -Update this file with: -1. Version support changes -2. Removed APIs (from v9 deprecations) -3. Behavioral changes -4. Package changes -5. Migration grep patterns diff --git a/src/skills/sentry-workflow/SKILL.md b/src/skills/sentry-workflow/SKILL.md deleted file mode 100644 index 120ab8b5..00000000 --- a/src/skills/sentry-workflow/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: sentry-workflow -description: Keep Sentry SDKs up to date. Use when asked to upgrade the Sentry SDK across major versions, migrate SDK versions, or fix deprecated APIs. -license: Apache-2.0 -role: router ---- - -> [All Skills](../../SKILL_TREE.md) - -# Sentry Workflows - -Keep your Sentry SDK up to date. This page helps you find the right workflow skill for your task. - -## Start Here — Read This Before Doing Anything - -- If the user mentions **upgrading Sentry, migrating SDK versions, or fixing deprecated APIs** → `sentry-sdk-upgrade` - -> Fixing or investigating a production issue? That's the standalone `sentry-debug-issue` skill. - ---- - -## Workflow Skills - -| Use when | Skill | -|---|---| -| Upgrading the Sentry JavaScript SDK — migration guides, breaking changes, deprecated APIs | [`sentry-sdk-upgrade`](../sentry-sdk-upgrade/SKILL.md) | - -Each skill contains its own detection logic, prerequisites, and step-by-step instructions. Trust the skill — read it carefully and follow it. Do not improvise or take shortcuts. - ---- - -Looking for SDK setup or feature configuration instead? See the [full Skill Tree](../../SKILL_TREE.md).