@prisma-next/middleware-telemetry 0.0.1

package/README.md

@@ -0,0 +1,29 @@
+# @prisma-next/middleware-telemetry
+
+A generic, family-agnostic telemetry middleware for Prisma Next runtimes.
+
+## Purpose
+
+This package is a **proof-of-concept** demonstrating that the `RuntimeMiddleware` SPI works across both SQL and Mongo runtimes. It validates the cross-family middleware contract by implementing a single middleware that operates identically in both families without any family-specific code.
+
+It is **not** intended as a production observability solution. Because framework-level middleware can only access `PlanMeta` (lane, target, storageHash, refs), they cannot inspect query content (SQL strings, Mongo commands, ASTs). Production telemetry will typically use family-specific middleware interfaces (`SqlMiddleware`, `MongoMiddleware`) that expose the full plan type.
+
+## Usage
+
+```typescript
+import { createTelemetryMiddleware } from '@prisma-next/middleware-telemetry';
+
+// Default: logs events via ctx.log.info
+const middleware = createTelemetryMiddleware();
+
+// Custom: collect events programmatically
+const middleware = createTelemetryMiddleware({
+  onEvent: (event) => console.log(event),
+});
+```
+
+The middleware emits a `TelemetryEvent` before and after each query execution, containing lane, target, storageHash, and (after execution) row count, latency, and completion status.
+
+## See also
+
+- [Runtime & Middleware Framework](../../../docs/architecture%20docs/subsystems/4.%20Runtime%20&%20Middleware%20Framework.md) — SPI design and middleware lifecycle

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@prisma-next/middleware-telemetry",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Generic telemetry middleware for Prisma Next runtimes",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/framework-components": "workspace:*"
+  },
+  "devDependencies": {
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/3-extensions/middleware-telemetry"
+  }
+}

package/src/exports/index.ts

@@ -0,0 +1,2 @@
+export type { TelemetryEvent, TelemetryMiddlewareOptions } from '../telemetry-middleware';
+export { createTelemetryMiddleware } from '../telemetry-middleware';

package/src/telemetry-middleware.ts

@@ -0,0 +1,67 @@
+import type { PlanMeta } from '@prisma-next/contract/types';
+import type {
+  AfterExecuteResult,
+  RuntimeMiddleware,
+  RuntimeMiddlewareContext,
+} from '@prisma-next/framework-components/runtime';
+
+export interface TelemetryEvent {
+  readonly phase: 'beforeExecute' | 'afterExecute';
+  readonly lane: string;
+  readonly target: string;
+  readonly storageHash: string;
+  readonly rowCount?: number;
+  readonly latencyMs?: number;
+  readonly completed?: boolean;
+}
+
+export interface TelemetryMiddlewareOptions {
+  readonly onEvent?: (event: TelemetryEvent) => void;
+}
+
+export function createTelemetryMiddleware(options?: TelemetryMiddlewareOptions): RuntimeMiddleware {
+  const emit = (event: TelemetryEvent, ctx: RuntimeMiddlewareContext) => {
+    try {
+      if (options?.onEvent) {
+        options.onEvent(event);
+      } else {
+        ctx.log.info(event);
+      }
+    } catch (error) {
+      ctx.log.warn({ message: 'telemetry sink error', error, event });
+    }
+  };
+
+  return {
+    name: 'telemetry',
+    async beforeExecute(plan: { readonly meta: PlanMeta }, ctx: RuntimeMiddlewareContext) {
+      emit(
+        {
+          phase: 'beforeExecute',
+          lane: plan.meta.lane,
+          target: plan.meta.target,
+          storageHash: plan.meta.storageHash,
+        },
+        ctx,
+      );
+    },
+    async afterExecute(
+      plan: { readonly meta: PlanMeta },
+      result: AfterExecuteResult,
+      ctx: RuntimeMiddlewareContext,
+    ) {
+      emit(
+        {
+          phase: 'afterExecute',
+          lane: plan.meta.lane,
+          target: plan.meta.target,
+          storageHash: plan.meta.storageHash,
+          rowCount: result.rowCount,
+          latencyMs: result.latencyMs,
+          completed: result.completed,
+        },
+        ctx,
+      );
+    },
+  };
+}