@glasstrace/sdk 1.15.0 → 1.16.0

package/README.md

@@ -363,6 +363,49 @@ A future SDK release may extend the auto-attach detection to recognize
 additional Next 16 provider shapes; until that ships, the manual path
 above is the production-supported integration.
 
+## Database query spans (Prisma)
+
+When Glasstrace manages the OpenTelemetry provider — the default when
+your app does not already run its own OpenTelemetry or Sentry setup — it
+automatically instruments [Prisma](https://www.prisma.io/) queries.
+Install
+[`@prisma/instrumentation`](https://www.npmjs.com/package/@prisma/instrumentation)
+(an optional peer dependency, Prisma 4–7) and query spans appear once the
+package is reachable; no extra wiring is required.
+
+If Glasstrace instead detects a provider you already registered (Sentry,
+a custom OpenTelemetry SDK, and similar), it attaches its exporter to
+that provider rather than taking over instrumentation — so it does not
+add Prisma instrumentation itself, and the diagnostic below does not
+apply. Register `@prisma/instrumentation` on your own provider;
+Glasstrace exports the spans it produces.
+
+Prisma ORM versions **4.2.0 through 6.1.0** additionally require enabling
+the `tracing`
+[preview feature](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing)
+in your schema's `generator` block — `previewFeatures = ["tracing"]` —
+before any tracing spans are emitted. Later Prisma versions need no flag.
+
+**Missing Prisma query spans?** On Prisma 4.2.0–6.1.0, first confirm the
+`tracing` preview feature above is enabled. Otherwise, the usual cause is
+a package manager that does not expose transitive copies of optional
+peers. Under pnpm's
+strict, isolated `node_modules`, `@prisma/instrumentation` can sit in
+the virtual store (pulled in by another dependency) without being
+linked into your app's `node_modules/@prisma/` — so the SDK's optional
+import resolves to nothing and Prisma spans are silently skipped. Add it
+as a **direct dependency** of your app:
+
+```bash
+npm install @prisma/instrumentation
+# pnpm add @prisma/instrumentation
+```
+
+To confirm whether it was loaded, enable verbose mode
+(`registerGlasstrace({ verbose: true })`): when
+`@prisma/instrumentation` cannot be loaded, the SDK logs a diagnostic
+noting that Prisma query spans will not be captured.
+
 ## Capturing error response bodies
 
 When debugging a 4xx or 5xx, the response body is often the most useful
@@ -627,6 +670,63 @@ ingestion service before persistence. This is intentional
 defense-in-depth: the SDK is the first gate; the product receiver
 is the second.
 
+### Value-fidelity scalars
+
+Beyond the categorical `fields` channel, `recordSideEffect()` accepts an
+optional `scalars` map for type-aware magnitudes emitted on a separate
+`glasstrace.side_effect.scalar.*` channel. The key suffix declares the
+value type:
+
+- `*Ms` / `*Amount` / `*Bytes` / `*Ratio` / `*Value` → a finite `number`
+- `*Flag` → a `boolean`
+- `*Id` → a pseudonymized `gthid_` string (see `hashId` below)
+
+(`Count` stays on the categorical `fields` channel; free-form string
+enums belong there too, not on the scalar channel.)
+
+```ts
+import { recordSideEffect } from "@glasstrace/sdk";
+import { hashId } from "@glasstrace/sdk/node";
+
+recordSideEffect({
+  kind: "external_api",
+  operation: "charge.create",
+  status: "succeeded",
+  scalars: {
+    latencyMs: 142, // bounded delta — not a wall-clock epoch
+    amountValue: 1999, // a magnitude
+    retriedFlag: false, // a boolean condition
+    // Identifiers must be pseudonymized; raw ids are rejected.
+    customerId: hashId(rawCustomerId, process.env.GLASSTRACE_ATTR_HMAC_KEY!),
+  },
+});
+```
+
+Scalars are validated at emit time under a **fail-closed `strict`**
+posture. (An account-level `captureFidelity` setting that can relax the
+timestamp/identifier rejections is part of the wire contract but is **not
+active in this release** — scalars are always validated as `strict`
+here.) Under `strict` the SDK rejects values that would leak raw,
+high-cardinality data before they reach the wire, recording only an
+integer omission count:
+
+| Rejected value | Omission reason |
+|---|---|
+| A `Date`, or a raw epoch on a `*Ms` key | `raw_timestamp` |
+| A non-`gthid_` value on an `*Id` key | `unhashed_id` |
+| `NaN` / `±Infinity` | `non_finite` |
+| A value whose type doesn't match its key suffix (e.g. a string or boolean on `*Ms`) | `raw_payload` |
+| A key not matching the scalar pattern | `unsupported_key` |
+| More than 16 scalars in one call (the excess are dropped) | `value_too_long` |
+
+Send **bounded deltas as numbers** (e.g. `latencyMs: 142`), not absolute
+timestamps. Note that raw-epoch screening applies only to `*Ms` keys (the
+time-typed suffix) — keep wall-clock values off other numeric suffixes.
+Pseudonymize identifiers with **`hashId`** (HMAC-SHA256, fixed-shape
+`gthid_<hex>`, fail-closed — returns `null` without a key), which ships on
+the Node-only `@glasstrace/sdk/node` subpath because it uses
+`node:crypto`. At most 16 scalars are recorded per operation.
+
 ## Source maps
 
 Glasstrace uploads server-side source maps at build time and resolves
@@ -798,7 +898,7 @@ without a deprecation cycle. Rely on the static file.
 
 ## Subpath exports
 
-`@glasstrace/sdk` ships four public entries:
+`@glasstrace/sdk` ships six public entries:
 
 - **`@glasstrace/sdk`** — primary import site. Use from
   `instrumentation.ts` (runtime instrumentation) and `next.config.ts`
@@ -810,14 +910,19 @@ without a deprecation cycle. Rely on the static file.
   runtimes; workloads running strictly on workerd or Vercel Edge
   should import from the internal edge-entry bundle — not currently
   exposed as a public entry — or ask for a public `/edge` subpath.
-- **`@glasstrace/sdk/node`** — Node-only build-time tooling
-  (source-map uploading, import-graph construction). Use from
-  `next.config.ts` / build scripts. Resolves only under the Node
-  condition; non-Node runtimes (workerd, edge-light) fail cleanly at
-  module resolution rather than at evaluation.
+- **`@glasstrace/sdk/node`** — Node-only helpers: build-time tooling
+  (source-map uploading, import-graph construction) plus the request-time
+  `hashId` identifier-pseudonymization helper for value-fidelity scalars.
+  Resolves only under the Node condition; non-Node runtimes (workerd,
+  edge-light) fail cleanly at module resolution rather than at
+  evaluation.
 - **`@glasstrace/sdk/drizzle`** — Drizzle ORM adapter.
 - **`@glasstrace/sdk/trpc`** — tRPC middleware-chain instrumentation.
   See "tRPC middleware instrumentation" below.
+- **`@glasstrace/sdk/middleware`** — request-middleware tracing wrapper
+  (`tracedRequestMiddleware`).
+- **`@glasstrace/sdk/async-context`** — async causality propagation
+  (`withAsyncCausality`).
 
 The source-map and import-graph helpers previously reachable from the
 `@glasstrace/sdk` root specifier have moved to `@glasstrace/sdk/node`
@@ -863,11 +968,15 @@ and the recommended call site.
 | `discoverTestFiles` | function | `node:fs`, `node:path` | — (call from a build script / CI job) |
 | `extractImports` | function | — (pure string processing) | — (kept under `/node` for API cohesion with `buildImportGraph`) |
 | `buildImportGraph` | function | `node:fs`, `node:path`, `node:crypto` | — (call from a build script / CI job) |
+| `hashId` | function | `node:crypto` | — (call from the request handler that records the side effect) |
 
 Type exports erase at runtime and are technically safe to import from
 edge code, but every runtime function that produces or consumes them is
-Node-only, so the practical signal is the same: reach for these from
-your build pipeline, not from a request handler.
+Node-only, so the practical signal is the same: reach for the source-map
+and import-graph helpers from your build pipeline, not from a request
+handler. `hashId` is the exception — it is a request-time helper for
+pseudonymizing identifiers before `recordSideEffect()`, Node-only only
+because it uses `node:crypto`.
 
 #### Why is X Node-only?
 

package/dist/async-context/index.cjs

@@ -15297,7 +15297,20 @@ var CaptureConfigSchema = external_exports.object({
    * client-side allowlist enforcement layered with the product's
    * storage-time filter as defense-in-depth.
    */
-  sideEffectEvidence: external_exports.boolean().optional().default(false)
+  sideEffectEvidence: external_exports.boolean().optional().default(false),
+  /**
+   * Per-account value-fidelity capture posture (server-pushed).
+   *
+   * `strict` (default) is fail-closed: the SDK rejects raw wall-clock
+   * timestamps and unhashed identifiers from the `scalar.*` channel at
+   * emit time. `full` relaxes those rejections so raw magnitudes can be
+   * surfaced — but only in conjunction with an explicit producer opt-in
+   * (so a `full`-configured account still emits strict-shaped scalars
+   * unless the producer also opts in). The operator owns this flag; it
+   * is never derived from producer or request input. Absent on the wire
+   * ⇒ `strict`.
+   */
+  captureFidelity: external_exports.enum(["strict", "full"]).optional().default("strict")
 });
 var SdkCachedConfigSchema = external_exports.object({
   response: external_exports.record(external_exports.string(), external_exports.unknown()),
@@ -15488,7 +15501,13 @@ var GLASSTRACE_ATTRIBUTE_NAMES = {
   SIDE_EFFECT_OMITTED_UNSUPPORTED_KEY: "glasstrace.side_effect.omitted.unsupported_key",
   SIDE_EFFECT_OMITTED_VALUE_TOO_LONG: "glasstrace.side_effect.omitted.value_too_long",
   SIDE_EFFECT_OMITTED_NOT_EMITTED: "glasstrace.side_effect.omitted.not_emitted",
-  SIDE_EFFECT_OMITTED_CAPTURE_DISABLED: "glasstrace.side_effect.omitted.capture_disabled"
+  SIDE_EFFECT_OMITTED_CAPTURE_DISABLED: "glasstrace.side_effect.omitted.capture_disabled",
+  // Value-fidelity scalar-channel omission reasons. Counts only; the
+  // rejected raw value (timestamp, unhashed id, non-finite number) is
+  // never echoed. Mirror the product omission enum verbatim.
+  SIDE_EFFECT_OMITTED_RAW_TIMESTAMP: "glasstrace.side_effect.omitted.raw_timestamp",
+  SIDE_EFFECT_OMITTED_UNHASHED_ID: "glasstrace.side_effect.omitted.unhashed_id",
+  SIDE_EFFECT_OMITTED_NON_FINITE: "glasstrace.side_effect.omitted.non_finite"
 };
 var MAX_SOURCE_MAP_FILE_PATH_LENGTH = 512;
 var MAX_SOURCE_MAP_FILE_SIZE = 50 * 1024 * 1024;