@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/nestjs/tracing.md

@@ -0,0 +1,762 @@
+# Tracing — Sentry NestJS SDK
+
+> Minimum SDK: `@sentry/nestjs` 8.x (requires Node >= 18.0.0; 18.19.0+ or 19.9.0+
+> recommended)
+
+## Configuration
+
+| Option                     | Type                   | Default     | Purpose                                                                                      |
+| -------------------------- | ---------------------- | ----------- | -------------------------------------------------------------------------------------------- |
+| `tracesSampleRate`         | `number`               | `undefined` | Fraction of transactions to trace (0.0–1.0); omit to disable tracing                         |
+| `tracesSampler`            | `function`             | `undefined` | Per-transaction sampling function; overrides `tracesSampleRate`                              |
+| `tracePropagationTargets`  | `(string \| RegExp)[]` | all origins | URLs/patterns to inject `sentry-trace` / `baggage` headers into                              |
+| `profileSessionSampleRate` | `number`               | `undefined` | Fraction of **process sessions** to profile (0.0–1.0); decided once at init                  |
+| `profileLifecycle`         | `'trace' \| 'manual'`  | `'trace'`   | `'trace'` = auto start/stop with spans; `'manual'` = call `startProfiler()`/`stopProfiler()` |
+| `beforeSendSpan`           | `function`             | `undefined` | Callback to mutate or drop individual spans before sending                                   |
+| `skipOpenTelemetrySetup`   | `boolean`              | `false`     | Skip automatic OTel provider setup (for custom OTel configurations)                          |
+| `strictTraceContinuation`  | `boolean`              | `false`     | Only continue traces from same Sentry org (v10+)                                             |
+
+## Architecture
+
+`@sentry/nestjs` is a thin wrapper over `@sentry/node`. Its tracing stack:
+
+```
+@sentry/nestjs
+  ├── Sentry.init() → auto-adds nestIntegration() to default integrations
+  ├── nestIntegration() → registers 3 OTel instrumentations:
+  │     ├── @opentelemetry/instrumentation-nestjs-core   → app_creation, request_context, handler spans
+  │     ├── SentryNestInstrumentation                    → middleware, guard, pipe, interceptor, filter spans
+  │     └── SentryNestEventInstrumentation               → @OnEvent handler spans
+  ├── SentryModule.forRoot() → registers SentryTracingInterceptor globally
+  ├── SentryTracingInterceptor → sets HTTP transaction names from Express/Fastify route patterns
+  └── SentryGlobalFilter → captures unhandled exceptions (HTTP, GraphQL, RPC)
+```
+
+Sentry is the OpenTelemetry provider — any OTel instrumentation automatically flows into
+Sentry.
+
+## Code Examples
+
+### Enable tracing
+
+```typescript
+// instrument.ts — must be loaded FIRST in main.ts, before NestJS imports
+import * as Sentry from "@sentry/nestjs";
+
+Sentry.init({
+  dsn: "https://<key>@<org>.ingest.sentry.io/<project>",
+  tracesSampleRate: 1.0, // 1.0 = 100% of transactions; reduce in production
+});
+```
+
+```typescript
+// main.ts
+import "./instrument"; // MUST be first — before @nestjs/core or any module
+import { NestFactory } from "@nestjs/core";
+import { AppModule } from "./app.module";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+```typescript
+// app.module.ts — two distinct entry points
+import { Module } from "@nestjs/common";
+import { SentryModule } from "@sentry/nestjs/setup"; // /setup entry point
+import { APP_FILTER } from "@nestjs/core";
+import { SentryGlobalFilter } from "@sentry/nestjs/setup"; // /setup entry point
+
+@Module({
+  imports: [SentryModule.forRoot()], // registers SentryTracingInterceptor globally
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: SentryGlobalFilter, // captures unhandled HTTP/GraphQL/RPC exceptions
+    },
+  ],
+})
+export class AppModule {}
+```
+
+> **`@sentry/nestjs` vs `@sentry/nestjs/setup` — two separate entry points:**
+>
+> - `@sentry/nestjs` — `Sentry.init()`, decorators, span APIs, all `@sentry/node`
+>   re-exports
+> - `@sentry/nestjs/setup` — `SentryModule`, `SentryTracingInterceptor`,
+>   `SentryGlobalFilter`
+
+### HTTP request auto-tracing
+
+HTTP tracing requires no extra code.
+Two mechanisms work together:
+
+1. **`nestIntegration`** (via `@opentelemetry/instrumentation-nestjs-core`) creates
+   spans:
+   - `app_creation.nestjs` — NestJS bootstrap
+   - `request_context.nestjs` — overall request handling
+   - `handler.nestjs` — each route handler
+
+2. **`SentryTracingInterceptor`** (registered via `SentryModule.forRoot()`) sets the
+   transaction name from the parameterized route:
+   - Express: `GET /users/:id` (from `req.route.path`)
+   - Fastify: `GET /users/:id` (from `req.routeOptions.url`)
+
+**Typical span tree for a request:**
+
+```
+GET /api/users/:id  (transaction name)
+  └── request_context.nestjs
+        ├── AuthGuard              (middleware.nestjs)
+        ├── ParseIntPipe           (middleware.nestjs)
+        ├── LoggingInterceptor     (middleware.nestjs — before route)
+        │     └── handler.nestjs
+        │           └── db query span (auto from pg/mysql/etc.)
+        └── LoggingInterceptor - Interceptors - After Route  (middleware.nestjs)
+```
+
+> All NestJS lifecycle spans (middleware, guards, pipes, interceptors, filters) share op
+> `middleware.nestjs`.
+
+### `@SentryTraced` decorator
+
+```typescript
+import { SentryTraced } from "@sentry/nestjs";
+import { Injectable } from "@nestjs/common";
+
+@Injectable()
+export class OrderService {
+  @SentryTraced("db.query") // op="db.query", name="findOrder" (method name)
+  async findOrder(id: string) {
+    return this.orderRepo.findOne({ where: { id } });
+  }
+
+  @SentryTraced() // op="function" (default)
+  async processOrder(data: CreateOrderDto) {
+    return this.process(data);
+  }
+}
+```
+
+- Span `name` = method name (e.g., `"findOrder"`)
+- Span `op` = decorator argument, defaults to `"function"`
+- Works with both sync and async methods
+- Copies `reflect-metadata` keys — NestJS DI compatibility preserved
+
+### Custom spans with `startSpan` (auto-ends)
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+import { Injectable } from "@nestjs/common";
+
+@Injectable()
+export class PaymentService {
+  async charge(userId: string, amount: number) {
+    return Sentry.startSpan({ name: "charge-card", op: "payment.charge" }, async (span) => {
+      span.setAttribute("payment.userId", userId);
+      span.setAttribute("payment.amount", amount);
+      const result = await this.stripeService.charge(userId, amount);
+      span.setAttribute("payment.transactionId", result.id);
+      return result;
+    });
+  }
+}
+```
+
+### `startSpanManual` (callback-style, must call `span.end()`)
+
+```typescript
+return Sentry.startSpanManual({ name: "legacy-callback", op: "function" }, (span) => {
+  legacyLib.doWork((err, result) => {
+    span.setStatus({ code: err ? 2 : 1 }); // 1=OK, 2=ERROR
+    span.end();
+    callback(err, result);
+  });
+});
+```
+
+### `startInactiveSpan` (detached, no auto-parent)
+
+```typescript
+const span = Sentry.startInactiveSpan({ name: "background-index", op: "task" });
+// ... do work independently ...
+span.end();
+```
+
+### Span options reference
+
+| Option             | Type                                          | Description                                                             |
+| ------------------ | --------------------------------------------- | ----------------------------------------------------------------------- |
+| `name`             | `string`                                      | **Required.** Span name                                                 |
+| `op`               | `string`                                      | Operation type (`db`, `http.client`, `function`, `queue.process`, etc.) |
+| `attributes`       | `Record<string, string \| number \| boolean>` | Key-value metadata                                                      |
+| `startTime`        | `number`                                      | Custom start timestamp (Unix seconds)                                   |
+| `parentSpan`       | `Span`                                        | Explicit parent (overrides auto-parent from context)                    |
+| `onlyIfParent`     | `boolean`                                     | Skip creating span if no active parent exists                           |
+| `forceTransaction` | `boolean`                                     | Display as root transaction in Sentry UI                                |
+
+### Accessing and modifying the active span
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+// Read active span
+const span = Sentry.getActiveSpan();
+if (span) {
+  span.setAttribute("user.id", userId);
+  span.setAttributes({ "order.type": "subscription", "order.currency": "USD" });
+}
+
+// Update span name (v8.47.0+)
+if (span) Sentry.updateSpanName(span, "Refined Operation Name");
+
+// Span status codes: 0=UNSET, 1=OK, 2=ERROR
+span?.setStatus({ code: 2 });
+```
+
+### Nested spans
+
+```typescript
+return Sentry.startSpan({ name: "process-checkout", op: "business.logic" }, async () => {
+  const cart = await Sentry.startSpan({ name: "fetch-cart", op: "db.query" }, () =>
+    this.cartRepo.findById(cartId),
+  );
+
+  await Sentry.startSpan({ name: "apply-discount", op: "function" }, () =>
+    this.discountService.apply(cart),
+  );
+
+  return Sentry.startSpan({ name: "create-order", op: "db.query" }, () =>
+    this.orderRepo.create(cart),
+  );
+});
+```
+
+### Modify all spans globally (`beforeSendSpan`)
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  beforeSendSpan(span) {
+    if (span.op === "db.query" && span.description?.includes("password")) {
+      span.description = "[REDACTED]";
+    }
+    // return null to drop the span entirely
+    return span;
+  },
+});
+```
+
+### Dynamic sampling with `tracesSampler`
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracesSampler: ({ name, attributes, parentSampled }) => {
+    // Drop health check endpoints
+    if (/\/(health|ping|readiness|liveness)/.test(name)) return 0;
+
+    // Always capture authentication flows
+    if (name.includes("/auth/")) return 1;
+
+    // Inherit parent's sampling decision (distributed tracing)
+    if (parentSampled !== undefined) return parentSampled;
+
+    // Default 10%
+    return 0.1;
+  },
+});
+```
+
+### Event emitter auto-tracing (`@OnEvent`)
+
+Requires `@nestjs/event-emitter` >= 2.0.0. Handlers are auto-wrapped — no code changes
+needed:
+
+```typescript
+import { OnEvent } from "@nestjs/event-emitter";
+import { Injectable } from "@nestjs/common";
+
+@Injectable()
+export class NotificationListener {
+  @OnEvent("user.created")
+  async handleUserCreated(payload: UserCreatedEvent) {
+    // Auto span: name="event user.created", op="event.nestjs"
+    // forceTransaction: true → appears as separate root transaction in Sentry UI
+    // Unhandled exceptions auto-captured (they bypass SentryGlobalFilter)
+    await this.emailService.sendWelcome(payload.userId);
+  }
+
+  @OnEvent("user.created")
+  @OnEvent("user.updated")
+  async handleUserChange(payload: UserEvent) {
+    // Span: name="event user.created|user.updated"
+  }
+
+  @OnEvent("order.*") // wildcards supported
+  async handleOrder(payload: OrderEvent) {
+    await this.orderService.process(payload);
+  }
+}
+```
+
+> **Note:** Event spans always use `forceTransaction: true` — they appear as isolated
+> root transactions, not child spans of the HTTP request that emitted the event.
+
+### GraphQL resolver tracing
+
+GraphQL is auto-traced via `graphqlIntegration` (enabled by default).
+No configuration needed:
+
+```typescript
+// Spans auto-created for:
+// - Query/mutation/subscription execution
+// - Individual resolver fields
+
+// SentryGlobalFilter handles GraphQL exceptions correctly:
+// - HttpException → rethrown without capturing (expected)
+// - All other errors → captured then rethrown (GraphQL ExternalExceptionFilter needs the rethrow)
+```
+
+### Microservices — transport support matrix
+
+| Transport       | Auto-traced? | Mechanism                                                                                  |
+| --------------- | ------------ | ------------------------------------------------------------------------------------------ |
+| AMQP / RabbitMQ | ✅           | `amqplibIntegration` — `amqp.publish` + `amqp.process` spans, headers auto-injected        |
+| Kafka (KafkaJS) | ✅           | `kafkaIntegration` — `kafka.send` + `kafka.process` spans, trace context in record headers |
+| Redis pub/sub   | ⚠️ Partial   | `redisIntegration` traces Redis commands only                                              |
+| TCP             | ❌           | No OTel instrumentation                                                                    |
+| NATS            | ❌           | Community OTel NATS package needed                                                         |
+| gRPC            | ❌           | Community OTel gRPC package needed                                                         |
+
+### WebSocket gateway tracing (manual)
+
+No dedicated WebSocket auto-tracing exists.
+`SentryTracingInterceptor` only handles HTTP contexts:
+
+```typescript
+import { SubscribeMessage, WebSocketGateway, MessageBody } from "@nestjs/websockets";
+import * as Sentry from "@sentry/nestjs";
+
+@WebSocketGateway(3001)
+export class ChatGateway {
+  @SubscribeMessage("message")
+  async handleMessage(@MessageBody() payload: { data: any; _sentry?: any }) {
+    const { sentryTrace, baggage } = payload._sentry ?? {};
+
+    return Sentry.continueTrace({ sentryTrace, baggage }, () =>
+      Sentry.startSpan(
+        {
+          name: "ws.chat.message",
+          op: "websocket.server",
+          forceTransaction: true,
+        },
+        async () => this.chatService.process(payload.data),
+      ),
+    );
+  }
+}
+
+// Client: attach trace context to every message
+const traceData = Sentry.getTraceData();
+socket.emit("message", {
+  data: payload,
+  _sentry: {
+    sentryTrace: traceData["sentry-trace"],
+    baggage: traceData["baggage"],
+  },
+});
+```
+
+### Bull/BullMQ job tracing (manual)
+
+No dedicated Bull integration — use manual spans in `@Process()` handlers.
+Always wrap with `withIsolationScope` to prevent scope leakage between concurrent jobs.
+
+#### BullMQ with `WorkerHost` (recommended for `@nestjs/bullmq`)
+
+```typescript
+import { Processor, WorkerHost } from "@nestjs/bullmq";
+import { Job } from "bullmq";
+import * as Sentry from "@sentry/nestjs";
+
+@Processor("email")
+export class EmailProcessor extends WorkerHost {
+  async process(job: Job) {
+    return Sentry.withIsolationScope(() =>
+      Sentry.startSpan(
+        {
+          name: `email ${job.name}`,
+          op: "queue.process",
+          forceTransaction: true,
+          attributes: {
+            "messaging.system": "bullmq",
+            "messaging.destination": "email",
+            "messaging.message.id": job.id ?? "unknown",
+            "job.name": job.name,
+            "job.attemptsMade": job.attemptsMade,
+          },
+        },
+        async () => {
+          await this.emailService.sendWelcomeEmail(job.data.userId);
+        },
+      ),
+    );
+  }
+}
+```
+
+> **Why `withIsolationScope`?** BullMQ processes jobs concurrently in the same process.
+> Without isolation, `setTag`, `setUser`, and breadcrumbs leak between concurrent jobs.
+
+#### Bull with `@Process()` decorator
+
+```typescript
+import { Process, Processor } from "@nestjs/bull";
+import { Job } from "bull";
+import * as Sentry from "@sentry/nestjs";
+
+@Processor("email")
+export class EmailProcessor {
+  @Process("send-welcome")
+  async handle(job: Job<{ userId: string; _sentry?: Record<string, string> }>) {
+    const { _sentry, ...data } = job.data;
+
+    return Sentry.withIsolationScope(() =>
+      Sentry.continueTrace(
+        {
+          sentryTrace: _sentry?.["sentry-trace"],
+          baggage: _sentry?.["baggage"],
+        },
+        () =>
+          Sentry.startSpan(
+            {
+              name: "email.send-welcome",
+              op: "queue.process",
+              forceTransaction: true,
+            },
+            async (span) => {
+              span.setAttribute("job.id", job.id.toString());
+              span.setAttribute("job.attemptsMade", job.attemptsMade);
+              await this.emailService.sendWelcomeEmail(data.userId);
+            },
+          ),
+      ),
+    );
+  }
+}
+```
+
+#### Publisher — attach trace context to job data
+
+```typescript
+async queueWelcomeEmail(userId: string) {
+  return Sentry.startSpan({ name: "email.queue", op: "queue.publish" }, () => {
+    const traceData = Sentry.getTraceData();
+    return this.emailQueue.add("send-welcome", { userId, _sentry: traceData });
+  });
+}
+```
+
+### Kafka / NATS microservice handler tracing
+
+Kafka messages are auto-instrumented by `kafkaIntegration` (KafkaJS), but NATS and other
+transports require manual spans.
+For consistency, wrapping `@EventPattern()` and `@MessagePattern()` handlers with
+explicit spans is recommended for all transports:
+
+```typescript
+import { Controller } from "@nestjs/common";
+import { EventPattern, MessagePattern, Payload } from "@nestjs/microservices";
+import * as Sentry from "@sentry/nestjs";
+
+@Controller()
+export class OrderController {
+  @EventPattern("order.created")
+  async handleOrderCreated(@Payload() data: OrderEvent) {
+    return Sentry.startSpan(
+      { name: "handleOrderCreated", op: "kafka", forceTransaction: true },
+      async () => {
+        await this.orderService.processCreated(data);
+      },
+    );
+  }
+
+  @MessagePattern("order.get")
+  async getOrder(@Payload() data: { id: string }) {
+    return Sentry.startSpan({ name: "getOrder", op: "rpc" }, async () => {
+      return this.orderService.findById(data.id);
+    });
+  }
+}
+```
+
+> Use `forceTransaction: true` for event handlers that should appear as root
+> transactions in Sentry UI.
+
+### Distributed tracing between services
+
+HTTP services propagate `sentry-trace` and `baggage` headers automatically.
+For custom channels:
+
+```typescript
+// Service A — publish with trace context
+async sendToQueue(data: any) {
+  return Sentry.startSpan({ name: "queue.publish", op: "queue.publish" }, () => {
+    const traceData = Sentry.getTraceData();
+    return this.queue.send({
+      payload: data,
+      headers: {
+        "sentry-trace": traceData["sentry-trace"],
+        "baggage": traceData["baggage"],
+      },
+    });
+  });
+}
+
+// Service B — continue trace from received message
+async handleMessage(message: any) {
+  return Sentry.continueTrace(
+    {
+      sentryTrace: message.headers["sentry-trace"],
+      baggage: message.headers["baggage"],
+    },
+    () => Sentry.startSpan(
+      { name: "queue.process", op: "queue.process" },
+      () => this.processPayload(message.payload)
+    )
+  );
+}
+```
+
+### Limit trace propagation targets
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  tracePropagationTargets: [
+    "localhost",
+    "https://api.internal.example.com",
+    /^https:\/\/microservice-[a-z]+\.internal\./,
+    // tracePropagationTargets: []  → disable outgoing propagation entirely
+  ],
+});
+```
+
+### Database auto-instrumentation
+
+| Driver / ORM         | Auto-enabled | Notes                                                                              |
+| -------------------- | ------------ | ---------------------------------------------------------------------------------- |
+| PostgreSQL (`pg`)    | ✅           | `postgresIntegration`                                                              |
+| MySQL                | ✅           | `mysqlIntegration`                                                                 |
+| MySQL2               | ✅           | `mysql2Integration`                                                                |
+| MongoDB              | ✅           | `mongoIntegration`                                                                 |
+| Mongoose             | ✅           | `mongooseIntegration`                                                              |
+| Prisma               | ⚠️ Manual    | `prismaIntegration` — add explicitly: `integrations: [Sentry.prismaIntegration()]` |
+| SQL Server (Tedious) | ✅           | `tediousIntegration`                                                               |
+| Knex                 | ❌           | Must add manually                                                                  |
+| TypeORM              | ❌           | Use `opentelemetry-instrumentation-typeorm` community package                      |
+| Sequelize            | ❌           | No known integration                                                               |
+
+```typescript
+// Knex — must add explicitly:
+import { knexIntegration } from "@sentry/node";
+Sentry.init({ dsn: "YOUR_DSN", integrations: [knexIntegration()] });
+```
+
+### Redis auto-instrumentation
+
+`redisIntegration` is auto-enabled — traces all `ioredis` and `node-redis` commands:
+
+```
+name: "SET user:123"   op: "db.redis"
+name: "GET session:abc"   op: "db.redis"
+```
+
+No configuration needed.
+
+### Using OTel APIs directly
+
+Since Sentry is the OTel provider, OTel spans automatically appear in Sentry:
+
+```typescript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-service", "1.0.0");
+
+tracer.startActiveSpan("process-event", (span) => {
+  try {
+    processEvent();
+    span.setStatus({ code: SpanStatusCode.OK });
+  } catch (e) {
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw e;
+  } finally {
+    span.end();
+  }
+});
+// → Appears in Sentry automatically, no extra config
+```
+
+Third-party OTel instrumentations also work without any Sentry-specific setup:
+
+```typescript
+// e.g., community TypeORM OTel instrumentation
+import "opentelemetry-instrumentation-typeorm";
+// → TypeORM query spans appear in Sentry automatically
+```
+
+### Disable or customize integrations
+
+```typescript
+Sentry.init({
+  // Disable a specific integration:
+  integrations: (defaults) => defaults.filter((i) => i.name !== "Kafka"),
+});
+
+// Override integration config:
+Sentry.init({
+  integrations: [Sentry.breadcrumbsIntegration({ console: false })],
+});
+
+// Add non-default integration:
+Sentry.addIntegration(Sentry.captureConsoleIntegration());
+
+// Disable all defaults (uncommon):
+Sentry.init({ defaultIntegrations: false });
+```
+
+### Profiling with `@sentry/profiling-node`
+
+```bash
+# Version must exactly match @sentry/nestjs
+npm install @sentry/profiling-node
+```
+
+```typescript
+// instrument.ts
+import * as Sentry from "@sentry/nestjs";
+const { nodeProfilingIntegration } = require("@sentry/profiling-node");
+
+Sentry.init({
+  dsn: "YOUR_DSN",
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: 1.0,
+  profileSessionSampleRate: 1.0, // profile 100% of process sessions
+  profileLifecycle: "trace", // auto start/stop with spans (recommended)
+});
+```
+
+| `profileLifecycle`  | Start                             | Stop                             | Use case                        |
+| ------------------- | --------------------------------- | -------------------------------- | ------------------------------- |
+| `"trace"` (default) | First active span                 | Last span ends                   | General profiling — zero config |
+| `"manual"`          | `Sentry.profiler.startProfiler()` | `Sentry.profiler.stopProfiler()` | Targeted hot paths              |
+
+> **`profileSessionSampleRate` is process-level** — decided once at startup, not
+> per-request. Use `0.1` to profile 10% of pods in a fleet without overhead on the rest.
+
+## Auto-Instrumented Integrations
+
+### Framework & HTTP (all auto-enabled)
+
+| Integration                  | What is traced                                                        |
+| ---------------------------- | --------------------------------------------------------------------- |
+| `nestIntegration`            | Middleware, guards, pipes, interceptors, filters, `@OnEvent` handlers |
+| `httpIntegration`            | Incoming HTTP requests + outgoing `http`/`https` calls                |
+| `nativeNodeFetchIntegration` | Outgoing `fetch()` calls                                              |
+| `requestDataIntegration`     | HTTP request data attached to error events                            |
+
+### Databases (all auto-enabled)
+
+`mongoIntegration`, `mongooseIntegration`, `mysqlIntegration`, `mysql2Integration`,
+`postgresIntegration`, `tediousIntegration`
+
+### Cache & Queues (all auto-enabled)
+
+`redisIntegration` (ioredis + node-redis), `amqplibIntegration` (AMQP/RabbitMQ),
+`kafkaIntegration` (KafkaJS)
+
+### AI / LLM (all auto-enabled)
+
+`openAIIntegration`, `anthropicAIIntegration`, `googleGenAIIntegration`,
+`langChainIntegration`, `vercelAiIntegration`
+
+### Must be added manually
+
+`knexIntegration`, `dataloaderIntegration`, `supabaseIntegration`,
+`captureConsoleIntegration`
+
+## What Is and Isn’t Auto-Traced
+
+### Auto-traced (no code changes needed)
+
+| Feature                                            | Mechanism                                                    |
+| -------------------------------------------------- | ------------------------------------------------------------ |
+| HTTP requests + transaction naming                 | `nestIntegration` + `SentryTracingInterceptor`               |
+| Middleware, guard, pipe, interceptor, filter spans | `SentryNestInstrumentation` (patches `@Injectable`/`@Catch`) |
+| `@OnEvent` handler spans                           | `SentryNestEventInstrumentation` (patches `@OnEvent`)        |
+| GraphQL queries/mutations/resolvers                | `graphqlIntegration`                                         |
+| AMQP/RabbitMQ + Kafka messages                     | `amqplibIntegration` + `kafkaIntegration`                    |
+| Redis, MongoDB, Mongoose, MySQL, PG                | Auto-integrations                                            |
+| Outgoing HTTP (axios, fetch, http)                 | `httpIntegration` + `nativeNodeFetchIntegration`             |
+| Any OTel instrumentation                           | Auto-forwarded via OTel bridge                               |
+
+### Requires manual instrumentation
+
+| Feature                        | API                                                                  |
+| ------------------------------ | -------------------------------------------------------------------- |
+| Custom business logic spans    | `Sentry.startSpan()`, `startSpanManual()`, `startInactiveSpan()`     |
+| Method-level tracing           | `@SentryTraced()` decorator                                          |
+| Cron job monitoring            | `@SentryCron()` decorator                                            |
+| Exception filter error capture | `@SentryExceptionCaptured()` decorator                               |
+| WebSocket gateway tracing      | `continueTrace()` + `startSpan()` in message handler                 |
+| TCP/NATS/gRPC microservices    | Manual `startSpan()` + `continueTrace()`                             |
+| Bull/BullMQ job tracing        | `withIsolationScope()` + `startSpan()` in `process()` / `@Process()` |
+| Non-HTTP distributed tracing   | `getTraceData()` + `continueTrace()`                                 |
+| TypeORM / Sequelize tracing    | Community OTel packages or manual spans                              |
+| Node.js profiling              | `@sentry/profiling-node` + `nodeProfilingIntegration()`              |
+
+## Best Practices
+
+- Always import `instrument.ts` as the **very first import** in `main.ts` — before
+  `@nestjs/core` or any app module
+- Use `tracesSampler` instead of `tracesSampleRate` in production — drop health checks,
+  adjust per-route, honour distributed decisions
+- Set `tracePropagationTargets` to avoid leaking `sentry-trace` headers to third-party
+  services
+- Prefer `startSpan()` (auto-ends) over `startSpanManual()` — forgetting `span.end()`
+  silently drops the span
+- Add `sentry-trace` and `baggage` to your CORS allowlist when tracing
+  browser-to-backend flows
+- Pin `@sentry/profiling-node` to the **exact same version** as `@sentry/nestjs`
+- Use `profileSessionSampleRate` to profile a fraction of pods rather than every pod —
+  the decision is per-process, not per-request
+- Always wrap background job handlers (`@Process()`, `WorkerHost.process()`, `@Cron()`,
+  `@OnEvent()`) with `withIsolationScope()` before `startSpan()` — without isolation,
+  concurrent jobs share scope state
+- If the project uses a DI wrapper for Sentry (e.g. `SENTRY_PROXY_TOKEN`), use the
+  injected service for `startSpan`, `captureException`, etc.
+  — only `instrument.ts` should import `@sentry/nestjs` directly
+- When using a config class for `Sentry.init()`, add new SDK options to the config type
+  rather than hardcoding them — this keeps options configurable per environment
+
+## Troubleshooting
+
+| Issue                                                                  | Solution                                                                                            |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| No transactions appearing                                              | Verify `tracesSampleRate > 0` or `tracesSampler` returns non-zero                                   |
+| Transaction names show raw URL (e.g., `/users/123`) instead of pattern | `SentryModule.forRoot()` not imported; or `instrument.ts` loaded after `@nestjs/core`               |
+| Middleware/guard/pipe spans missing                                    | `nestIntegration` not registered; ensure `instrument.ts` is first import                            |
+| `@OnEvent` spans not appearing                                         | `@nestjs/event-emitter` < 2.0.0; or `instrument.ts` loaded after event emitter                      |
+| Distributed traces broken across services                              | Check `sentry-trace` and `baggage` headers pass through proxies/API gateways                        |
+| DB spans missing                                                       | Driver loaded before `instrument.ts`; reorder imports                                               |
+| Profiler crashes at startup                                            | `@sentry/profiling-node` version doesn’t match `@sentry/nestjs`                                     |
+| Event spans appear as isolated transactions                            | Expected — `@OnEvent` uses `forceTransaction: true` by design                                       |
+| RPC exceptions not captured or app crashes                             | Use a dedicated `@Catch(RpcException)` filter; `SentryGlobalFilter` logs a warning for RPC          |
+| OTel instrumentation spans not appearing                               | Ensure the OTel package is loaded after `instrument.ts`                                             |
+| BullMQ jobs share tags/user/breadcrumbs                                | Wrap `process()` body with `Sentry.withIsolationScope(() => ...)`                                   |
+| `profilesSampleRate` not working                                       | Deprecated in SDK 10.x — use `profileSessionSampleRate` + `profileLifecycle: "trace"`               |
+| `SentryModule.forRoot()` registered twice                              | Only register once — if a shared library module already imports it, skip in `AppModule`             |
+| `import * as Sentry` blocked by ESLint                                 | Use named imports or the project’s DI proxy; namespace imports trigger `no-restricted-syntax` rules |