@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,169 @@
+# Logging — Sentry Cloudflare SDK
+
+> Minimum SDK: `@sentry/cloudflare` v9.41.0+ (stable GA) First experimental: v9.10.0+
+> (via `_experiments.enableLogs`) Status: ✅ **Generally Available**
+
+---
+
+## Overview
+
+Sentry Logs are high-cardinality structured log entries that link directly to traces and
+errors. They let you answer _why_ something broke, not just _what_ broke.
+
+Key characteristics:
+
+- Sent as structured data — each attribute is individually searchable in Sentry UI
+- Automatically linked to the active trace (if tracing is enabled)
+- Buffered and batched — no per-log network overhead
+- NOT a replacement for a logging library; designed to complement one
+
+---
+
+## Initialization
+
+`enableLogs: true` is **required**. Logging is disabled by default.
+
+```typescript
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    enableLogs: true,
+    tracesSampleRate: 1.0,
+
+    beforeSendLog: (log) => {
+      // Optional: filter or transform logs
+      if (log.level === "debug") return null; // Drop debug logs
+      return log;
+    },
+  }),
+  handler,
+);
+```
+
+---
+
+## Logger API
+
+All six methods live at `Sentry.logger.*`:
+
+```typescript
+Sentry.logger.trace("Processing request for path %s", [request.url]);
+Sentry.logger.debug("Cache lookup result: %s", [cacheHit ? "hit" : "miss"]);
+Sentry.logger.info("User %s authenticated successfully", [userId]);
+Sentry.logger.warn("Rate limit approaching for key %s: %d/%d", [apiKey, current, limit]);
+Sentry.logger.error("Payment processing failed for order %s", [orderId]);
+Sentry.logger.fatal("Worker initialization failed: %s", [error.message]);
+```
+
+### Signature
+
+```typescript
+Sentry.logger.<level>(message: string, params?: unknown[], attributes?: Record<string, unknown>)
+```
+
+- **`message`** — format string with `%s`, `%d`, `%f`, `%o`, `%O` placeholders
+  (printf-style)
+- **`params`** — parameter values substituted into the format string
+- **`attributes`** — structured key-value data attached to the log entry
+
+### With Attributes
+
+```typescript
+Sentry.logger.info("Request processed", [], {
+  "http.method": request.method,
+  "http.url": request.url,
+  "http.status_code": response.status,
+  "response.time_ms": elapsed,
+});
+```
+
+---
+
+## Console Integration
+
+The `consoleIntegration` (enabled by default) captures `console.log`, `console.warn`,
+`console.error`, etc.
+as **breadcrumbs** — not as Sentry Logs.
+
+For actual Sentry Logs that appear in the Logs product, use `Sentry.logger.*`.
+
+To also forward `console.*` calls to Sentry Logs, add the `consoleLoggingIntegration`:
+
+```typescript
+import * as Sentry from "@sentry/cloudflare";
+
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    enableLogs: true,
+    integrations: [Sentry.consoleLoggingIntegration({ levels: ["warn", "error"] })],
+  }),
+  handler,
+);
+```
+
+This captures `console.warn()` and `console.error()` calls as Sentry Logs in addition to
+their normal breadcrumb behavior.
+
+---
+
+## Log-to-Trace Correlation
+
+When tracing is enabled, logs are automatically linked to the active trace.
+In the Sentry UI, you can navigate from a log entry to the trace timeline and vice
+versa.
+
+```typescript
+await Sentry.startSpan({ op: "function", name: "processOrder" }, async () => {
+  Sentry.logger.info("Starting order processing for %s", [orderId]);
+
+  await validateOrder(orderId);
+  Sentry.logger.debug("Order validated", [], { orderId });
+
+  await chargePayment(orderId);
+  Sentry.logger.info("Payment charged for order %s", [orderId]);
+});
+// All three log entries are linked to the "processOrder" span
+```
+
+---
+
+## Configuration
+
+| Option          | Type                   | Default | Notes                                        |
+| --------------- | ---------------------- | ------- | -------------------------------------------- |
+| `enableLogs`    | `boolean`              | `false` | Must be `true` to enable Sentry Logs         |
+| `beforeSendLog` | `(log) => log \| null` | —       | Filter or modify logs; return `null` to drop |
+
+---
+
+## Best Practices
+
+1. **Use structured attributes** — put searchable data in the `attributes` parameter,
+   not in the message string.
+   This makes logs filterable in the Sentry UI.
+
+2. **Use format strings with parameters** —
+   `Sentry.logger.info("User %s did %s", [userId, action])` is better than template
+   literals because Sentry can group similar logs.
+
+3. **Don’t log everything** — Sentry Logs are for observability, not a firehose.
+   Focus on key events: authentication, payment, external API calls, errors.
+
+4. **Combine with `console.log` for local dev** — `Sentry.logger.*` sends to Sentry
+   only. Keep `console.log` for local development output and `Sentry.logger.*` for
+   production observability.
+
+5. **Filter noisy logs** — use `beforeSendLog` to drop debug/trace level logs in
+   production if they generate too much volume.
+
+---
+
+## Troubleshooting
+
+| Issue                            | Solution                                                                                                  |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Logs not appearing in Sentry     | Verify `enableLogs: true` is set in init options                                                          |
+| Logs not linked to traces        | Ensure tracing is enabled (`tracesSampleRate` or `tracesSampler` set)                                     |
+| `console.log` not in Sentry Logs | `console.*` creates breadcrumbs, not Logs. Use `consoleLoggingIntegration` to also forward to Sentry Logs |
+| Log volume too high              | Use `beforeSendLog` to filter by level or content; avoid logging in tight loops                           |

package/skills/sentry/references/sdks/cloudflare/nodejs-compat.md

@@ -0,0 +1,134 @@
+# Node.js Compatibility Entrypoint — Sentry Cloudflare SDK
+
+> `@sentry/cloudflare/nodejs_compat` entrypoint: v10.64.0+ Prisma integration
+> (Cloudflare): via `/nodejs_compat` entrypoint only Requires the `nodejs_compat`
+> compatibility flag in Wrangler config
+
+---
+
+## Overview
+
+Cloudflare Workers can run with Node.js APIs enabled through the
+[`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/).
+To take advantage of this, the Cloudflare SDK ships a dedicated
+`@sentry/cloudflare/nodejs_compat` entrypoint that unlocks Node.js SDK features which
+aren’t available in the default Workers runtime.
+
+**Using this entrypoint is generally recommended, and it’s the default choice for new
+projects.** It’s a drop-in replacement for the default `@sentry/cloudflare` import that
+adds functionality (see [What It Unlocks](#what-it-unlocks)) without removing anything —
+and it becomes the default entrypoint in v11, so adopting it now keeps you ahead of that
+change. The only prerequisite is the `nodejs_compat` flag, which is itself a superset of
+the `nodejs_als` flag the SDK already needs.
+For a new Worker, enable `nodejs_compat` and import from
+`@sentry/cloudflare/nodejs_compat` from the start.
+
+> The `/nodejs_compat` entrypoint requires SDK version `10.64.0` or higher.
+> It will become the **default entrypoint in the next major version (v11)**.
+
+### What It Unlocks
+
+The `/nodejs_compat` entrypoint enables Node.js-only integrations and features on
+Cloudflare, including:
+
+- **`prismaIntegration`** — tracing Prisma ORM queries (see
+  [Prisma Integration](#prisma-integration) below)
+- **Vercel AI SDK v7 support** for the `vercelAIIntegration`
+
+---
+
+## Usage
+
+The entrypoint is a drop-in replacement for `@sentry/cloudflare` — switching over only
+requires changing your imports:
+
+```typescript
+// Before
+import * as Sentry from "@sentry/cloudflare";
+
+// After
+import * as Sentry from "@sentry/cloudflare/nodejs_compat";
+```
+
+Everything else (`withSentry`, `sentryPagesPlugin`, `instrumentDurableObjectWithSentry`,
+etc.) works exactly the same.
+
+### Prerequisite: `nodejs_compat` Flag
+
+To use the entrypoint, your Worker must set the `nodejs_compat` compatibility flag in
+your Wrangler configuration:
+
+**wrangler.jsonc:**
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat"],
+}
+```
+
+**wrangler.toml:**
+
+```toml
+compatibility_flags = ["nodejs_compat"]
+```
+
+> `nodejs_compat` is a superset of `nodejs_als` — it enables `AsyncLocalStorage` (which
+> the SDK requires) plus the rest of the Node.js compatibility surface.
+> If you’re already on `nodejs_compat`, using the `/nodejs_compat` entrypoint is
+> recommended.
+
+---
+
+## Prisma Integration
+
+On Cloudflare, the `prismaIntegration` is **only** available through the
+`/nodejs_compat` entrypoint.
+
+Import Sentry from the `@sentry/cloudflare/nodejs_compat` entrypoint and add
+`prismaIntegration` to your init options:
+
+```typescript
+import * as Sentry from "@sentry/cloudflare/nodejs_compat";
+
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+    integrations: [Sentry.prismaIntegration()],
+  }),
+  {
+    async fetch(request, env, ctx) {
+      return new Response("OK");
+    },
+  } satisfies ExportedHandler<Env>,
+);
+```
+
+The integration creates a span for each query and reports relevant details to Sentry.
+
+**Supported Prisma versions:** `5.x`, `6.x`, `7.x`.
+
+In Prisma **v5**, you also need to add the `tracing` preview feature to the `generator`
+block of your Prisma schema:
+
+```txt
+// schema.prisma
+generator client {
+  provider        = "prisma-client-js"
+  previewFeatures = ["tracing"]
+}
+```
+
+For details on the span structure Prisma’s OpenTelemetry tracing produces (e.g.,
+`prisma:client:operation`, `prisma:engine:db_query`), see the
+[Prisma trace output docs](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing#trace-output).
+
+---
+
+## Troubleshooting
+
+| Issue                                           | Cause                                              | Solution                                                                        |
+| ----------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `prismaIntegration` not found / no Prisma spans | Importing from the default entrypoint              | Import from `@sentry/cloudflare/nodejs_compat` and ensure SDK ≥ v10.64.0        |
+| Prisma v5 produces no spans                     | Missing `tracing` preview feature                  | Add `previewFeatures = ["tracing"]` to the `generator` block in `schema.prisma` |
+| Node.js APIs undefined at runtime               | Using `/nodejs_compat` entrypoint without the flag | Add `nodejs_compat` to `compatibility_flags` in Wrangler config                 |