@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,174 @@
+# Logging — Sentry NestJS SDK
+
+> Minimum SDK: `@sentry/nestjs` 9.41.0+ for structured Sentry Logs (`enableLogs: true`)
+
+## Two Logging Systems
+
+| System                     | Produces                                       | Requires                               |
+| -------------------------- | ---------------------------------------------- | -------------------------------------- |
+| **Sentry Structured Logs** | Searchable log records in Sentry Logs UI       | `enableLogs: true` + `Sentry.logger.*` |
+| **Framework integrations** | Bridge NestJS/Pino/Winston logs to Sentry Logs | Integration-specific setup             |
+
+## Configuration
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+Sentry.init({
+  dsn: "https://<key>@<org>.ingest.sentry.io/<project>",
+  enableLogs: true, // required — without this, all Sentry.logger.* calls are no-ops
+});
+```
+
+## Code Examples
+
+### Sentry Structured Logs — direct API
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+// All six log levels
+Sentry.logger.trace("Starting database connection {database}", { database: "users" });
+Sentry.logger.debug("Cache miss for user {userId}", { userId: 123 });
+Sentry.logger.info("User signed in");
+Sentry.logger.warn("Rate limit reached for endpoint {endpoint}", { endpoint: "/api/results" });
+Sentry.logger.error("Failed to process payment for order {orderId}", { orderId: "or_2342" });
+Sentry.logger.fatal("Database {database} connection pool exhausted", { database: "users" });
+```
+
+**Available levels:** `trace`, `debug`, `info`, `warn`, `error`, `fatal`
+
+### Tagged template for parameterized messages
+
+Use `Sentry.logger.fmt` to create structured, searchable messages where each placeholder
+becomes an individually queryable attribute in the Sentry Logs UI:
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+Sentry.logger.info(Sentry.logger.fmt`User ${"userId"} signed in from ${"region"}`, {
+  userId: 42,
+  region: "eu-west-1",
+});
+```
+
+### NestJS ConsoleLogger integration
+
+To route NestJS’s built-in `ConsoleLogger` output to Sentry Logs, use
+`consoleLoggingIntegration` with `forceConsole: true`:
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+import { consoleLoggingIntegration } from "@sentry/nestjs";
+
+Sentry.init({
+  dsn: "...",
+  enableLogs: true,
+  integrations: [consoleLoggingIntegration({ forceConsole: true })],
+});
+```
+
+Then use NestJS’s built-in logger as usual — all output is captured:
+
+```typescript
+import { Injectable, Logger } from "@nestjs/common";
+
+@Injectable()
+export class AppService {
+  private readonly logger = new Logger(AppService.name);
+
+  doSomething() {
+    this.logger.log("Processing request"); // → Sentry Logs: info
+    this.logger.warn("Unusual payload size"); // → Sentry Logs: warn
+    this.logger.error("Payment failed"); // → Sentry Logs: error
+  }
+}
+```
+
+### Pino integration (SDK 10.18.0+)
+
+```bash
+npm install pino
+```
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+import { pinoIntegration } from "@sentry/nestjs";
+
+Sentry.init({
+  dsn: "...",
+  enableLogs: true,
+  integrations: [pinoIntegration()],
+});
+```
+
+### Winston integration
+
+```bash
+npm install winston
+```
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+import { createSentryWinstonTransport } from "@sentry/nestjs";
+import winston from "winston";
+
+Sentry.init({ dsn: "...", enableLogs: true });
+
+const logger = winston.createLogger({
+  transports: [
+    new winston.transports.Console(),
+    createSentryWinstonTransport({ minLevel: "info" }),
+  ],
+});
+```
+
+> **Bunyan is not supported.** Use Pino or Winston if you need a framework logger
+> bridge.
+
+### `beforeSendLog` hook — filter and sanitize
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+Sentry.init({
+  dsn: "...",
+  enableLogs: true,
+  beforeSendLog(log) {
+    // Drop debug logs to reduce volume
+    if (log.level === "debug") return null;
+
+    // Redact sensitive fields
+    if (log.attributes?.["user.email"]) {
+      log.attributes["user.email"] = "[redacted]";
+    }
+
+    return log;
+  },
+});
+```
+
+## Log-to-Trace Correlation
+
+Log entries are automatically correlated to the active trace — no configuration
+required. When a log is emitted inside an instrumented request or span, Sentry links it
+to the corresponding transaction in the Traces UI.
+
+## Decision Table
+
+| Goal                                            | Tool                                                |
+| ----------------------------------------------- | --------------------------------------------------- |
+| Searchable structured records in Sentry Logs UI | `Sentry.logger.*` + `enableLogs: true`              |
+| Bridge NestJS `ConsoleLogger` to Sentry Logs    | `consoleLoggingIntegration({ forceConsole: true })` |
+| Bridge Pino to Sentry Logs                      | `pinoIntegration()` (SDK 10.18.0+)                  |
+| Bridge Winston to Sentry Logs                   | `createSentryWinstonTransport()`                    |
+| Drop or modify a log before sending             | `beforeSendLog` callback                            |
+
+## Troubleshooting
+
+| Issue                                       | Solution                                                    |
+| ------------------------------------------- | ----------------------------------------------------------- |
+| `Sentry.logger.*` calls have no effect      | Ensure `enableLogs: true` is set in `Sentry.init()`         |
+| NestJS `ConsoleLogger` output not appearing | Add `consoleLoggingIntegration({ forceConsole: true })`     |
+| Pino logs not appearing                     | Requires `@sentry/nestjs` 10.18.0+; add `pinoIntegration()` |
+| Too many log records hitting quota          | Use `beforeSendLog` to filter by level or attribute         |

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

@@ -0,0 +1,243 @@
+# Metrics — Sentry NestJS SDK
+
+> Minimum SDK: `@sentry/nestjs` 10.25.0+
+
+## Overview
+
+`Sentry.metrics` provides custom counters, gauges, and distributions.
+Metrics are enabled by default — no extra `init()` flag needed.
+
+## Metric Types
+
+| Type         | API                             | Use for                                                     |
+| ------------ | ------------------------------- | ----------------------------------------------------------- |
+| Counter      | `Sentry.metrics.count()`        | Event occurrences, request counts                           |
+| Distribution | `Sentry.metrics.distribution()` | Latencies, sizes — supports p50/p90/p95/p99                 |
+| Gauge        | `Sentry.metrics.gauge()`        | Current values (min, max, avg, sum, count — no percentiles) |
+
+## Configuration
+
+```typescript
+import "./instrument"; // Sentry init must run before anything else
+import { NestFactory } from "@nestjs/core";
+import { AppModule } from "./app.module";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+No extra flags required — metrics are on by default once `Sentry.init()` is called.
+
+Optional `beforeSendMetric` hook:
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+Sentry.init({
+  dsn: "https://<key>@<org>.ingest.sentry.io/<project>",
+  beforeSendMetric(metric) {
+    if (metric.name === "noisy-metric") {
+      return null; // drop this metric
+    }
+    metric.attributes["env"] = "prod"; // add attribute
+    return metric;
+  },
+});
+```
+
+## Code Examples
+
+### Counter — event occurrences
+
+```typescript
+import * as Sentry from '@sentry/nestjs';
+
+// In a controller
+@Controller('orders')
+export class OrdersController {
+  @Post()
+  async createOrder(@Body() dto: CreateOrderDto) {
+    Sentry.metrics.count('orders.created', 1, {
+      attributes: {
+        type: dto.type,
+        region: dto.region,
+      },
+    });
+    return this.ordersService.create(dto);
+  }
+}
+
+// Count per route/method
+@Get(':id')
+async getOrder(@Param('id') id: string) {
+  Sentry.metrics.count('http.requests', 1, {
+    attributes: {
+      route: '/orders/:id',
+      method: 'GET',
+    },
+  });
+  return this.ordersService.findOne(id);
+}
+```
+
+### Distribution — percentile analysis
+
+Best for latencies, response sizes, durations where p50/p90/p99 matter:
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+@Injectable()
+export class OrdersService {
+  async processOrder(order: Order): Promise<void> {
+    const start = Date.now();
+
+    await this.doProcessing(order);
+
+    Sentry.metrics.distribution("orders.processing_time", Date.now() - start, {
+      unit: "millisecond",
+      attributes: {
+        "order.type": order.type,
+        region: order.region,
+      },
+    });
+  }
+}
+```
+
+Database query timing:
+
+```typescript
+@Injectable()
+export class UsersRepository {
+  async findByEmail(email: string) {
+    const start = Date.now();
+    const result = await this.db.users.findOne({ email });
+
+    Sentry.metrics.distribution("db.query_time", Date.now() - start, {
+      unit: "millisecond",
+      attributes: { table: "users", operation: "findOne" },
+    });
+
+    return result;
+  }
+}
+```
+
+### Gauge — current state
+
+Use for values that fluctuate over time; no percentile support:
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+
+// Bull/BullMQ queue depth
+@Injectable()
+export class QueueMonitorService {
+  constructor(@InjectQueue("email") private emailQueue: Queue) {}
+
+  @Cron(CronExpression.EVERY_MINUTE)
+  async reportQueueDepth() {
+    const waiting = await this.emailQueue.getWaitingCount();
+    const active = await this.emailQueue.getActiveCount();
+
+    Sentry.metrics.gauge("queue.depth", waiting, {
+      attributes: { queue: "email", state: "waiting" },
+    });
+
+    Sentry.metrics.gauge("queue.depth", active, {
+      attributes: { queue: "email", state: "active" },
+    });
+  }
+}
+```
+
+### Business event counting
+
+```typescript
+@Injectable()
+export class PaymentsService {
+  async chargeCard(dto: ChargeDto): Promise<Charge> {
+    try {
+      const charge = await this.stripe.charges.create(dto);
+
+      Sentry.metrics.count("payments.charged", 1, {
+        attributes: {
+          currency: dto.currency,
+          success: true,
+        },
+      });
+
+      return charge;
+    } catch (err) {
+      Sentry.metrics.count("payments.charged", 1, {
+        attributes: {
+          currency: dto.currency,
+          success: false,
+          "error.type": err.type ?? "unknown",
+        },
+      });
+      throw err;
+    }
+  }
+}
+```
+
+### Attribute value types
+
+```typescript
+Sentry.metrics.count("api.request", 1, {
+  attributes: {
+    endpoint: "/v2/users", // string
+    method: "POST",
+    success: true, // boolean
+    status_code: 201, // number
+    latency: 0.042, // number (float)
+  },
+});
+```
+
+### Unit strings
+
+| Category      | Values                                                                                                |
+| ------------- | ----------------------------------------------------------------------------------------------------- |
+| Time          | `"nanosecond"`, `"microsecond"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"` |
+| Data          | `"bit"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`                             |
+| Fractions     | `"ratio"`, `"percent"`                                                                                |
+| Dimensionless | `"none"` (default when omitted)                                                                       |
+
+### `beforeSendMetric` — metric object schema
+
+| Key          | Type                                          | Description                                |
+| ------------ | --------------------------------------------- | ------------------------------------------ |
+| `name`       | `string`                                      | Metric identifier                          |
+| `type`       | `string`                                      | `"counter"` / `"gauge"` / `"distribution"` |
+| `value`      | `number`                                      | Numeric measurement                        |
+| `unit`       | `string \| undefined`                         | Unit string                                |
+| `attributes` | `Record<string, string \| number \| boolean>` | Custom key-value pairs                     |
+| `timestamp`  | `number`                                      | Epoch seconds                              |
+| `traceId`    | `string \| undefined`                         | Associated trace ID                        |
+| `spanId`     | `string \| undefined`                         | Active span ID                             |
+
+## Best Practices
+
+- Keep attribute cardinality low — avoid user IDs, UUIDs, or timestamps as attribute
+  values
+- Use `distribution` over `gauge` when you need percentile analysis
+- Prefix metric names with your service name: `"payments.charge_time"` not
+  `"charge_time"`
+- Use standard unit strings — Sentry renders them in the UI with proper labels
+- Each metric consumes up to 2 KB — avoid unbounded attribute value sets
+- Metrics are buffered and flushed periodically — not suitable for sub-second alerting
+
+## Troubleshooting
+
+| Issue                       | Solution                                                                    |
+| --------------------------- | --------------------------------------------------------------------------- |
+| Metrics not appearing       | Verify `@sentry/nestjs` ≥ 10.25.0; check `debug: true` output               |
+| Metric dropped silently     | Check `beforeSendMetric` hook; verify metric name has no special characters |
+| High cardinality warning    | Reduce attribute values — avoid per-user or per-request identifiers         |
+| No percentiles in Sentry UI | Switch from `gauge` to `distribution` — gauges do not support percentiles   |

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

@@ -0,0 +1,127 @@
+# Profiling — Sentry NestJS SDK
+
+> Requires `@sentry/profiling-node` (version must **exactly match** `@sentry/nestjs`)
+
+## Installation
+
+```bash
+npm install @sentry/profiling-node --save
+```
+
+## Configuration
+
+| Option                                       | Purpose                                                            |
+| -------------------------------------------- | ------------------------------------------------------------------ |
+| `integrations: [nodeProfilingIntegration()]` | Enable the V8 CPU profiler                                         |
+| `profileSessionSampleRate`                   | Fraction of processes/pods to profile (evaluated **once at init**) |
+| `profileLifecycle`                           | `'trace'` = auto-managed; `'manual'` = explicit start/stop         |
+| `tracesSampleRate`                           | Must be `> 0` — profiling requires tracing to be active            |
+
+## Mode Comparison
+
+|                   | Trace lifecycle (`'trace'`)     | Manual (`'manual'`)               |
+| ----------------- | ------------------------------- | --------------------------------- |
+| **Start trigger** | First active span               | `Sentry.profiler.startProfiler()` |
+| **Stop trigger**  | Last span ends                  | `Sentry.profiler.stopProfiler()`  |
+| **Coverage**      | All code during active spans    | Only between explicit start/stop  |
+| **Use case**      | General profiling (recommended) | Targeted hot paths                |
+| **Setup**         | Zero — fully automatic          | Manual call sites required        |
+
+## Code Examples
+
+### Trace lifecycle — recommended
+
+Add `nodeProfilingIntegration()` to the `integrations` array in `instrument.ts`:
+
+```typescript
+// instrument.ts  (must be the first file loaded — see main skill)
+import * as Sentry from "@sentry/nestjs";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: 1.0,
+  profileSessionSampleRate: 1.0, // profile 100% of process sessions
+  profileLifecycle: "trace", // SDK auto-manages profiler lifetime
+});
+```
+
+All HTTP requests, lifecycle spans, `@OnEvent` handlers, and custom spans are profiled
+automatically.
+
+### Manual mode — targeted profiling
+
+```typescript
+import * as Sentry from "@sentry/nestjs";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: 1.0,
+  profileSessionSampleRate: 1.0,
+  profileLifecycle: "manual",
+});
+
+// Somewhere in application code:
+Sentry.profiler.startProfiler();
+await expensiveOperation();
+Sentry.profiler.stopProfiler();
+```
+
+### Production fleet sampling
+
+`profileSessionSampleRate` is decided **once at process startup** — use it to sample a
+fraction of pods/containers rather than per-request:
+
+```typescript
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: 0.1, // sample 10% of requests for traces
+  profileSessionSampleRate: 0.25, // profile 25% of pods/instances
+  profileLifecycle: "trace",
+});
+```
+
+## Technical Details
+
+- Uses **V8’s `CpuProfiler`** native C++ add-on — ~100 Hz sampling (10 ms interval)
+- Precompiled binaries available for:
+  - macOS x64 / ARM64
+  - Linux x64 glibc / ARM64 musl
+  - Windows x64
+  - Node.js 18, 20, 22, 24
+- **Not supported** in Deno or Bun
+
+## Environment Variables
+
+| Variable                       | Purpose                                           |
+| ------------------------------ | ------------------------------------------------- |
+| `SENTRY_PROFILER_BINARY_PATH`  | Override full path to `profiler.node` binary      |
+| `SENTRY_PROFILER_BINARY_DIR`   | Override directory containing `profiler.node`     |
+| `SENTRY_PROFILER_LOGGING_MODE` | `eager` (default) or `lazy` (starts on first use) |
+
+**Eager mode (default):** Profiler always running — lower latency to first profile, uses
+CPU between requests.\
+**Lazy mode:** Starts on first use — lower baseline CPU overhead, small latency on first
+profile.
+
+## Performance Overhead
+
+- 100 Hz sampling has minimal per-sample cost
+- Eager mode consumes some CPU even between requests
+- Load test before enabling in high-throughput production services
+- Start with a low `profileSessionSampleRate` (e.g., `0.1`) and increase based on
+  observed overhead
+
+## Troubleshooting
+
+| Issue                               | Solution                                                                                              |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| No profiles appearing               | Verify `tracesSampleRate > 0` and both `profileSessionSampleRate` + `profileLifecycle` are set        |
+| Native binary fails to load         | Check Node.js version is 18–24 and platform is supported; set `SENTRY_PROFILER_BINARY_PATH` if needed |
+| Version mismatch error              | `@sentry/profiling-node` version must exactly match `@sentry/nestjs`                                  |
+| Profiler not stopping (manual mode) | Ensure `Sentry.profiler.stopProfiler()` is called on shutdown / after the target code                 |
+| High CPU in idle                    | Switch to `SENTRY_PROFILER_LOGGING_MODE=lazy` or reduce `profileSessionSampleRate`                    |