@dasasian/firebase-structured-logger 1.1.0 → 1.2.0

package/README.md

@@ -675,6 +675,77 @@ enableNavigation({ cleanPath: (path) => path.replace(/[^/]+@[^/]+/g, ':email') }
 enableNavigation({ path: false })
 ```
 
+## Timing: when something is too slow
+
+Some failures never throw. A loading screen waits on eight pieces, one of them takes 30
+seconds, and the logs say nothing — because nothing failed. Traces report exactly that
+case, and only that case: something took longer than you said it should, or never
+finished. A trace that finishes in time sends nothing at all.
+
+```ts
+import { trace, startTrace } from '@dasasian/firebase-structured-logger/client/timing'
+
+await trace('app_boot', async (boot) => {
+  const user = await boot.step('sign-in', () => signIn())
+  await Promise.all([
+    boot.step('products', () => loadProducts(user)),
+    boot.step('places', () => loadPlaces(user)),
+  ])
+})
+
+// A flow that spans functions — a screen that starts on mount and ends when its data is in
+const open = startTrace('order_open')
+await open.step('order', () => loadOrder(id))
+open.end()
+```
+
+Your code holds names only. The limits live in one place, set once at startup:
+
+```ts
+import { configureTraces } from '@dasasian/firebase-structured-logger/client/timing'
+
+configureTraces({
+  app_boot:   { warnAfterMs: 8000, steps: { products: 3000 } },
+  order_open: { warnAfterMs: 2000 },
+})
+```
+
+A trace with no limits configured is timed but never reported. Limits are read when a run
+starts, so configure before the first one.
+
+**What gets sent.** One `WARNING` per run, the moment the first limit is crossed — the
+trace's, or a step's own — while it is still running, so a step that never finishes is
+reported too. Nothing more is sent for that run afterwards.
+
+```
+WARNING  app_boot slow: products passed 3000 ms, still waiting
+         labels.trace="app_boot"  labels.run="<id>"  labels.slow="step"  labels.step="products"
+         timing: { elapsedMs: 3000, limitMs: 3000,
+                   steps: { sign-in: 610, places: 410 }, waiting: ["products"] }
+```
+
+`labels.slow` is `"trace"` or `"step"`. Durations are in milliseconds, always in `timing`.
+`labels.run` tells two overlapping runs of the same trace apart.
+
+**What is never judged.** A browser pauses pages it is not showing: a hidden tab, a phone
+switching apps, a laptop going to sleep. Time spent paused is not your app being slow, so
+a run that was hidden at any point, or that was paused — a one-second check that arrives
+five or more seconds late — is not reported. Laptop sleep often fires no event at all,
+which is why the late check exists.
+
+**Underneath** each step is a standard `performance.mark` and `performance.measure`, so
+it shows in the browser's Performance panel and in other tools that read them. Ours are
+cleared when the run ends. A `step` after `end()`, or a second `end()`, is ignored.
+
+**On the server**, `trace` and `startTrace` come from `/functions`, with the same entry. A
+server run is judged when a step or the trace ends — there is no timer, because Cloud
+Functions and Cloud Run can throttle the CPU once a response is sent. A request that hangs
+outright is ended by the platform's timeout, which logs it. Inside `withLogging`, the entry
+carries that request's labels like any other.
+
+Traces explain the slow case; they do not measure what is normal. There are no
+percentiles here and no sampling — if you need those, that is a monitoring tool's job.
+
 ## User feedback
 
 ```ts
@@ -922,6 +993,7 @@ Narrow it when you need to:
 | `labels.truncated="true"` | entries shortened to fit — the full copy is `fsl-overflow.json` |
 | `labels.repeatKey="<key>" OR labels.repeatOf="<key>"` | one repeating error: its full copies and its summaries |
 | `labels.sentLate="true"` | repeat summaries sent on a later visit |
+| `labels.trace="app_boot"` | slow runs of one trace — `labels.slow` says whether the trace or a step was late |
 
 Locally, the emulator's JSONL answers the same questions. Point
 **[firebase-mcp-server](https://github.com/dasasian/firebase-mcp-server)** at either and ask
@@ -959,6 +1031,9 @@ Optional helpers are separate entry points, so an app ships only what it imports
 ```ts
 import { enableNavigation } from '@dasasian/firebase-structured-logger/client/navigation'
 enableNavigation({ routeFor?, cleanPath?, path? })   // see "Navigation, automatically"
+
+import { trace, startTrace, configureTraces } from '@dasasian/firebase-structured-logger/client/timing'
+configureTraces({ name: { warnAfterMs?, steps?: { step: ms } } })   // see "Timing"
 ```
 
 Also exported: `initLogger`, `getClientLogger`, `setupGlobalErrorHandler`, `handleReactError`,
@@ -993,6 +1068,8 @@ getLogger()                       // the current request's writer, or an anonymo
 logError / logWarn / logInfo / logDebug (message, labels?, context?, attachments?)
 
 configureAttachments({ bucket?, prefix? })    // once, at module load — see Attachments
+configureTraces({ name: { warnAfterMs?, steps? } })   // once — see "Timing"
+trace(name, async (t) => { await t.step(name, fn) })   // or startTrace(name) … .end()
 
 // Receiving client logs. All three take the same source-map config:
 //   { bucket?, sourceMaps?: { bucket?, prefix? } }

package/dist/client/timing.d.ts

@@ -0,0 +1,20 @@
+import { type TraceConfig } from '../shared/trace';
+export type { TraceConfig, TraceLimits } from '../shared/trace';
+/**
+ * `@dasasian/firebase-structured-logger/client/timing` — its own entry point
+ * (CLAUDE.md, "Optional client helpers are separate entry points"), so an app
+ * that never imports it ships none of this. Touches no browser global at module
+ * load — `performance`, `document` and the timers below are only read once a
+ * trace actually starts. See README, "Timing: when something is too slow".
+ */
+export interface Trace {
+    step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    end(): void;
+}
+/** Replaces every limit. Read when a run starts, so configure before the first one. */
+export declare function configureTraces(newConfig: TraceConfig): void;
+/** `startTrace(name)` returns the object; call `.end()` when the flow is over. */
+export declare function startTrace(name: string): Trace;
+/** Runs `fn` with a trace object and ends the trace when `fn` settles, either way. */
+export declare function trace<T>(name: string, fn: (t: Trace) => T | Promise<T>): Promise<T>;
+//# sourceMappingURL=timing.d.ts.map

package/dist/client/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/client/timing.ts"],"names":[],"mappings":"AACA,OAAO,EAAqD,KAAK,WAAW,EAAoB,MAAM,iBAAiB,CAAA;AAEvH,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAM/D;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3D,GAAG,IAAI,IAAI,CAAA;CACZ;AAID,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAE5D;AAqHD,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAE9C;AAED,sFAAsF;AACtF,wBAAsB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOzF"}

package/dist/client/timing.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureTraces = configureTraces;
+exports.startTrace = startTrace;
+exports.trace = trace;
+const logger_1 = require("./logger");
+const trace_1 = require("../shared/trace");
+function newPageLocalRunId() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+let config = {};
+/** Replaces every limit. Read when a run starts, so configure before the first one. */
+function configureTraces(newConfig) {
+    config = newConfig;
+}
+const WATCHDOG_INTERVAL_MS = 1000;
+const LATE_THRESHOLD_MS = 5000;
+const activeRuns = new Set();
+let watchdogId;
+let visibilityWired = false;
+let lastTickAt;
+function now() {
+    return performance.now();
+}
+function markName(run, step, kind) {
+    return `fsl:${run.name}:${run.run}:${step}:${kind}`;
+}
+function disqualifyActiveRuns() {
+    for (const active of activeRuns)
+        active.disqualified = true;
+}
+function onVisibilityChange() {
+    if (document.visibilityState === 'hidden')
+        disqualifyActiveRuns();
+}
+/** No-op outside a browser (Node, SSR) — nothing there can ever go hidden. */
+function wireVisibility() {
+    if (visibilityWired)
+        return;
+    visibilityWired = true;
+    if (typeof document === 'undefined')
+        return;
+    document.addEventListener('visibilitychange', onVisibilityChange);
+}
+function reportRun(run, report) {
+    (0, logger_1.getClientLogger)().warning((0, trace_1.traceMessage)(run.name, report), (0, trace_1.traceLabels)(run.name, run.run, report), (0, trace_1.traceContext)(report));
+}
+function tick() {
+    const nowMs = Date.now();
+    const late = lastTickAt !== undefined && nowMs - lastTickAt - WATCHDOG_INTERVAL_MS >= LATE_THRESHOLD_MS;
+    lastTickAt = nowMs;
+    if (late)
+        disqualifyActiveRuns();
+    for (const active of activeRuns) {
+        if (active.disqualified || active.run.hasReported)
+            continue;
+        const report = active.run.check();
+        if (!report)
+            continue;
+        active.run.markReported();
+        reportRun(active.run, report);
+    }
+}
+function ensureWatchdog() {
+    wireVisibility();
+    if (watchdogId !== undefined)
+        return;
+    lastTickAt = Date.now();
+    watchdogId = setInterval(tick, WATCHDOG_INTERVAL_MS);
+}
+function stopWatchdogIfIdle() {
+    if (activeRuns.size > 0 || watchdogId === undefined)
+        return;
+    clearInterval(watchdogId);
+    watchdogId = undefined;
+}
+async function runStep(run, active, name, fn) {
+    if (run.isEnded)
+        return fn();
+    const startMark = markName(run, name, 'start');
+    const endMark = markName(run, name, 'end');
+    const measureName = markName(run, name, 'measure');
+    active.marks.push(startMark, endMark);
+    active.measures.push(measureName);
+    performance.mark(startMark);
+    run.startStep(name);
+    try {
+        return await fn();
+    }
+    finally {
+        run.endStep(name);
+        performance.mark(endMark);
+        performance.measure(measureName, startMark, endMark);
+    }
+}
+function endRun(run, active) {
+    if (run.isEnded)
+        return;
+    run.end();
+    for (const mark of active.marks)
+        performance.clearMarks(mark);
+    for (const measure of active.measures)
+        performance.clearMeasures(measure);
+    activeRuns.delete(active);
+    stopWatchdogIfIdle();
+}
+function startRun(name) {
+    const run = new trace_1.TraceRun(name, config[name], now, newPageLocalRunId());
+    const active = { run, disqualified: false, marks: [], measures: [] };
+    if (config[name]) {
+        activeRuns.add(active);
+        ensureWatchdog();
+    }
+    return {
+        step: (stepName, fn) => runStep(run, active, stepName, fn),
+        end: () => endRun(run, active),
+    };
+}
+/** `startTrace(name)` returns the object; call `.end()` when the flow is over. */
+function startTrace(name) {
+    return startRun(name);
+}
+/** Runs `fn` with a trace object and ends the trace when `fn` settles, either way. */
+async function trace(name, fn) {
+    const handle = startRun(name);
+    try {
+        return await fn(handle);
+    }
+    finally {
+        handle.end();
+    }
+}
+//# sourceMappingURL=timing.js.map

package/dist/client/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/client/timing.ts"],"names":[],"mappings":"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"}

package/dist/functions/index.d.ts

@@ -3,6 +3,8 @@ export { initLogger } from './logger';
 export type { LogWriter } from './logger';
 export { withLogging, getLogger } from './requestLogger';
 export { configureAttachments } from './sourceMapCache';
+export { trace, startTrace, configureTraces } from './trace';
+export type { Trace, TraceConfig, TraceLimits } from './trace';
 export { createClientLogHandler, createClientLogFunction, ClientLogError } from './logHandler';
 export { createHttpLogHandler } from './httpHandler';
 export type { ClientLogHandlerConfig, ClientLogRequest, LogRequest } from './logHandler';

package/dist/functions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/functions/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACxF,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC1F,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE1E,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAG,IAAkC,CAAA;AACrG,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,KAAG,IAAoC,CAAA;AACxG,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KAAG,IAAiC,CAAA;AAClG,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAG,IAAkC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/functions/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC5D,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC9D,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACxF,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC1F,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE1E,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAG,IAAkC,CAAA;AACrG,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,KAAG,IAAoC,CAAA;AACxG,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KAAG,IAAiC,CAAA;AAClG,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAG,IAAkC,CAAA"}

package/dist/functions/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logDebug = exports.logInfo = exports.logWarn = exports.logError = exports.createHttpLogHandler = exports.ClientLogError = exports.createClientLogFunction = exports.createClientLogHandler = exports.configureAttachments = exports.getLogger = exports.withLogging = exports.initLogger = void 0;
+exports.logDebug = exports.logInfo = exports.logWarn = exports.logError = exports.createHttpLogHandler = exports.ClientLogError = exports.createClientLogFunction = exports.createClientLogHandler = exports.configureTraces = exports.startTrace = exports.trace = exports.configureAttachments = exports.getLogger = exports.withLogging = exports.initLogger = void 0;
 const requestLogger_1 = require("./requestLogger");
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "initLogger", { enumerable: true, get: function () { return logger_1.initLogger; } });
@@ -9,6 +9,10 @@ Object.defineProperty(exports, "withLogging", { enumerable: true, get: function
 Object.defineProperty(exports, "getLogger", { enumerable: true, get: function () { return requestLogger_2.getLogger; } });
 var sourceMapCache_1 = require("./sourceMapCache");
 Object.defineProperty(exports, "configureAttachments", { enumerable: true, get: function () { return sourceMapCache_1.configureAttachments; } });
+var trace_1 = require("./trace");
+Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return trace_1.trace; } });
+Object.defineProperty(exports, "startTrace", { enumerable: true, get: function () { return trace_1.startTrace; } });
+Object.defineProperty(exports, "configureTraces", { enumerable: true, get: function () { return trace_1.configureTraces; } });
 var logHandler_1 = require("./logHandler");
 Object.defineProperty(exports, "createClientLogHandler", { enumerable: true, get: function () { return logHandler_1.createClientLogHandler; } });
 Object.defineProperty(exports, "createClientLogFunction", { enumerable: true, get: function () { return logHandler_1.createClientLogFunction; } });

package/dist/functions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/functions/index.ts"],"names":[],"mappings":";;;AAAA,mDAA2C;AAG3C,mCAAqC;AAA5B,oGAAA,UAAU,OAAA;AAEnB,iDAAwD;AAA/C,4GAAA,WAAW,OAAA;AAAE,0GAAA,SAAS,OAAA;AAC/B,mDAAuD;AAA9C,sHAAA,oBAAoB,OAAA;AAC7B,2CAA8F;AAArF,oHAAA,sBAAsB,OAAA;AAAE,qHAAA,uBAAuB,OAAA;AAAE,4GAAA,cAAc,OAAA;AACxE,6CAAoD;AAA3C,mHAAA,oBAAoB,OAAA;AAKtB,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAoC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;AAAxF,QAAA,QAAQ,YAAgF;AAC9F,MAAM,OAAO,GAAG,CAAC,GAAG,IAAsC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;AAA3F,QAAA,OAAO,WAAoF;AACjG,MAAM,OAAO,GAAG,CAAC,GAAG,IAAmC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;AAArF,QAAA,OAAO,WAA8E;AAC3F,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAoC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;AAAxF,QAAA,QAAQ,YAAgF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/functions/index.ts"],"names":[],"mappings":";;;AAAA,mDAA2C;AAG3C,mCAAqC;AAA5B,oGAAA,UAAU,OAAA;AAEnB,iDAAwD;AAA/C,4GAAA,WAAW,OAAA;AAAE,0GAAA,SAAS,OAAA;AAC/B,mDAAuD;AAA9C,sHAAA,oBAAoB,OAAA;AAC7B,iCAA4D;AAAnD,8FAAA,KAAK,OAAA;AAAE,mGAAA,UAAU,OAAA;AAAE,wGAAA,eAAe,OAAA;AAE3C,2CAA8F;AAArF,oHAAA,sBAAsB,OAAA;AAAE,qHAAA,uBAAuB,OAAA;AAAE,4GAAA,cAAc,OAAA;AACxE,6CAAoD;AAA3C,mHAAA,oBAAoB,OAAA;AAKtB,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAoC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;AAAxF,QAAA,QAAQ,YAAgF;AAC9F,MAAM,OAAO,GAAG,CAAC,GAAG,IAAsC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;AAA3F,QAAA,OAAO,WAAoF;AACjG,MAAM,OAAO,GAAG,CAAC,GAAG,IAAmC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;AAArF,QAAA,OAAO,WAA8E;AAC3F,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAoC,EAAQ,EAAE,CAAC,IAAA,yBAAS,GAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;AAAxF,QAAA,QAAQ,YAAgF"}

package/dist/functions/trace.d.ts

@@ -0,0 +1,13 @@
+import { type TraceConfig } from '../shared/trace';
+export type { TraceConfig, TraceLimits } from '../shared/trace';
+export interface Trace {
+    step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    end(): void;
+}
+/** Replaces every limit. Read when a run starts, so configure before the first one. */
+export declare function configureTraces(newConfig: TraceConfig): void;
+/** `startTrace(name)` returns the object; call `.end()` when the flow is over. */
+export declare function startTrace(name: string): Trace;
+/** Runs `fn` with a trace object and ends the trace when `fn` settles, either way. */
+export declare function trace<T>(name: string, fn: (t: Trace) => T | Promise<T>): Promise<T>;
+//# sourceMappingURL=trace.d.ts.map

package/dist/functions/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/functions/trace.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqD,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAErG,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAE/D,MAAM,WAAW,KAAK;IACpB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3D,GAAG,IAAI,IAAI,CAAA;CACZ;AAID,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAE5D;AAyCD,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAE9C;AAED,sFAAsF;AACtF,wBAAsB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOzF"}

package/dist/functions/trace.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureTraces = configureTraces;
+exports.startTrace = startTrace;
+exports.trace = trace;
+const ulid_1 = require("ulid");
+const requestLogger_1 = require("./requestLogger");
+const trace_1 = require("../shared/trace");
+let config = {};
+/** Replaces every limit. Read when a run starts, so configure before the first one. */
+function configureTraces(newConfig) {
+    config = newConfig;
+}
+function now() {
+    return Date.now();
+}
+/**
+ * Judged only when a step finishes or the trace ends — no timer, since Cloud
+ * Functions and Cloud Run can throttle the CPU once a response is sent (see
+ * CLAUDE.md, "Traces report misbehaviour, nothing else"). Sent through the
+ * request-scoped writer, so it carries that request's labels like any other entry.
+ */
+function report(run, found) {
+    if (!found)
+        return;
+    run.markReported();
+    (0, requestLogger_1.getLogger)().warning((0, trace_1.traceMessage)(run.name, found), (0, trace_1.traceLabels)(run.name, run.run, found), (0, trace_1.traceContext)(found));
+}
+function startRun(name) {
+    const run = new trace_1.TraceRun(name, config[name], now, (0, ulid_1.ulid)());
+    return {
+        async step(stepName, fn) {
+            if (run.isEnded)
+                return fn();
+            run.startStep(stepName);
+            try {
+                return await fn();
+            }
+            finally {
+                const ms = run.endStep(stepName);
+                if (ms !== undefined)
+                    report(run, run.checkFinishedStep(stepName, ms));
+                report(run, run.check());
+            }
+        },
+        end() {
+            if (run.isEnded)
+                return;
+            report(run, run.check());
+            run.end();
+        },
+    };
+}
+/** `startTrace(name)` returns the object; call `.end()` when the flow is over. */
+function startTrace(name) {
+    return startRun(name);
+}
+/** Runs `fn` with a trace object and ends the trace when `fn` settles, either way. */
+async function trace(name, fn) {
+    const handle = startRun(name);
+    try {
+        return await fn(handle);
+    }
+    finally {
+        handle.end();
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/functions/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/functions/trace.ts"],"names":[],"mappings":";;AAcA,0CAEC;AA0CD,gCAEC;AAGD,sBAOC;AAtED,+BAA2B;AAC3B,mDAA2C;AAC3C,2CAAqG;AASrG,IAAI,MAAM,GAAgB,EAAE,CAAA;AAE5B,uFAAuF;AACvF,SAAgB,eAAe,CAAC,SAAsB;IACpD,MAAM,GAAG,SAAS,CAAA;AACpB,CAAC;AAED,SAAS,GAAG;IACV,OAAO,IAAI,CAAC,GAAG,EAAE,CAAA;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAS,MAAM,CAAC,GAAa,EAAE,KAAoC;IACjE,IAAI,CAAC,KAAK;QAAE,OAAM;IAClB,GAAG,CAAC,YAAY,EAAE,CAAA;IAClB,IAAA,yBAAS,GAAE,CAAC,OAAO,CAAC,IAAA,oBAAY,EAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,IAAA,mBAAW,EAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,IAAA,oBAAY,EAAC,KAAK,CAAC,CAAC,CAAA;AAChH,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,GAAG,GAAG,IAAI,gBAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAA,WAAI,GAAE,CAAC,CAAA;IAEzD,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE;YACrB,IAAI,GAAG,CAAC,OAAO;gBAAE,OAAO,EAAE,EAAE,CAAA;YAC5B,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;YACvB,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAA;YACnB,CAAC;oBAAS,CAAC;gBACT,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;gBAChC,IAAI,EAAE,KAAK,SAAS;oBAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,iBAAiB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAA;gBACtE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAA;YAC1B,CAAC;QACH,CAAC;QACD,GAAG;YACD,IAAI,GAAG,CAAC,OAAO;gBAAE,OAAM;YACvB,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAA;YACxB,GAAG,CAAC,GAAG,EAAE,CAAA;QACX,CAAC;KACF,CAAA;AACH,CAAC;AAED,kFAAkF;AAClF,SAAgB,UAAU,CAAC,IAAY;IACrC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAA;AACvB,CAAC;AAED,sFAAsF;AAC/E,KAAK,UAAU,KAAK,CAAI,IAAY,EAAE,EAAgC;IAC3E,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,CAAA;IACzB,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,GAAG,EAAE,CAAA;IACd,CAAC;AACH,CAAC"}

package/dist/shared/trace.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The pure bookkeeping behind `/client/timing` and `/functions`' `trace`/`startTrace` —
+ * which steps are finished (with their ms) and which are still running, checked
+ * against configured limits through an injected monotonic clock so tests never wait
+ * for real time. The two entry points differ only in how often they call `check()`
+ * (a watchdog tick in the browser, a step/trace boundary on the server, per
+ * CLAUDE.md "Traces report misbehaviour, nothing else") and in what they do with
+ * the `TraceReport` it returns.
+ */
+export interface TraceLimits {
+    warnAfterMs?: number;
+    steps?: Record<string, number>;
+}
+/** `configureTraces({ name: { warnAfterMs?, steps? } })` — see README, "Timing". */
+export type TraceConfig = Record<string, TraceLimits>;
+export interface TraceReport {
+    slow: 'trace' | 'step';
+    step?: string;
+    elapsedMs: number;
+    limitMs: number;
+    steps: Record<string, number>;
+    waiting: string[];
+}
+export declare class TraceRun {
+    readonly name: string;
+    private readonly limits;
+    private readonly clock;
+    readonly run: string;
+    private readonly startedAt;
+    private readonly finishedSteps;
+    private readonly runningSteps;
+    private reported;
+    private ended;
+    constructor(name: string, limits: TraceLimits | undefined, clock: () => number, runId: string);
+    get isEnded(): boolean;
+    get hasReported(): boolean;
+    startStep(name: string): void;
+    endStep(name: string): number | undefined;
+    end(): void;
+    /**
+     * The first limit crossed right now, or undefined. Does not itself mark the
+     * run as reported — callers do that only once they have actually sent it.
+     */
+    check(): TraceReport | undefined;
+    /**
+     * The server's counterpart to `check()`'s step loop: a step that has already
+     * been moved into `finishedSteps` (so `endStep` has already run for it) is no
+     * longer in `runningSteps` for `check()` to see, yet the instant it finished
+     * is the only one the server — with no timer — gets to judge it against its
+     * own limit. `ms` is the duration `endStep` just returned for it.
+     */
+    checkFinishedStep(name: string, ms: number): TraceReport | undefined;
+    markReported(): void;
+}
+/** The message README, "Timing" shows: `"app_boot slow: products passed 3000 ms, still waiting"`. */
+export declare function traceMessage(name: string, report: TraceReport): string;
+export declare function traceLabels(name: string, run: string, report: TraceReport): Record<string, string>;
+export declare function traceContext(report: TraceReport): Record<string, unknown>;
+//# sourceMappingURL=trace.d.ts.map

package/dist/shared/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/shared/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAErD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,GAAG,MAAM,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,qBAAa,QAAQ;IASjB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAVxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;IACzD,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAQ;gBAGV,IAAI,EAAE,MAAM,EACJ,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,KAAK,EAAE,MAAM,MAAM,EACpC,KAAK,EAAE,MAAM;IAMf,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASzC,GAAG,IAAI,IAAI;IAIX;;;OAGG;IACH,KAAK,IAAI,WAAW,GAAG,SAAS;IAkChC;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAcpE,YAAY,IAAI,IAAI;CAGrB;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAGtE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIlG;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzE"}

package/dist/shared/trace.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceRun = void 0;
+exports.traceMessage = traceMessage;
+exports.traceLabels = traceLabels;
+exports.traceContext = traceContext;
+class TraceRun {
+    name;
+    limits;
+    clock;
+    run;
+    startedAt;
+    finishedSteps = {};
+    runningSteps = new Map();
+    reported = false;
+    ended = false;
+    constructor(name, limits, clock, runId) {
+        this.name = name;
+        this.limits = limits;
+        this.clock = clock;
+        this.run = runId;
+        this.startedAt = clock();
+    }
+    get isEnded() {
+        return this.ended;
+    }
+    get hasReported() {
+        return this.reported;
+    }
+    startStep(name) {
+        if (this.ended)
+            return;
+        this.runningSteps.set(name, this.clock());
+    }
+    endStep(name) {
+        const startedAt = this.runningSteps.get(name);
+        if (startedAt === undefined)
+            return undefined;
+        this.runningSteps.delete(name);
+        const ms = this.clock() - startedAt;
+        this.finishedSteps[name] = ms;
+        return ms;
+    }
+    end() {
+        this.ended = true;
+    }
+    /**
+     * The first limit crossed right now, or undefined. Does not itself mark the
+     * run as reported — callers do that only once they have actually sent it.
+     */
+    check() {
+        if (this.reported || !this.limits)
+            return undefined;
+        const limits = this.limits;
+        const elapsedMs = this.clock() - this.startedAt;
+        if (limits.warnAfterMs !== undefined && elapsedMs >= limits.warnAfterMs) {
+            return {
+                slow: 'trace',
+                elapsedMs,
+                limitMs: limits.warnAfterMs,
+                steps: { ...this.finishedSteps },
+                waiting: [...this.runningSteps.keys()],
+            };
+        }
+        for (const [stepName, startedAt] of this.runningSteps) {
+            const limitMs = limits.steps?.[stepName];
+            if (limitMs === undefined)
+                continue;
+            const stepElapsedMs = this.clock() - startedAt;
+            if (stepElapsedMs >= limitMs) {
+                return {
+                    slow: 'step',
+                    step: stepName,
+                    elapsedMs: stepElapsedMs,
+                    limitMs,
+                    steps: { ...this.finishedSteps },
+                    waiting: [...this.runningSteps.keys()],
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * The server's counterpart to `check()`'s step loop: a step that has already
+     * been moved into `finishedSteps` (so `endStep` has already run for it) is no
+     * longer in `runningSteps` for `check()` to see, yet the instant it finished
+     * is the only one the server — with no timer — gets to judge it against its
+     * own limit. `ms` is the duration `endStep` just returned for it.
+     */
+    checkFinishedStep(name, ms) {
+        if (this.reported || !this.limits)
+            return undefined;
+        const limitMs = this.limits.steps?.[name];
+        if (limitMs === undefined || ms < limitMs)
+            return undefined;
+        return {
+            slow: 'step',
+            step: name,
+            elapsedMs: ms,
+            limitMs,
+            steps: { ...this.finishedSteps },
+            waiting: [...this.runningSteps.keys()],
+        };
+    }
+    markReported() {
+        this.reported = true;
+    }
+}
+exports.TraceRun = TraceRun;
+/** The message README, "Timing" shows: `"app_boot slow: products passed 3000 ms, still waiting"`. */
+function traceMessage(name, report) {
+    const subject = report.slow === 'step' ? `${report.step} ` : '';
+    return `${name} slow: ${subject}passed ${report.limitMs} ms, still waiting`;
+}
+function traceLabels(name, run, report) {
+    const labels = { trace: name, run, slow: report.slow };
+    if (report.step !== undefined)
+        labels.step = report.step;
+    return labels;
+}
+function traceContext(report) {
+    return {
+        timing: {
+            elapsedMs: report.elapsedMs,
+            limitMs: report.limitMs,
+            steps: report.steps,
+            waiting: report.waiting,
+        },
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/shared/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/shared/trace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dasasian/firebase-structured-logger",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Structured logging for Firebase and Google Cloud web apps — browser, backend, and tools",
   "license": "MIT",
   "author": "Dasasian",
@@ -38,6 +38,10 @@
       "types": "./dist/client/navigation.d.ts",
       "default": "./dist/client/navigation.js"
     },
+    "./client/timing": {
+      "types": "./dist/client/timing.d.ts",
+      "default": "./dist/client/timing.js"
+    },
     "./functions": {
       "types": "./dist/functions/index.d.ts",
       "default": "./dist/functions/index.js"
@@ -55,6 +59,9 @@
       "client/navigation": [
         "dist/client/navigation.d.ts"
       ],
+      "client/timing": [
+        "dist/client/timing.d.ts"
+      ],
       "functions": [
         "dist/functions/index.d.ts"
       ],
@@ -64,7 +71,7 @@
     }
   },
   "bin": {
-    "fsl": "./dist/tools/index.js"
+    "fsl": "dist/tools/index.js"
   },
   "files": [
     "dist",
@@ -75,7 +82,7 @@
     "build:watch": "tsc --watch",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.check.json",
-    "test": "tsx tests/logger.ts && tsx tests/browserBundle.ts && tsx tests/breadcrumbs.ts && tsx tests/navigation.ts && tsx tests/rateLimiter.ts && tsx tests/errorHandler.ts && tsx tests/attachments.ts && tsx tests/feedback.ts && tsx tests/paths.ts && tsx tests/loadsWithoutOptionalPeers.ts && tsx tests/sourceMapStripping.ts && FUNCTIONS_EMULATOR=true tsx tests/errorPayload.ts && FUNCTIONS_EMULATOR=true tsx tests/requestLogger.ts && FUNCTIONS_EMULATOR=true tsx tests/handler.ts && FUNCTIONS_EMULATOR=true tsx tests/httpHandler.ts && FUNCTIONS_EMULATOR=true tsx tests/symbolication.ts && FUNCTIONS_EMULATOR=true tsx tests/publicApi.ts && FUNCTIONS_EMULATOR=true tsx tests/configureTwice.ts && FUNCTIONS_EMULATOR=true tsx tests/deprecatedNames.ts && tsx tests/productionOutput.ts && tsx tests/storageChain.ts && tsx tests/entrySize.ts && tsx tests/handlerSymbolication.ts && tsx tests/releaseResolution.ts && tsx tests/sourceMapCacheBounds.ts && tsx tests/doctor.ts && tsx tests/doctorProcess.ts && tsx tests/uploadSourcemapsBackend.ts",
+    "test": "tsx tests/logger.ts && tsx tests/browserBundle.ts && tsx tests/breadcrumbs.ts && tsx tests/navigation.ts && tsx tests/timing.ts && tsx tests/rateLimiter.ts && tsx tests/errorHandler.ts && tsx tests/attachments.ts && tsx tests/feedback.ts && tsx tests/paths.ts && tsx tests/loadsWithoutOptionalPeers.ts && tsx tests/sourceMapStripping.ts && FUNCTIONS_EMULATOR=true tsx tests/errorPayload.ts && FUNCTIONS_EMULATOR=true tsx tests/requestLogger.ts && FUNCTIONS_EMULATOR=true tsx tests/serverTrace.ts && FUNCTIONS_EMULATOR=true tsx tests/handler.ts && FUNCTIONS_EMULATOR=true tsx tests/httpHandler.ts && FUNCTIONS_EMULATOR=true tsx tests/symbolication.ts && FUNCTIONS_EMULATOR=true tsx tests/publicApi.ts && FUNCTIONS_EMULATOR=true tsx tests/configureTwice.ts && FUNCTIONS_EMULATOR=true tsx tests/deprecatedNames.ts && tsx tests/productionOutput.ts && tsx tests/storageChain.ts && tsx tests/entrySize.ts && tsx tests/handlerSymbolication.ts && tsx tests/releaseResolution.ts && tsx tests/sourceMapCacheBounds.ts && tsx tests/doctor.ts && tsx tests/doctorProcess.ts && tsx tests/uploadSourcemapsBackend.ts",
     "prepublishOnly": "npm run clean && npm run build",
     "smoke:deploy": "cd smoke/functions && npm install && npm run build && cd .. && firebase deploy --only functions --project $(grep '^FSL_SMOKE_PROJECT=' .env.local | cut -d= -f2)",
     "smoke:deploy:run": "bash smoke/cloudrun/deploy.sh",

package/skills/query-logs/SKILL.md

@@ -34,6 +34,10 @@ All entries written by firebase-structured-logger include these labels:
 | `route` | Route pattern, e.g. `/orders/:id/items` — group by this (apps using `enableNavigation`) |
 | `path` | Real path, e.g. `/orders/1042/items` — one specific page or record; query string never stored |
 | `routeSource` | `router` (the app named the route) or `pattern` (ids replaced by rule) |
+| `trace` | On a slow-trace WARNING: the trace's name, e.g. `app_boot` |
+| `run` | On a slow-trace WARNING: tells overlapping runs of one trace apart |
+| `slow` | `trace` (the whole run passed its limit) or `step` (one step passed its own) |
+| `step` | When `slow="step"`: the step that was late. `jsonPayload.timing` has every step's ms and what was still waiting |
 | `releaseId` | Git short hash or explicit release ID |
 | `platform` | `ios`, `android`, `macos`, `windows`, `web` |
 | `browser` | `chrome`, `firefox`, `safari`, `edge` |