@stacknext/prisma 0.9.0 → 0.10.0

package/docs/configuration.md

@@ -0,0 +1,81 @@
+---
+title: Configuration
+description: Configure Prisma query events and the StackNext adapter.
+---
+
+# Configuration
+
+## Prisma Client
+
+Query events must be enabled when the client is created:
+
+```ts
+import { PrismaClient } from '@prisma/client'
+
+const prisma = new PrismaClient({
+  log: [{ emit: 'event', level: 'query' }],
+})
+```
+
+Prisma's default logging does not emit these events.
+
+## Adapter
+
+```ts
+import { instrumentPrismaClient } from '@stacknext/prisma'
+
+const stop = instrumentPrismaClient(prisma, {
+  databaseSystem: 'postgresql',
+})
+```
+
+| Option | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `databaseSystem` | No | `'prisma'` | Use the engine name, for example `sqlite` or `postgresql`. |
+| `transport` | No | Process-wide transport | Must expose `enqueueDatabaseQuery`. |
+| `onError` | No | none | Receives telemetry failures; they never reach Prisma. |
+
+## Lifecycle
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:28f70536dac55a5bf479d919dd7e163c76b9148c7a914e348e3b8decef5a2e95 -->
+
+`instrumentPrismaClient` returns a cleanup function. Calling it deactivates the
+listener and clears the idempotency guard. Calling `instrumentPrismaClient`
+again for the same client before cleanup returns a no-op cleanup.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+Register the adapter once per Prisma client, after the client is created and
+before the first request.
+
+## `stacknext.config.json`
+
+```json
+{
+  "database": { "drizzle": false, "prisma": true }
+}
+```
+
+`database.prisma` is setup intent used by `stacknext init` and
+`stacknext doctor`. It does not attach the listener; the adapter must be called
+explicitly.
+
+## Duration
+
+Prisma query events include a duration in milliseconds. StackNext uses it when
+it is a finite number, otherwise `durationMs` is `null`. Null is unmeasured, not
+zero.
+
+## Privacy
+
+The adapter never reads `event.params`. SQL is redacted and capped. No
+configuration option can enable bind-parameter capture.
+
+## Verify
+
+1. Start `stacknext dev` and exercise a Prisma query.
+2. Run `stacknext coverage`; database evidence should be observed.
+3. Check that the query duration is measured for Prisma.
+4. Open the dashboard Database page or use `list_database_queries` through MCP.

package/docs/index.md

@@ -0,0 +1,84 @@
+---
+title: "@stacknext/prisma"
+description: Prisma Client query event instrumentation for StackNext.
+---
+
+# @stacknext/prisma
+
+`@stacknext/prisma` subscribes to Prisma `query` events and sends redacted query
+evidence to the active StackNext transport.
+
+## Who should read this
+
+Applications using Prisma. This is a **public, optional integration package**.
+It is not required unless the project uses Prisma.
+
+## Installation
+
+```bash
+pnpm add @stacknext/prisma
+```
+
+`@prisma/client >=5.0.0` is an optional peer dependency. The adapter accepts a
+structural subset of the client and does not import Prisma at runtime.
+
+## Usage
+
+```ts
+import { PrismaClient } from '@prisma/client'
+import { instrumentPrismaClient } from '@stacknext/prisma'
+
+const prisma = new PrismaClient({
+  log: [{ emit: 'event', level: 'query' }],
+})
+
+const stop = instrumentPrismaClient(prisma, {
+  databaseSystem: 'postgresql',
+})
+
+// Optional: call stop() during shutdown.
+```
+
+Prisma must be configured to emit query events. Without the `log` event
+configuration, the adapter receives nothing.
+
+## API
+
+### `instrumentPrismaClient(client, options?)`
+
+Subscribes to `$on('query', listener)` and returns a cleanup function. It is
+idempotent for the same client instance: a second call returns a no-op cleanup
+and does not attach a second listener.
+
+`StackNextPrismaOptions`:
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `databaseSystem` | string | `'prisma'` | Reported as `db.system.name`. |
+| `transport` | `Pick<StackNextTransport, 'enqueueDatabaseQuery'>` | global transport | Override for tests or custom setups. |
+| `onError` | `(error: unknown) => void` | none | Called when the sink throws. |
+
+## What is recorded
+
+- redacted SQL text (capped at 20,000 characters);
+- inferred operation;
+- `durationMs` when Prisma supplies a finite, non-negative duration;
+- active trace/span ids when a valid OTel context exists;
+- `databaseSystem`, `source: 'prisma'`, `success: true`;
+- `db.duration.measured`;
+- `db.prisma.target` (bounded to 200 characters), when present.
+
+## Privacy
+
+`event.params` is typed as a JSON string but is **never read**. SQL text passes
+through `redactSql`. Query events do not include request bodies or headers.
+
+## Documentation map
+
+- [Configuration](configuration.md)
+- [Troubleshooting](troubleshooting.md)
+
+## Related packages
+
+- `@stacknext/core` owns the transport and redaction.
+- `@stacknext/cli` runs the collector.

package/docs/troubleshooting.md

@@ -0,0 +1,49 @@
+---
+title: Troubleshooting
+description: Diagnose missing Prisma query events, duplicate listeners and unmeasured durations.
+---
+
+# Troubleshooting
+
+## No Prisma queries appear
+
+1. Confirm `PrismaClient` is created with
+   `log: [{ emit: 'event', level: 'query' }]`.
+2. Confirm `instrumentPrismaClient(prisma, ...)` is called on that same client.
+3. Confirm the app runs under `stacknext dev`.
+4. Exercise a query, then check `stacknext coverage`.
+5. Run `stacknext doctor` for adapter and config warnings.
+
+## The listener is not attached
+
+The adapter requires `client.$on('query', callback)`. A mock, a wrapper or a
+different client type may not satisfy the structural contract. Use the real
+Prisma Client.
+
+## I called the adapter twice
+
+It is idempotent for the same client. The second call returns a no-op cleanup
+and does not attach another listener.
+
+## Duration is null
+
+The event duration was missing or not a finite number. StackNext never
+fabricates a duration. Check the Prisma event payload and version.
+
+## Queries are not linked to a request
+
+Trace/span ids are recorded only when a valid OTel context is active. Queries
+from scripts, workers or background jobs may have no request root.
+
+## Params are missing
+
+By design. `event.params` is never read, logged or transmitted. The redacted SQL
+text is the only query body StackNext stores.
+
+## Verify
+
+```bash
+stacknext status --json
+stacknext coverage --json
+stacknext diagnose --category database
+```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@stacknext/prisma",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Prisma Client query instrumentation adapter for StackNext",
   "license": "MIT",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,7 +19,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/core": "0.9.0",
+    "@stacknext/core": "0.10.0",
     "@opentelemetry/api": "1.9.0"
   },
   "devDependencies": {