* feat(node-sdk): add sentry-node-sdk main SKILL.md wizard
Introduces the sentry-node-sdk skill covering all three JS server-side
runtimes in a single unified wizard: Node.js, Bun, and Deno.
Key design decisions:
- One skill for all three runtimes — Bun is a thin wrapper over @sentry/node
(shares 99% of the API), and Deno shares the same core Sentry primitives,
so a unified skill with runtime-specific sections is cleaner than three
separate skills.
- Node.js wizard path: 'npx @sentry/wizard@latest -i node' is offered as
the recommended first option; manual setup covers CJS (require + first
line) and ESM (--import ./instrument.mjs flag, Node 18.19.0+ required).
- Bun: 'bun --preload ./instrument.ts' pattern; profiling explicitly marked
as unsupported (native addon incompatible).
- Deno: npm: specifier only (deno.land/x/sentry is deprecated); Deno 2.0+
required; --allow-net permissions documented; denoCronIntegration noted.
- All six framework error handlers documented (Express, Fastify, Koa, Hapi,
Connect, NestJS) with placement rules and async flag for Hapi.
- Feature support matrix per runtime so agents don't suggest profiling on Bun/Deno.
- Four-phase structure (Detect → Recommend → Guide → Cross-Link) consistent
with every other SDK skill in the bundle.
Also:
- Registers sentry-node-sdk in the sentry-sdk-setup router table
- Updates routing instructions (Next.js preference over node-sdk)
- Regenerates SKILL_TREE.md via build-skill-tree.sh (0 errors)
Co-Authored-By: Claude Sonnet 4.5 (Anthropic AI assistant)
* feat(node-sdk): add error monitoring reference for sentry-node-sdk
Adds a comprehensive ~1200-line error monitoring reference covering:
- Instrument-first rule with CJS and ESM startup patterns
- Auto-captured vs manual errors — the 'swallowed catch' gotcha
- Framework error handler placement rules (critical: differs per framework)
- Express: setupExpressErrorHandler AFTER routes
- Fastify: setupFastifyErrorHandler BEFORE routes
- Koa: setupKoaErrorHandler as FIRST middleware
- Hapi: await setupHapiErrorHandler (async — must await!)
- Connect: setupConnectErrorHandler BEFORE routes
- NestJS: SentryGlobalFilter + SentryModule.forRoot()
- Full captureException/captureMessage API with TypeScript signatures
- Scope management (v8+ Hub removal): global, isolation, current scopes
- withScope vs withIsolationScope — when to use each
- Context enrichment: setTag, setContext, setUser, setExtra, addBreadcrumb
- beforeSend, beforeBreadcrumb, ignoreErrors filtering
- Fingerprinting: per-capture, withScope, beforeSend global rules
- Event processors vs beforeSend (unlimited vs one-only)
- requestDataIntegration PII opt-in (body/cookies/IP)
- Error chains via linkedErrorsIntegration (Error.cause)
- Lifecycle: flush/close before shutdown (critical for serverless)
- Bun runtime: --preload pattern, profiling incompatibility
- Deno runtime: npm: specifier, Deno 2+ requirements
- Quick reference card
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* feat(node-sdk): add tracing reference for sentry-node-sdk
Adds a comprehensive 816-line tracing reference covering:
- OTel-native architecture in v8+: SentrySpanProcessor, SentryPropagator,
SentrySampler, SentryContextManager and how they compose
- Full auto-instrumentation table (28+ packages) across HTTP, databases
(pg, mysql2, mongodb, redis, prisma, sequelize, typeorm, knex), message
queues (kafkajs, amqplib, pubsub, SNS/SQS, bull, bullmq), GraphQL, and
AI/LLM libraries (OpenAI, Anthropic, LangChain, Vercel AI, Google GenAI)
- Custom span APIs: startSpan (auto-end), startSpanManual (manual end),
startInactiveSpan (not active), withActiveSpan (temporarily activate)
with real-world usage examples including middleware and parallel ops
- Sampling: tracesSampleRate, tracesSampler with SamplingContext shape,
inheritOrSampleWith() (v9+), and precedence rules
- Distributed tracing: sentry-trace/baggage headers, tracePropagationTargets,
continueTrace(), manual propagation over Kafka/AMQP/WebSocket
- Advanced APIs: startNewTrace(), suppressTracing(), forceTransaction,
onlyIfParent, ignoreSpans, beforeSendSpan, getActiveSpan, getRootSpan
- Framework auto-instrumentation patterns for Express, Fastify, Koa,
Hapi, and NestJS (with @SentryTraced decorator)
- Runtime differences table: Node.js (full), Bun (via Node, no profiling),
Deno (limited auto-instrumentation, manual HTTP wrapping required)
- Troubleshooting table for 12 common issues
Co-Authored-By: Claude claude.ai/code
* docs(sentry-node-sdk): add profiling.md reference
Add comprehensive profiling reference for the sentry-node-sdk skill covering
the @sentry/profiling-node native addon and all its configuration options.
Key points documented:
- Node.js only: native C++ addon via V8 CpuProfiler; Bun and Deno are
explicitly NOT supported (clearly called out at top and in platform table)
- Installation with strict version-matching requirement
- Trace mode (auto-attach to spans) vs manual mode (startProfiler/stopProfiler)
- Continuous profiling for long-running processes and batch jobs
- V2 chunk-based architecture: 60-second upload windows, no 30s cap
- profileSessionSampleRate semantics (once per process startup, not per request)
- Supported platforms table: macOS/Linux/Windows, x64/ARM64, Node 18-24
- Environment variables: SENTRY_PROFILER_BINARY_PATH, SENTRY_PROFILER_LOGGING_MODE
- Production recommendations with performance impact notes
- Alpine/Docker setup (musl libc variant, rebuild steps)
- 10-entry troubleshooting table covering all common failure modes
Follows the pattern established by skills/sentry-nextjs-sdk/references/profiling.md
but scoped to Node.js only (no browser profiling section).
Co-Authored-By: claude-sonnet-4-5 (Anthropic)
* docs(sentry-node-sdk): add logging, metrics, and crons reference files
Three new reference files for the sentry-node-sdk skill:
- logging.md: Covers the GA Sentry.logger.* API (v9.41.0+), the fmt tagged
template literal for parameterized messages, scope-based attributes
(v10.32.0+), consoleLoggingIntegration, createConsolaReporter, the
beforeSendLog hook, manual Winston/Pino bridge patterns (no official
transports), trace linking, buffer flushing, and a troubleshooting table.
- metrics.md: Covers the Open Beta Sentry.metrics.* API (v10.25.0+) with the
three methods count/gauge/distribution (no increment or set in v10), unit
strings, attribute cardinality guidance, scope-based attributes (v10.33.0+),
beforeSendMetric hook, and flush semantics.
- crons.md: Covers the GA crons API (v7.51.1+) including captureCheckIn,
withMonitor, heartbeat vs start/finish patterns, MonitorConfig upsert,
crontab and interval schedule types, official instrumentNodeCron /
instrumentCron / instrumentNodeSchedule helpers, manual patterns for Agenda
and BullMQ, serverless flush requirement, and rate limit details.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
* docs: register sentry-node-sdk in AGENTS.md and README.md
Add sentry-node-sdk to the SDK Skills table in both AGENTS.md and README.md.
The skill was already registered in sentry-sdk-setup router and SKILL_TREE.md
from prior work; this completes the documentation surface.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
* fix(node-sdk): address review findings — handler placement, NestJS imports, troubleshooting
P0: Fix Fastify error handler placement in SKILL.md (BEFORE routes, not after)
P0: Fix Connect error handler placement in SKILL.md (BEFORE routes, not after)
P1: Remove erroneous await on setupFastifyErrorHandler in tracing.md
P1: Fix SentryGlobalFilter import path to @sentry/nestjs/setup in SKILL.md
P1: Add missing Troubleshooting section to error-monitoring.md (11 entries)
P2: Add Deno denoCronIntegration section to crons.md reference
Co-Authored-By: Claude Sonnet 4 (Anthropic)
* refactor(node-sdk): defer NestJS/Next.js to their dedicated skills
Replace inline NestJS setup code in SKILL.md, error-monitoring.md, and
tracing.md with cross-references to sentry-nestjs-sdk. NestJS uses a
separate package (@sentry/nestjs) with NestJS-native decorators, filters,
and GraphQL support — the dedicated skill covers it better.
Update the SDK router to:
- Add NestJS routing priority (rule 3: prefer sentry-nestjs-sdk)
- Remove NestJS from sentry-node-sdk framework list
- Clarify sentry-node-sdk is the fallback for generic Node/Bun/Deno
Update Phase 4 cross-link table to prominently surface both
sentry-nestjs-sdk and sentry-nextjs-sdk as preferred alternatives
when those frameworks are detected.
Co-Authored-By: Claude Sonnet 4 (Anthropic)
* chore: remove review files
Remove .pi/review.md and review.md that were accidentally included in the PR.
Add sentry-android-sdk to all discovery surfaces so the new skill is
reachable through every entry point:
- skills/sentry-sdk-setup/SKILL.md: add Android row to the routing table
(alphabetically between the implicit position before Cocoa) and a
dedicated routing instruction — 'If Android (build.gradle with android
plugin) is detected, use sentry-android-sdk'
- README.md: add sentry-android-sdk to the SDK Setup Wizards table
- AGENTS.md: add sentry-android-sdk to the SDK Skills table
- SKILL_TREE.md: regenerated via scripts/build-skill-tree.sh — 20 skills
scanned, 3 routers, 0 errors
Co-Authored-By: Claude claude.ai/code
Add four deep-dive reference files to the sentry-android-sdk skill bundle:
- logging.md: Structured Logs API (Sentry.logger(), SentryLogParameters, SentryAttributes),
six log levels with OTel severity numbers, Timber bridge integration, Logcat Gradle plugin
auto-instrumentation, beforeSend filtering, auto-attached attributes (user fields note for
8.33.0 PII change), batch processing constants, and a 9-entry troubleshooting table.
- metrics.md: ⚠️ Open Beta — Counter/Distribution/Gauge APIs (no Set type — prominently noted),
MetricsUnit constants reference (custom strings are not supported), SentryMetricsParameters
with custom timestamps and attributes, AndroidMetricsBatchProcessor background-flush behavior,
batch processing constants (5s delay, 10k queue cap), and a 7-entry troubleshooting table.
- crons.md: Four implementation patterns — CheckInUtils.withCheckIn (experimental wrapper),
manual two-step IN_PROGRESS/OK|ERROR lifecycle, heartbeat-only pattern, and WorkManager
wiring (no SDK adapter exists — fully manual). Prominent warning that duration is in seconds
not milliseconds. MonitorSchedule crontab + interval types, MonitorConfig options, global
Cron defaults via SentryOptions.Cron, and an 8-entry limitations/troubleshooting table.
- session-replay.md: API 26+ hard requirement prominently noted with code reference. Both
PIXEL_COPY (stable) and CANVAS (experimental, ignores all masking) screenshot strategies.
Complete SentryReplayOptions reference table. All masking mechanisms: class-based
addMaskViewClass/addUnmaskViewClass, XML sentry_privacy tags, Kotlin View extensions,
and Compose Modifier.sentryReplayMask()/sentryReplayUnmask() — with Compose 1.8+
compatibility note for SDK ≥ 8.33.0. Session lifecycle diagram, network capture config,
debug masking overlay, and a 9-entry troubleshooting table.
All files verified against io.sentry:sentry-android:8.33.0 source and docs.
Co-Authored-By: Claude claude.ai/code
Add three deep-dive reference documents to skills/sentry-android-sdk/references/,
following the same structure as the React Native SDK reference docs:
- error-monitoring.md (26 KB): covers captureException/captureMessage/captureEvent,
automatic crash handling (UncaughtExceptionHandler), ANR detection (watchdog + ANRv2
via ApplicationExitInfo on API 30+), NDK/native crash capture with scope sync, full
scope management API (configureScope/withScope/pushScope), context enrichment (tags,
user, custom contexts, breadcrumbs), beforeSend/beforeBreadcrumb hooks, fingerprinting,
view hierarchy/screenshot attachments, release health, and a 14-entry troubleshooting table.
- tracing.md (28 KB): covers three-tier instrumentation architecture (Gradle plugin,
runtime integrations, manual API), Activity TTID/TTFD, Fragment lifecycle tracing,
OkHttp spans with 9 sub-spans (DNS/TLS/connect phases), SQLite/Room query spans,
Jetpack Compose navigation, File I/O spans, user interaction tracing, slow/frozen
frames, zero-source-change Gradle plugin config, custom spans (startTransaction,
startChild, coroutines with SentryContext), distributed tracing (sentry-trace,
baggage, W3C traceparent), dynamic sampling, and a 14-entry troubleshooting table.
- profiling.md (14 KB): covers continuous/UI profiling (recommended, SDK 8.7+) vs.
legacy transaction-based profiling (30 s hard cap), TRACE vs. MANUAL ProfileLifecycle,
profile chunk model (60 s rolling), the sampling relationship (profilesSampleRate is
relative to tracesSampleRate), mutual exclusivity of the two modes, performance overhead
guidance per device tier, ProGuard mapping upload, and a 13-entry troubleshooting table.
Each file mirrors the React Native reference format: minimum SDK version at top,
Configuration section, Kotlin code examples with Java equivalents, Best Practices
(embedded in context), and a Troubleshooting table. All content sourced from SDK
source analysis (sentry-java 8.33.0) and official docs.
Co-Authored-By: Claude claude-sonnet-4-5 (Anthropic)
Implements the primary wizard skill for the Sentry Android SDK
(io.sentry:sentry-android 8.33.0, Gradle plugin 6.1.0).
The skill follows the established 4-phase wizard pattern from
sentry-react-native-sdk, adapted for the Android ecosystem:
Phase 1 — Detect: bash commands to discover Gradle DSL (Groovy vs KTS),
minSdk level, Kotlin vs Java, and presence of OkHttp, Room, Compose,
Timber, Jetpack Navigation, and Apollo integrations.
Phase 2 — Recommend: opinionated feature matrix (Error Monitoring +
Tracing always; Session Replay for API 26+ user-facing apps; Profiling,
Logging, Metrics as opt-ins).
Phase 3 — Guide: two setup paths — Path A via Gradle plugin (recommended,
handles ProGuard/R8 mapping upload, source context, and bytecode
auto-instrumentation) and Path B for manual setup. Full-featured
SentryAndroid.init() quick reference in both Kotlin and Java. Reference
dispatch table for deep dives into error monitoring, tracing, profiling,
session replay, logging, metrics, crons, and user feedback.
Phase 4 — Cross-Link: detects backend (Go, Python, Ruby, Node) and iOS
counterparts, suggests matching skills, and explains tracePropagationTargets
for distributed trace context.
Key Android-specific content:
- No wizard CLI (unlike React Native) — Gradle plugin is the recommended path
- Bytecode instrumentation via InstrumentationFeature enum (DATABASE,
FILE_IO, OKHTTP, COMPOSE, LOGCAT) — zero source changes required
- Session Replay hard requirement: API 26+ (silent no-op on API 21–25)
- Continuous UI profiling (profileSessionSampleRate) vs legacy transaction
profiling (profilesSampleRate) — mutually exclusive, decision tree included
- AndroidManifest.xml meta-data config as alternative to programmatic init
- 20+ troubleshooting entries covering common ANR, NDK, replay, profiling,
ProGuard, and distributed tracing issues
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Fixes 1 P0 and 7 P1 issues from code review:
P0: Add missing references/ai-monitoring.md — was referenced in two
dispatch tables but did not exist. Covers OpenAI, Vercel AI SDK,
Anthropic, Google GenAI, and LangChain with NestJS-specific examples.
P1 fixes:
- Remove duplicate MonitorConfig import in crons.md (would not compile)
- Fix Prisma listed as auto-enabled in tracing.md — it requires manual
prismaIntegration() setup (consistent with SKILL.md)
- Fix anthropicIntegration → anthropicAIIntegration casing in SKILL.md
- Fix profileLifecycle default from 'manual' to 'trace' in SKILL.md
- Clarify crons.md minimum version: withMonitor() is from @sentry/node
7.76.0+, not @sentry/nestjs (which started at 8.x)
Co-Authored-By: Claude Sonnet 4 (Anthropic)
Add the new NestJS SDK skill to both documentation files so it's
discoverable alongside the existing SDK skills. Listed alphabetically
between Go and Next.js with its key framework support noted:
Express, Fastify, GraphQL, Microservices, and WebSocket.
Co-Authored-By: Claude Sonnet 4 (Anthropic)
Adds skills/sentry-nestjs-sdk/references/crons.md covering all three
check-in approaches for NestJS scheduled jobs:
- @SentryCron decorator paired with @Cron from @nestjs/schedule — the
idiomatic zero-boilerplate path; documents critical decorator ordering
rule (@SentryCron must come after @Cron, i.e. closer to the method)
- Sentry.withMonitor() for manual wrapping — recommended for Bull/BullMQ
processors and other non-@nestjs/schedule contexts where
auto-instrumentation is not supported
- Sentry.captureCheckIn() for full two-step in_progress → ok/error control,
including heartbeat pattern for long-running batch jobs
Also covers MonitorConfig upsert (slug + config auto-creates monitors on
first run), full MonitorConfig field reference, and a troubleshooting table
for the most common issues (decorator order, missing config, Bull/BullMQ,
MISSED/TIMEOUT false positives).
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add skills/sentry-nestjs-sdk/references/metrics.md covering the three
current metric types available in @sentry/nestjs 10.25.0+:
- count() for event occurrences and request tracking
- distribution() for latency/size measurements with percentile support
- gauge() for current-state values like queue depths
NestJS-specific examples include:
- Request counting per controller route with attributes
- Order/database query response-time distributions
- Bull/BullMQ queue depth gauges via @Cron scheduler
- Payment success/failure business event counting
Documents the beforeSendMetric hook, unit string catalogue, attribute
value types (string/number/boolean), the 2 KB per-metric size limit,
and cardinality best practices. Includes a troubleshooting table.
Note: increment() and set() are old alpha API and intentionally omitted.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Adds skills/sentry-nestjs-sdk/references/tracing.md — a comprehensive
tracing reference document covering the full breadth of NestJS tracing
capabilities in @sentry/nestjs.
Key topics documented:
Architecture: explains the two-layer auto-tracing stack — nestIntegration()
(three OTel instrumentations) combined with SentryTracingInterceptor for
HTTP transaction naming. Clarifies the two separate entry points
(@sentry/nestjs vs @sentry/nestjs/setup) and the critical requirement that
instrument.ts must be the very first import in main.ts.
Auto-instrumented features: HTTP requests with parameterized transaction
names, NestJS lifecycle spans (middleware, guards, pipes, interceptors,
filters — all op middleware.nestjs), @OnEvent handlers via
SentryNestEventInstrumentation with forceTransaction semantics, GraphQL,
AMQP/RabbitMQ, Kafka, Redis, and all 7 database drivers.
Manual instrumentation: startSpan / startSpanManual / startInactiveSpan
with full options reference; @SentryTraced decorator (method name → span
name, op parameter); nested span patterns; accessing and modifying the
active span; beforeSendSpan for global span mutation.
Gaps and workarounds: WebSocket gateways (continueTrace + startSpan),
Bull/BullMQ jobs (manual spans in @Process()), TCP/NATS/gRPC transports
(manual), TypeORM/Sequelize (community OTel packages).
Distributed tracing: tracePropagationTargets, continueTrace() +
getTraceData() for non-HTTP channels, manual publisher/worker pattern
for queue-based distributed traces.
Sampling: tracesSampler with SamplingContext shape, inheritance of parent
decisions for distributed traces, dynamic rates by route/op.
Profiling: nodeProfilingIntegration() setup, profileSessionSampleRate
(process-level decision), trace vs manual lifecycle modes, version
pinning requirement.
Follows the established reference format used in sentry-python-sdk.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add skills/sentry-nestjs-sdk/references/logging.md covering all logging
capabilities for the NestJS SDK.
Key content:
- enableLogs: true requirement (without it all Sentry.logger.* are no-ops)
- All six log levels: trace, debug, info, warn, error, fatal
- Sentry.logger.fmt tagged template for parameterized, searchable messages
- NestJS ConsoleLogger bridge via consoleLoggingIntegration({ forceConsole: true })
- Pino integration via pinoIntegration() (SDK 10.18.0+)
- Winston integration via createSentryWinstonTransport()
- beforeSendLog hook for filtering and sanitizing log records
- Automatic log-to-trace correlation (no config needed)
- Decision table and troubleshooting guide
Bunyan is explicitly called out as unsupported.
Follows the same structure as skills/sentry-python-sdk/references/logging.md,
adapted for TypeScript/NestJS idioms and SDK-specific API differences.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add skills/sentry-nestjs-sdk/references/profiling.md covering the full
profiling setup for NestJS applications using @sentry/profiling-node.
The reference documents:
- Installation requirement (version must exactly match @sentry/nestjs)
- Two profiling modes: trace lifecycle (recommended) and manual
- Side-by-side mode comparison table (triggers, coverage, use cases)
- Code examples for instrument.ts integration: trace mode, manual mode,
and production fleet sampling with profileSessionSampleRate
- Technical internals: V8 CpuProfiler, ~100Hz sampling, precompiled
binaries matrix (macOS/Linux/Windows × Node 18-24)
- Environment variables: SENTRY_PROFILER_BINARY_PATH/DIR and
SENTRY_PROFILER_LOGGING_MODE (eager vs lazy)
- Performance overhead guidance and production sampling strategy
- Troubleshooting table for common issues (binary load failures,
version mismatches, high idle CPU, missing profiles)
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add a new workflow skill that guides users through upgrading the Sentry
JavaScript SDK across major versions (v7→v8, v8→v9, v9→v10). Uses a
4-phase wizard flow (Detect → Recommend → Guide → Cross-Link) with
version-specific reference files distilled from official migration docs.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Three P1 bugs and five P2 issues resolved:
P1 — Router step numbering: The PHP detection rule was numbered 6 but
appeared before the fallback step 5, creating sequence 1,2,3,4,6,5.
Corrected to 1,2,3,4,5,6 so LLMs process rules in the right priority order.
P1 — Fabricated \Sentry\withContext() API: This function does not exist
in sentry-php 4.x. Removed from the scope API table, code example, plain
PHP notes, and Octane troubleshooting row. Replaced with the correct
pushScope()/popScope() pattern throughout error-monitoring.md.
P1 — continueTrace() return value discarded: The 'Extracting incoming
trace context' example called continueTrace() without capturing its
TransactionContext return value, then created a fresh context — meaning
the transaction would never be linked to the upstream trace. Fixed to
assign the return value and use it directly, matching the correct pattern
already shown in the queue consumer example.
P2 — error_types default inconsistent: error-monitoring.md said E_ALL;
SKILL.md and the SDK research both say null/error_reporting(). Updated
the reference to error_reporting() for consistency with the SDK source.
P2 — Phantom 'never' value for max_request_body_size: Removed the
undocumented 'never' option. Valid values are none/small/medium/always.
P2 — Package name sentry/sentry-php vs sentry/sentry: All reference file
headers used sentry/sentry-php (the GitHub repo name) instead of
sentry/sentry (the Packagist package). Fixed across crons.md,
error-monitoring.md, logging.md, metrics.md, profiling.md, and tracing.md.
P2 — Tracing header mixed profiling version noise: Simplified the
tracing.md header to just SDK minimums; profiling version details already
live in profiling.md where they belong.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add sentry-php-sdk to all skill registry locations:
- sentry-sdk-setup/SKILL.md: add PHP row to routing table and detection
instruction for composer.json with laravel/framework or symfony/framework-bundle
- SKILL_TREE.md: regenerated via build-skill-tree.sh with PHP entry
- AGENTS.md: add sentry-php-sdk to SDK Skills table
- README.md: add PHP (Laravel, Symfony) to SDK skills listing
- Remove stale .gitkeep from references/ (replaced by actual reference files)
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add two comprehensive reference documents for the PHP SDK skill:
- references/error-monitoring.md — covers all capture APIs (captureException,
captureMessage, captureEvent, captureLastError), Hub/Scope management
(configureScope, withScope, withContext, push/pop), context enrichment (tags,
UserDataBag, Breadcrumb TYPE_* and LEVEL_* constants, setContext), before_send
and before_breadcrumb hooks with exact callback signatures, EventHint and
ExceptionMechanism for handled/unhandled distinction, exception chaining,
fingerprinting via Scope and before_send, and framework-specific integration
notes for plain PHP, Laravel, and Symfony. Includes a 5-row troubleshooting
table.
- references/tracing.md — covers traces_sample_rate / traces_sampler config
(including Symfony service-factory pattern for closures), the full custom
span API (TransactionContext, SpanContext, startChild, Sentry\trace() helper,
safe manual pattern), auto-instrumentation matrix for Laravel (15+ operations)
and Symfony (12+ operations), distributed tracing with sentry-trace + baggage
headers (Guzzle middleware, continueTrace(), queue worker pattern), HTML meta
tag injection for frontend/backend stitching, profiling with Excimer extension,
a span ops cheat-sheet table, and an 8-row troubleshooting table.
Both files mirror the structure of the sentry-python-sdk reference files
(config table → code examples → best practices / framework notes → troubleshooting).
Co-Authored-By: claude-sonnet-4-5 <claude-sonnet-4-5@anthropic.com>
Adds two comprehensive framework-specific reference files for the sentry-php-sdk skill:
- references/laravel.md (~496 lines): Full deep dive covering installation (Laravel 11+ vs 10 exception handler patterns), all config/sentry.php options including breadcrumb and tracing sub-arrays with ENV variable names, auto-instrumented operations table (11+ operations), filesystem disk opt-in instrumentation, auto-registered middleware, both log channel drivers (sentry vs sentry_logs), full queue distributed tracing with payload keys, sentryMonitor() macro with all parameters, Artisan commands, closures-and-config-cache gotcha with static callable workaround, Lumen support, Laravel Octane scope isolation warning, and Pennant feature flags integration.
- references/symfony.md (~531 lines): Full deep dive covering Flex auto-registration vs manual bundle setup, complete sentry.yaml schema with all top-level/options/messenger/tracing sub-nodes, Symfony-specific defaults (kernel.environment, PrettyVersions release, in_app_exclude auto-includes), bundle-level options table, DIC callable pattern with full service factory example (critical Symfony gotcha — YAML can't hold closures), auto-instrumented operations table (Doctrine DBAL, Twig, Cache, HTTP Client), structured logs via LogsHandler Monolog service, traditional Monolog handler with buffer support, Messenger integration (error-capture only, no tracing spans), cron monitoring using base PHP SDK functions, console command tracing config, all auto-registered event listeners, and automatic distributed tracing header handling.
These are loaded conditionally by the main SKILL.md when Laravel or Symfony is detected in the project's composer.json.
Co-Authored-By: Claude claude.ai/code
Add four reference files to skills/sentry-php-sdk/references/ covering the
full set of PHP SDK observability features:
- profiling.md: Excimer extension prerequisites, version requirements per
framework (PHP ≥3.15, Laravel ≥3.3, Symfony ≥4.7), profiles_sample_rate
semantics (relative to traces_sample_rate), FastCGI latency mitigation,
and Relay proxy setup
- logging.md: Structured Sentry Logs feature (enable_logs: true), direct
logger API (\Sentry\logger()), Monolog bridge, Laravel sentry_logs channel
setup via .env and config/logging.php, Symfony LogsHandler + monolog.yaml
wiring, before_send_log filtering (closure for PHP/Laravel, service ID for
Symfony), auto-added attributes table, flush semantics per runtime context
- metrics.md: TraceMetrics API (count/distribution/gauge), deprecation notice
for old \Sentry\metrics() API, unit enum reference, ring buffer flush
behavior (cap 1000), before_send_metric filtering, auto-added attributes,
Symfony YAML configuration
- crons.md: withMonitor() wrapper, manual captureCheckIn() pattern, heartbeat
pattern, programmatic MonitorConfig upsert (crontab + interval schedules),
Laravel sentryMonitor() macro with full parameter reference, Symfony direct
SDK usage (no framework-specific integration), CheckInStatus/MonitorSchedule
references, rate limits (6/min per monitor-environment), alerts setup
All files follow the structure established by the sentry-python-sdk references.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
Add the primary wizard skill for PHP SDK setup covering plain PHP, Laravel, and
Symfony in a single skill following the one-skill-per-language pattern used by
Python, Ruby, and .NET skills.
The wizard follows the standard 4-phase structure:
- Phase 1 (Detect): composer.json inspection, filesystem markers (artisan /
bin/console), framework and queue detection
- Phase 2 (Recommend): concrete proposal matrix for Error Monitoring, Tracing,
Profiling, Logging, Metrics, and Crons
- Phase 3 (Guide): framework-branched installation and initialization — plain
PHP uses \Sentry\init(), Laravel uses artisan sentry:publish + Integration::handles(),
Symfony uses YAML bundle config
- Phase 4 (Cross-Link): detects companion frontend (React, Svelte, Vue) and
suggests the matching frontend SDK skill
Key design decisions:
- No wizard CLI (php/laravel/symfony not supported by @sentry/wizard)
- Laravel artisan sentry:publish --dsn= documented as the closest equivalent
- Profiling clearly marked as requiring the excimer PECL extension (Linux/macOS only)
- Metrics marked as beta using the TraceMetrics API
- Framework-specific deep dives deferred to references/laravel.md and references/symfony.md
Creates the references/ directory (populated in subsequent commits).
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
When an agent matches a skill via a router but doesn't have it installed
locally, the router now instructs it to fetch the SKILL.md directly from
the GitHub repo using the raw content URL pattern:
https://raw.githubusercontent.com/getsentry/sentry-for-ai/main/skills/<name>/SKILL.md
This ensures agents that only have the three router skills installed can
still access the full library of SDK, workflow, and feature skills
on-demand without requiring a full local clone. The Skill Tree is
referenced as the source of truth for valid skill names and paths.
Updated all three routers:
- sentry-sdk-setup (SDK setup wizard routing)
- sentry-workflow (issue fixing, code review routing)
- sentry-feature-setup (AI monitoring, OTel, alerts routing)
Co-Authored-By: Claude (Anthropic)
* fix(skills): mark wizard as user-run-only, add manual setup fallback
The Sentry wizard CLI requires interactive browser-based login and
org/project selection prompts that AI agents cannot handle. Updated all
SDK skills that reference the wizard to present it inside a blockquote
telling the user to run the command themselves in their terminal.
If the user skips the wizard, the agent proceeds with full manual setup.
Updated skills:
- sentry-nextjs-sdk
- sentry-svelte-sdk
- sentry-react-native-sdk
- sentry-dotnet-sdk
- sentry-cocoa-sdk
- sentry-sdk-skill-creator (template + philosophy reference)
Co-Authored-By: Claude (Anthropic Claude Sonnet 4)
* fix(skills): address reviewer findings for wizard guidance
- react-features.md: add interactive-login warning to source maps wizard
reference (P1 — agent would hang on browser auth)
- cocoa SKILL.md: align 'once it finishes' copy with other skills to
point to Verification instead of vague 'continue with configuration'
Co-Authored-By: Claude (Anthropic Claude Sonnet 4)
Extract validate-skill-tree from the warden workflow into a dedicated
.github/workflows/validate-skill-tree.yml. Keeps concerns separate —
warden handles AI code review, skill tree validation handles structural
integrity. Both trigger on the same PR events but run independently.
Use ${ARRAY[@]+"${ARRAY[@]}"} pattern for all array expansions that
could be empty (category arrays, errors array, function parameters).
Bash 3.2 with set -u treats "${EMPTY[@]}" as an unbound variable error,
while bash 4+ handles it gracefully. The +"..." syntax expands to nothing
when the array is unset/empty, avoiding the crash.
Also fix AGENTS.md claiming CI only runs on skills/** changes — the
validate-skill-tree job runs on all PRs (it's fast enough not to need
path filtering).
Adds a parallel CI job that runs `./scripts/build-skill-tree.sh --check`
on every PR. The job checks out the repo with minimal permissions
(contents: read) and fails if SKILL_TREE.md is stale or any skill
frontmatter/breadcrumb/router-table validation errors are found.
Running it as a separate job (rather than a step in the warden review
job) keeps concerns isolated and lets both jobs run in parallel.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Documents the router pattern that keeps agent startup metadata lean
(~300 tokens vs ~1,600+ as the skill library grows). Covers:
- How the three router skills (sentry-sdk-setup, sentry-workflow,
sentry-feature-setup) gate access to hidden child skills via
disable-model-invocation
- Category taxonomy with responsible routers
- Step-by-step checklist for adding a new skill (frontmatter fields,
breadcrumb, router table update, build script)
- Guidance on splitting categories once they exceed ~10 skills
- Reference to scripts/build-skill-tree.sh for local validation and
its --check flag used in CI
This gives contributors (human and AI) a single authoritative source
for skill tree conventions without needing to reverse-engineer the
frontmatter or ask questions.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
Adds scripts/build-skill-tree.sh — a bash-only script that scans
all skills/*/SKILL.md files, regenerates SKILL_TREE.md from live
frontmatter data, and validates the entire skill hierarchy.
What the script does:
1. Scan — finds all SKILL.md files via find, parses YAML frontmatter
(name, description, category, parent, role, disable-model-invocation)
using awk. No external dependencies beyond standard Unix tools.
2. Categorize — groups skills by category field, identifies routers
by role: router.
3. Generate — rebuilds SKILL_TREE.md with Quick Navigation table,
per-category skill tables (SDK Setup, Workflow, Feature Setup,
Internal), and short column values extracted from descriptions.
4. Validate — checks every rule without stopping on first failure:
- Non-router/non-internal skills must have category, parent, and
disable-model-invocation: true
- Internal skills must have disable-model-invocation: true
- Every skill's parent must exist and have role: router
- Each skill must appear in its router's SKILL.md
- All breadcrumb .md links must resolve to real files
- Warns on unknown categories
5. Stale check — diffs generated vs existing SKILL_TREE.md; writes
file unless --check is passed (check-only mode for CI).
Uses a temp-directory pattern for per-skill data storage instead of
bash 4 associative arrays, keeping it compatible with macOS bash 3.2.
Also updates SKILL_TREE.md to match the script's generated output
(column values are now extracted from descriptions via sed, ordering
follows find | sort alphabetical).
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Creates a flat sitemap at the repo root that gives any agent an instant
overview of the full skill structure. The file contains:
- Quick navigation table mapping user intent to the three router skills
(sentry-sdk-setup, sentry-workflow, sentry-feature-setup)
- Four categorized tables covering all 16 skills: SDK Setup (9 platforms),
Workflow (3 skills), Feature Setup (3 skills), and Internal (1 skill)
- Every skill name and path is a clickable markdown link
- Kept under 1000 tokens as specified
This file serves as the entry point agents use to locate the right skill
before diving into individual SKILL.md files. It will later be generated
automatically by the build script; this is the hand-authored initial version.
Co-Authored-By: Claude Sonnet 4.6 (Anthropic)
Extends the skill-tree navigation pattern (already applied to SDK skills)
to the remaining workflow, feature-setup, and internal skills.
Each file receives three new frontmatter fields:
- category: workflow | feature-setup | internal
- parent: router skill name (omitted for internal/sentry-sdk-skill-creator)
- disable-model-invocation: true
And a breadcrumb blockquote immediately after the closing --- for
contextual navigation:
Workflow skills (parent: sentry-workflow):
sentry-code-review, sentry-pr-code-review, sentry-fix-issues
Feature-setup skills (parent: sentry-feature-setup):
sentry-setup-ai-monitoring, sentry-otel-exporter-setup, sentry-create-alert
Internal skills (no parent router):
sentry-sdk-skill-creator → breadcrumb links to SKILL_TREE.md only
No existing skill content was modified — pure additive changes.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Add category, parent, and disable-model-invocation fields to the YAML
frontmatter of all 9 SDK skill files, and insert a breadcrumb navigation
line as the first body element after the closing ---.
Each skill now declares:
category: sdk-setup
parent: sentry-sdk-setup
disable-model-invocation: true
And opens with a breadcrumb blockquote:
> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > <Platform> SDK
This establishes the skill tree hierarchy for the sdk-setup category,
enabling routers and tooling to discover parent/child relationships and
preventing these implementation skills from being invoked directly by
the model without going through the sentry-sdk-setup router.
No existing skill content was modified — only additive changes.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic)
Introduce three new router-role skills that act as entry points for common
Sentry tasks, routing agents to the appropriate specialized skill based on
user intent and detected platform context.
- sentry-sdk-setup: detects project platform from files (package.json,
go.mod, Gemfile, *.xcodeproj, etc.) and maps to one of 9 SDK skills
(Cocoa, .NET, Go, Next.js, Python, React Native, React, Ruby, Svelte).
Includes priority rules for Next.js over React and React Native over React,
with a fallback to docs.sentry.io/platforms/ for unmatched platforms.
- sentry-workflow: routes debugging and code review tasks to sentry-fix-issues
(MCP-based production debugging), sentry-code-review (sentry[bot] PR
comments), or sentry-pr-code-review (Seer Bug Prediction reviews).
- sentry-feature-setup: routes feature configuration requests to
sentry-setup-ai-monitoring (LLM/AI SDK instrumentation),
sentry-otel-exporter-setup (OTel Collector pipelines), or
sentry-create-alert (workflow engine alerts and notifications).
All three skills use role: router in frontmatter and include breadcrumb
navigation back to SKILL_TREE.md.
Co-Authored-By: Claude Sonnet 4.5 (Anthropic AI assistant)
Restructure the README around what users can actually do with the
plugin rather than listing technical components. Opens with the core
value prop — your AI assistant knows code, this teaches it Sentry — then
shows real examples for each use case before diving into skill tables.
Drops the plugin structure tree (internal detail) and streamlines
installation instructions. Adds a contributing section pointing to the
agent skills spec and the sdk-skill-creator skill.
Co-Authored-By: Claude (Anthropic)
Update documentation to reflect the full skill catalog ported from
sentry-agent-skills. Skills are now organized into four categories:
- SDK bundles (9): full platform setup wizards with reference docs
- Setup skills (2): AI monitoring, OTel exporter
- Workflow skills (4): code review, PR review, fix issues, create alerts
- Authoring skills (1): SDK skill creator
Also adds scripts/generate-skill-list.sh from sentry-agent-skills for
generating skill lists from SKILL.md frontmatter.
Co-Authored-By: Claude (Anthropic)
Daniel Griesser