@edraj/sauron-node 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 All notable changes to `@edraj/sauron-node` are documented here.
 
+## 1.5.0
+
+### Added
+
+- **`tags` and `extra` on transactions.** `trackTransaction` now accepts two
+  developer-supplied maps: `tags` (flat string→string, indexed) and `extra`
+  (freeform JSON). `extra` is where a request body, a response body, an order
+  id or a retry count goes — the span that times an HTTP call can now carry
+  what the call actually sent and received.
+
+  Both are visible on the new **Transactions** page and in the session
+  timeline, and both are searchable: `@tag.tier:premium`,
+  `extra.order_id:9001`, or `extra.response:~9001` to match a substring
+  *inside* a stored response body.
+
+  **They are per-call only.** Unlike `captureException` and `track`, a
+  transaction does not inherit the scope — `setTag()` / `setExtra()` defaults
+  are not merged in. Transactions are the highest-volume signal an app emits,
+  one per navigation and per request, so inheriting a global blob would write
+  it onto every row. This asymmetry is deliberate and is documented on the
+  method.
+
+  `extra` is serialized and capped at **16 KB**. Past that the whole map is
+  replaced with a `{"_truncated": true, "_bytes": N}` marker, and the
+  dashboard says so on the row rather than showing a short object that looks
+  complete. The cap is not cosmetic: envelopes are batched, and one oversized
+  body would push the whole envelope past the ingest limit and take every
+  unrelated span sent with it — a silent loss of data nobody asked about.
+  Size is measured in UTF-8 bytes, so non-ASCII payloads are counted at what
+  they actually cost on the wire.
+
+  Nothing in `extra` is scrubbed. `beforeSend` remains the redaction seam;
+  think twice before attaching a body that can carry tokens or personal data.
+
+  An app that sets neither field serializes byte-identically to before: both
+  keys are omitted when empty, never sent as `null`.
+
+  Signature: `trackTransaction({ …, tags?: Record<string, string>, extra?: Record<string, unknown> })`. `MAX_TRANSACTION_EXTRA_BYTES` and `capTransactionExtra` are now exported from the package entrypoint, so a caller can size a payload before attaching it.
+
+## 1.4.0
+
+### Fixed
+
+- **`trackTransaction` shipped transactions with no duration, silently.** This
+  SDK's input field is `duration_ms`; the browser SDK's is `durationMs`. A
+  snippet moved between the two — or any plain-JavaScript caller, where the type
+  checker is not there to object — produced a transaction item missing the one
+  field it exists to carry, and nothing anywhere complained: the item validated,
+  shipped, and looked delivered.
+
+  `durationMs` is now accepted as an alias, and a transaction with no usable
+  duration is **dropped with a debug log line rather than sent**. Refusing is the
+  point: sending it anyway is what let the misspelling survive unnoticed.
+  `duration_ms: 0` is a legitimate duration and is still sent.
+
+### Changed
+
+- `TransactionInput.duration_ms` is now optional, since `durationMs` may supply
+  it instead. Supply exactly one — `duration_ms` wins if both are present.
+  Supplying neither is the drop above, not a compile error.
+
 ## 1.3.0
 
 ### Added

package/README.md

@@ -275,10 +275,28 @@ function trackTransaction(input: TransactionInput): void
 | `input.http_status` | `number` | omitted | e.g. `200`. |
 | `input.url` | `string` | omitted | Request URL/path. |
 | `input.distinct_id` | `string` | scope user's `id`, else omitted | Explicit value wins over the scope. |
+| `input.tags` | `Record<string, string>` | omitted | Indexed string→string labels. Filter with `@tag.key:value` on the Transactions page. |
+| `input.extra` | `Record<string, unknown>` | omitted | Freeform JSON — request body, response body, SQL text, row counts. Searchable with `extra.key:value`. |
 
 Emits a `transaction` item. Absent optional fields are omitted from the wire JSON
 rather than serialized as `null`. Returns `void`.
 
+**`tags` and `extra` are per-call only.** Unlike `track()` and
+`captureException()`, a transaction does **not** inherit the scope:
+`setTag()` / `setExtra()` defaults are not merged in. Transactions are the
+highest-volume signal a service emits — one per request and per query — so
+inheriting a global blob would write it onto every row.
+
+`extra` is serialized and capped at **16 KB**
+(`MAX_TRANSACTION_EXTRA_BYTES`, exported from `transaction-extra`). Past that
+the whole map is replaced with `{ _truncated: true, _bytes: N }` and the
+dashboard says so on the row. The cap is not cosmetic: envelopes are batched,
+and one oversized body would push the whole envelope past the ingest limit and
+drop every unrelated span sent with it.
+
+Nothing in `extra` is scrubbed. Use `beforeSend` for redaction, and think twice
+before attaching a body that can carry tokens, passwords or personal data.
+
 ```ts
 const started = Date.now();
 await handler(req, res);
@@ -293,6 +311,128 @@ trackTransaction({
 });
 ```
 
+#### Example: an Express route, with request and response bodies
+
+`res.json` is wrapped rather than read afterwards, because by the time the
+`finish` event fires the payload is already on the wire and gone.
+
+```ts
+import express from 'express';
+import { trackTransaction } from '@edraj/sauron-node';
+
+export function tracedRoute(routeLabel: string, handler: express.RequestHandler) {
+  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const started = Date.now();
+    let responseBody: unknown;
+
+    // Capture on the way out. Reading it in `finish` is too late — the body
+    // has already been serialized and released by then.
+    const json = res.json.bind(res);
+    res.json = (body: unknown) => {
+      responseBody = body;
+      return json(body);
+    };
+
+    res.on('finish', () => {
+      trackTransaction({
+        name: routeLabel,              // 'POST /orders', NOT '/orders/8412'
+        op: 'http',
+        duration_ms: Date.now() - started,
+        http_method: req.method,
+        http_status: res.statusCode,
+        url: req.originalUrl,
+        status: res.statusCode < 400 ? 'ok' : 'error',
+        distinct_id: (req as { userId?: string }).userId,
+        tags: { route: routeLabel, tier: (req as { plan?: string }).plan ?? 'free' },
+        extra: {
+          request: req.body,
+          response: responseBody,
+          query: req.query,
+          // Header VALUES are omitted on purpose — `authorization` and
+          // `cookie` live there.
+          request_headers: Object.keys(req.headers),
+        },
+      });
+    });
+
+    try {
+      await handler(req, res, next);
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+const app = express();
+app.post('/orders', tracedRoute('POST /orders', createOrder));
+```
+
+On the dashboard: **Transactions → the row → expand**. Both bodies render as a
+JSON tree, and every one of these finds it:
+
+```text
+extra.response:~9001        # substring, inside the stored response body
+@tag.route:"POST /orders"   # indexed tag
+op:http http.status:>=500   # the failures
+duration:>2s                # the slow ones
+```
+
+#### Example: a SQL query (`pg`)
+
+Put the **statement** in `extra` and keep `name` a stable label — a query with
+literals baked in would mint a new dashboard row per execution.
+
+```ts
+import { Pool } from 'pg';
+import { trackTransaction } from '@edraj/sauron-node';
+
+const pool = new Pool();
+
+export async function tracedQuery<T>(label: string, sql: string, params: unknown[] = []) {
+  const started = Date.now();
+  try {
+    const result = await pool.query<T>(sql, params);
+    trackTransaction({
+      // The LABEL, not the statement. `op` is free-form on this SDK, so a
+      // 'db' op is stored as-is — but note the browser SDK coerces anything
+      // outside navigation|http|resource|screen_load|custom to 'custom', so
+      // use a tag if you need the two to agree.
+      name: label,
+      op: 'db',
+      duration_ms: Date.now() - started,
+      status: 'ok',
+      tags: { db: 'postgres', table: 'orders' },
+      extra: {
+        statement: sql,
+        row_count: result.rowCount,
+        // Bind PARAMETERS are user data. Log them only if you have decided
+        // that is acceptable, or log their shape instead.
+        params,
+      },
+    });
+    return result;
+  } catch (err) {
+    trackTransaction({
+      name: label,
+      op: 'db',
+      duration_ms: Date.now() - started,
+      status: 'error',
+      tags: { db: 'postgres', table: 'orders' },
+      extra: { statement: sql, error: String(err) },
+    });
+    throw err;
+  }
+}
+
+await tracedQuery(
+  'SELECT orders',
+  'SELECT id, total FROM orders WHERE user_id = $1 ORDER BY created_at DESC LIMIT 20',
+  [userId],
+);
+```
+
+Then `@tag.table:orders duration:>500ms` is your slow-query list.
+
 ### `addBreadcrumb(crumb)`
 
 ```ts

package/dist/client.js

@@ -6,6 +6,7 @@ import { parseError } from './stacktrace.js';
 import { installAutoCapture, installShutdownHooks } from './autocapture.js';
 import { getCurrentScope, getGlobalScope, normalizeBreadcrumb, } from './scope.js';
 import { normalizeReason, normalizeWorkflowName } from './workflow.js';
+import { capTransactionExtra } from './transaction-extra.js';
 const DEFAULTS = {
     release: null,
     sampleRate: 1,
@@ -179,12 +180,25 @@ export class SauronClient {
     trackTransaction(input) {
         if (typeof input?.name !== 'string' || input.name.length === 0)
             return;
+        // `durationMs` accepted as an alias — see TransactionInput. Without it, a
+        // caller using the browser SDK's spelling shipped a transaction with the
+        // duration field absent and no complaint from anywhere.
+        const duration = input.duration_ms ?? input.durationMs;
+        if (typeof duration !== 'number' || !Number.isFinite(duration)) {
+            // Refused loudly rather than sent. A transaction whose whole purpose is
+            // to record a duration is not worth persisting without one, and silence
+            // here is what let the mis-spelling survive: the item looked delivered.
+            this.debugLog(`dropped transaction "${input.name}": duration_ms must be a finite number ` +
+                `(got ${typeof duration === 'number' ? duration : typeof duration}). ` +
+                `Use duration_ms, or durationMs if you are porting from the browser SDK.`);
+            return;
+        }
         const distinctId = input.distinct_id ?? getCurrentScope().data.user?.id ?? undefined;
         const item = {
             type: 'transaction',
             name: input.name,
             op: input.op ?? 'custom',
-            duration_ms: input.duration_ms,
+            duration_ms: duration,
             timestamp: isoNow(),
         };
         if (input.status !== undefined)
@@ -197,6 +211,15 @@ export class SauronClient {
             item.url = input.url;
         if (distinctId != null)
             item.distinct_id = distinctId;
+        // Per-call only — deliberately no `globalScope.tags`/`.extra` merge here,
+        // unlike `track()` and `captureException` below. See TransactionInput.
+        // Omitted when empty so an app that never sets them is byte-identical on
+        // the wire to before these fields existed.
+        if (input.tags && Object.keys(input.tags).length > 0)
+            item.tags = { ...input.tags };
+        if (input.extra && Object.keys(input.extra).length > 0) {
+            item.extra = capTransactionExtra({ ...input.extra });
+        }
         this.dispatch(item);
     }
     /** Capture a product-analytics event. `distinctId` is required. */

package/dist/index.d.ts

@@ -77,3 +77,4 @@ export declare function setExtra(key: string, value: unknown): void;
 export declare function flush(): Promise<void>;
 /** Flush and stop the background timer, then clear the active client. */
 export declare function close(): Promise<void>;
+export { MAX_TRANSACTION_EXTRA_BYTES, capTransactionExtra, } from './transaction-extra.js';

package/dist/index.js

@@ -112,3 +112,6 @@ export async function close() {
     activeClient = null;
     await client.close();
 }
+// Exported so a caller can size a payload BEFORE attaching it — the cap is
+// otherwise invisible until the dashboard shows a truncation marker.
+export { MAX_TRANSACTION_EXTRA_BYTES, capTransactionExtra, } from './transaction-extra.js';

package/dist/transaction-extra.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The size cap on a transaction's developer-supplied `extra`.
+ *
+ * Its own module rather than a private helper inside `client.ts` so the limit
+ * and its behaviour are directly testable — the failure this guards against
+ * (an oversized payload taking a whole batched envelope down with it) is not
+ * visible from the outside once it happens.
+ */
+/**
+ * Largest serialized `extra` a single transaction may carry, in bytes.
+ *
+ * Transactions are the highest-volume signal and they ship in BATCHED
+ * envelopes, so one oversized payload does not fail alone — ingest rejects the
+ * whole envelope past `INGEST_MAX_BODY_BYTES` (1 MiB by default) and every
+ * unrelated span batched with it is lost. Since the motivating use of
+ * transaction `extra` is request and response bodies, that is not a remote
+ * hazard.
+ *
+ * Kept identical across all five SDKs. If it moves, it moves everywhere.
+ */
+export declare const MAX_TRANSACTION_EXTRA_BYTES: number;
+/**
+ * Cap a transaction's `extra`, substituting a marker when it is too large.
+ *
+ * Replaces the WHOLE map rather than trimming keys: a half-written JSON value
+ * is worse than an honest marker, and per-key trimming would make the result
+ * depend on key iteration order, which differs across the five SDKs. The marker
+ * is deliberately readable on the dashboard — `_truncated` says data was
+ * dropped rather than silently serving a short object that looks complete.
+ *
+ * A value that cannot be serialized at all (a cycle, a BigInt) becomes the same
+ * marker with `_bytes: -1`, because the alternative is throwing from inside
+ * `trackTransaction` — and an SDK that crashes the app it is measuring is worse
+ * than one that drops a payload.
+ */
+export declare function capTransactionExtra(extra: Record<string, unknown>, maxBytes?: number): Record<string, unknown>;

package/dist/transaction-extra.js

@@ -0,0 +1,53 @@
+/**
+ * The size cap on a transaction's developer-supplied `extra`.
+ *
+ * Its own module rather than a private helper inside `client.ts` so the limit
+ * and its behaviour are directly testable — the failure this guards against
+ * (an oversized payload taking a whole batched envelope down with it) is not
+ * visible from the outside once it happens.
+ */
+/**
+ * Largest serialized `extra` a single transaction may carry, in bytes.
+ *
+ * Transactions are the highest-volume signal and they ship in BATCHED
+ * envelopes, so one oversized payload does not fail alone — ingest rejects the
+ * whole envelope past `INGEST_MAX_BODY_BYTES` (1 MiB by default) and every
+ * unrelated span batched with it is lost. Since the motivating use of
+ * transaction `extra` is request and response bodies, that is not a remote
+ * hazard.
+ *
+ * Kept identical across all five SDKs. If it moves, it moves everywhere.
+ */
+export const MAX_TRANSACTION_EXTRA_BYTES = 16 * 1024;
+/**
+ * Cap a transaction's `extra`, substituting a marker when it is too large.
+ *
+ * Replaces the WHOLE map rather than trimming keys: a half-written JSON value
+ * is worse than an honest marker, and per-key trimming would make the result
+ * depend on key iteration order, which differs across the five SDKs. The marker
+ * is deliberately readable on the dashboard — `_truncated` says data was
+ * dropped rather than silently serving a short object that looks complete.
+ *
+ * A value that cannot be serialized at all (a cycle, a BigInt) becomes the same
+ * marker with `_bytes: -1`, because the alternative is throwing from inside
+ * `trackTransaction` — and an SDK that crashes the app it is measuring is worse
+ * than one that drops a payload.
+ */
+export function capTransactionExtra(extra, maxBytes = MAX_TRANSACTION_EXTRA_BYTES) {
+    let bytes;
+    try {
+        const json = JSON.stringify(extra);
+        if (json === undefined)
+            return { _truncated: true, _bytes: -1 };
+        // UTF-8 byte length, not `json.length`: the latter undercounts every
+        // non-ASCII byte, which is exactly what a response body full of user text
+        // is made of.
+        bytes = Buffer.byteLength(json, 'utf8');
+    }
+    catch {
+        return { _truncated: true, _bytes: -1 };
+    }
+    if (bytes <= maxBytes)
+        return extra;
+    return { _truncated: true, _bytes: bytes };
+}

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { maybeGzip } from './gzip.js';
 import { BoundedQueue } from './queue.js';
 const SDK_NAME = 'sauron-node';
-const SDK_VERSION = '1.3.0';
+const SDK_VERSION = '1.5.0';
 /** Default exponential-backoff base (ms) for the first retry. */
 const DEFAULT_RETRY_BASE_MS = 200;
 /** Hard cap on any single backoff delay (ms). */

package/dist/types.d.ts

@@ -161,19 +161,66 @@ export interface TransactionItem {
     workflow_id?: string;
     workflow_name?: string;
     timestamp: string;
+    /**
+     * Developer-supplied flat string tags for THIS transaction. NOT merged with
+     * the scope — see {@link TransactionInput.tags}. Omitted when empty.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Developer-supplied freeform JSON for THIS transaction. Capped and replaced
+     * with a truncation marker past `MAX_TRANSACTION_EXTRA_BYTES`. Omitted when
+     * empty.
+     */
+    extra?: Record<string, unknown>;
 }
 /** Caller input for {@link TransactionItem} via `trackTransaction`. */
 export interface TransactionInput {
     name: string;
     /** Operation class: `navigation | http | resource | screen_load | custom`. Default `custom`. */
     op?: string;
-    duration_ms: number;
+    duration_ms?: number;
+    /**
+     * Accepted alias for {@link duration_ms}.
+     *
+     * The browser SDK's equivalent input takes `durationMs` (`sdks/js`), so a
+     * snippet moved between the two — or any plain-JavaScript caller, where the
+     * type checker is not there to object — used to produce a transaction with no
+     * duration at all. The item still validated and still shipped, just without
+     * the one field it exists to carry, which is the worst possible outcome: no
+     * error anywhere and a silently useless performance record.
+     *
+     * Supply exactly one. `duration_ms` wins if both are present.
+     */
+    durationMs?: number;
     status?: string;
     http_method?: string;
     http_status?: number;
     url?: string;
     /** Falls back to the scoped user's id when omitted. */
     distinct_id?: string;
+    /**
+     * Flat string tags for this transaction.
+     *
+     * **Per-call only — the scope is NOT merged in**, which is the one place
+     * transactions differ from `track()` and `captureException()`. Those two
+     * merge `setTag`/`setExtra` defaults; a transaction carries only what its own
+     * call site attached. Transactions are the highest-volume signal (one per
+     * navigation and per HTTP call), so inheriting a global blob would write it
+     * onto every row.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Freeform JSON for this transaction — the request body, the response body,
+     * an order id, a retry count.
+     *
+     * Per-call only, for the reason on {@link TransactionInput.tags}. Serialized
+     * and capped at `MAX_TRANSACTION_EXTRA_BYTES`; past that the whole map is
+     * replaced with `{ _truncated: true, _bytes: N }` so one large body cannot
+     * take a batched envelope over the ingest limit and drop every span in it.
+     *
+     * Nothing here is scrubbed. `beforeSend` is the redaction seam.
+     */
+    extra?: Record<string, unknown>;
 }
 /** Any item that can appear in an envelope's `items` array. */
 export type EnvelopeItem = ErrorItem | EventItem | IdentifyItem | TransactionItem;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edraj/sauron-node",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Sauron server-side Node/TypeScript SDK: product-analytics events + exception capture for Node backends.",
   "homepage": "https://github.com/edraj/sauron/tree/main/sdks/node#readme",
   "repository": {