@pristine-ts/observability 2.0.16

package/dist/types/store/log-store.d.ts

@@ -0,0 +1,79 @@
+import { LogModel } from "@pristine-ts/logging";
+/**
+ * The read/write layer for captured logs. The `ObservabilityLogger` (a `Logger`-tagged
+ * transport) calls `append` on every log it sees. The CLI's `logs` command calls `read`
+ * / `tail` — addressed by event/trace/request id, never by a partition selector.
+ *
+ * Internally, each pristine process writes to its own per-process directory (keyed by
+ * the kernel instantiation id) so concurrent processes never race on the same file.
+ * That partition is invisible to callers: `read` walks every directory newest-first and
+ * concatenates; `tail` follows the most-recently-written directory.
+ *
+ * Singleton so both the writer (logger) and any reader resolved during the same
+ * process see the same in-memory state.
+ */
+export declare class LogStore {
+    private readonly enabled;
+    private readonly retainedInstances;
+    private readonly partitionId;
+    private readonly paths;
+    private directoryEnsured;
+    private pruned;
+    constructor(enabled: boolean, directory: string, retainedInstances: number, partitionId: string);
+    /**
+     * Whether capture is on. The `LoggerInterface` contract surfaces this through the
+     * adapter so `LogHandler` can skip dispatch entirely for disabled stores.
+     */
+    isCaptureEnabled(): boolean;
+    /**
+     * Appends one log entry to the current process's `logs.jsonl`. No-op when
+     * observability is disabled.
+     *
+     * The on-disk shape is the JSON-serialized `LogModel` itself — `severity` stays a
+     * numeric `SeverityEnum`, `date` becomes an ISO string — so the `logs` command can
+     * round-trip through `PrettyLogFormatter`. Stringification is cycle-safe because
+     * `log.extra` routinely holds `Span`/`Trace` objects whose `parentSpan` ↔ `children`
+     * back-references would otherwise blow up a naive serializer.
+     */
+    append(log: LogModel): void;
+    /**
+     * Every captured log entry across every partition, in write order within each
+     * partition and partitions concatenated newest-first. When `id` is provided, only
+     * entries whose `traceId` / `eventId` / `requestId` match are returned — useful for
+     * `pristine logs <id>`.
+     */
+    read(id?: string): Record<string, any>[];
+    /**
+     * Follows the most-recently-written partition's `logs.jsonl`, emitting each newly-
+     * appended line until the returned handle's `stop()` is called. When `id` is
+     * provided, only matching entries surface. Returns a no-op handle when the store
+     * has no partitions yet.
+     */
+    tail(id: string | undefined, onLine: (line: string) => void): {
+        stop(): void;
+    };
+    private ensurePartitionDirectory;
+    /**
+     * Drops partition directories beyond the retained limit, ordered by `mtime`. Once
+     * per process — additional appends are zero-cost. Best-effort: a failure to prune
+     * never blocks a write.
+     */
+    private pruneOldPartitions;
+    private partitionsNewestFirst;
+    private latestPartition;
+    private directoryMtime;
+    private readJsonl;
+    /**
+     * True when any of the entry's correlation fields match the requested id.
+     * `requestId` is checked too even though `LogModel` doesn't define it as a field
+     * today — JSON deserialization is permissive, so a custom mapper that does set it
+     * will round-trip and match.
+     */
+    private static entryMatchesId;
+    /**
+     * `JSON.stringify` with a cycle guard — an object seen earlier in the walk is rendered
+     * as `"[Circular]"` rather than recursed into. Faithful at any depth, and immune to the
+     * `Span.parentSpan` ↔ `Span.children` cycles common in `log.extra`.
+     */
+    private static safeStringify;
+}

package/dist/types/store/log-tailer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Follows a growing `.jsonl` file and emits each newly-appended complete line. The
+ * `logs --follow` command and the REPL use this for a `tail -f`-style live view.
+ *
+ * Watches the file's parent directory (watching a not-yet-created file directly is
+ * unreliable across platforms) and reads the byte delta on each change. Partial trailing
+ * lines are buffered until their terminating newline arrives.
+ *
+ * Not a DI service — a plain utility. Instantiate, `follow()`, and `stop()` when done.
+ */
+export declare class LogTailer {
+    private readonly filePath;
+    private watcher?;
+    private offset;
+    private buffer;
+    constructor(filePath: string);
+    /**
+     * Starts following. Existing content is skipped — only lines appended after this call
+     * are emitted. Call `stop()` to release the watch.
+     */
+    follow(onLine: (line: string) => void): void;
+    /**
+     * Stops following and releases the filesystem watch.
+     */
+    stop(): void;
+    private drain;
+}

package/dist/types/store/observability-paths.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolves every path inside the observability store from the configured store directory.
+ * Pure and stateless past construction — instantiate once with the configured directory
+ * and reuse.
+ *
+ * Layout:
+ * ```
+ * <root>/
+ *   <instanceId>/logs.jsonl
+ *   <instanceId>/requests.jsonl
+ *   <instanceId>/traces/<traceId>.json
+ * ```
+ *
+ * Each `<instanceId>` is one pristine process lifetime (= the kernel instantiation id).
+ * No metadata sidecars, no `latest.json` pointer — directory `mtime` answers "which is
+ * most recent."
+ */
+export declare class ObservabilityPaths {
+    /**
+     * The absolute store root. The configured directory is resolved against `process.cwd()`
+     * when it is not already absolute.
+     */
+    readonly root: string;
+    constructor(configuredDirectory: string);
+    instanceDirectory(instanceId: string): string;
+    logsFile(instanceId: string): string;
+    requestsFile(instanceId: string): string;
+    tracesDirectory(instanceId: string): string;
+    traceFile(instanceId: string, traceId: string): string;
+}

package/dist/types/store/observability-run-manager.d.ts

@@ -0,0 +1,96 @@
+import { ObservabilityConfiguration } from "../observability-configuration";
+/**
+ * Owns the lifecycle of an observability run. A "run" is one `pristine start` lifetime;
+ * the run directory is keyed by the kernel instantiation id.
+ *
+ * The observability writers (`ObservabilityLogger`, `ObservabilityTracer`) stay dormant
+ * until `beginRun()` is called — so one-shot CLI commands (`build`, `logs`, `trace`) and
+ * the REPL never pollute the store. `StartCommand` is the only caller of `beginRun()`.
+ *
+ * A singleton so the logger, the tracer, and `StartCommand` all share the same run state.
+ */
+export declare class ObservabilityRunManager {
+    private readonly configuration;
+    private readonly runId;
+    /**
+     * Once the reclaimed run exceeds the budget we trim back to this fraction of it, so the
+     * (relatively expensive) reclaim isn't re-triggered on the very next write.
+     */
+    private static readonly LOW_WATER_FRACTION;
+    private readonly paths;
+    private activeRunDirectory?;
+    /**
+     * Approximate running total of bytes written to the active run. Incremented cheaply by
+     * the writers via `recordBytesWritten`; resynced to the real on-disk total after each
+     * reclaim. Used to decide when to enforce the per-run size budget without stat-ing the
+     * whole run directory on every write.
+     */
+    private runBytes;
+    constructor(configuration: ObservabilityConfiguration, runId: string);
+    /**
+     * Begins a run: creates the run directory, writes `run.json`, repoints `latest.json`,
+     * and prunes old runs. No-op when observability is disabled. Safe to call once per
+     * process.
+     */
+    beginRun(command: string): void;
+    /**
+     * Reports bytes just written to the run by a writer. Cheap — an add and a compare. When
+     * the running total crosses the configured `maxRunSizeBytes`, triggers a reclaim that
+     * drops the run's oldest data. No-op when no run is active or the cap is disabled.
+     */
+    recordBytesWritten(bytes: number): void;
+    /**
+     * Ends the active run by stamping `endedAt` into `run.json`. No-op when no run is active.
+     */
+    endRun(): void;
+    /**
+     * Whether a run is currently active. The writers consult this on every write.
+     */
+    isRunActive(): boolean;
+    /**
+     * The absolute logs file for the active run, or undefined when no run is active.
+     */
+    logsFile(): string | undefined;
+    /**
+     * The absolute requests-index file for the active run, or undefined when no run is active.
+     */
+    requestsFile(): string | undefined;
+    /**
+     * The absolute path of the trace file for a given trace id in the active run, or
+     * undefined when no run is active.
+     */
+    traceFile(traceId: string): string | undefined;
+    /**
+     * Lazily begins a run when `autoBegin` is configured and none is active yet — so a
+     * server started outside the `pristine` CLI captures its logs/traces on the first
+     * write, with nothing calling `beginRun()` explicitly.
+     */
+    private ensureAutoBegun;
+    /**
+     * Drops the run's oldest data until it is back under the budget's low-water mark:
+     * oldest trace files first, then the head of `logs.jsonl` (keeping the newest tail).
+     * The `requests.jsonl` index is rewritten to drop entries for deleted traces.
+     *
+     * Best-effort and fully guarded — budget enforcement must never break or lose a write.
+     */
+    private reclaim;
+    /**
+     * Rewrites a file in place keeping only its last `keepBytes` bytes, aligned forward to
+     * the next newline so no partial line survives.
+     */
+    private trimFileHead;
+    /**
+     * Rewrites `requests.jsonl` keeping only entries whose trace file still exists — so the
+     * request index stays consistent after trace files are reclaimed.
+     */
+    private pruneRequestsIndex;
+    /**
+     * Sum of the sizes of every file directly inside `directory`.
+     */
+    private directoryTotalSize;
+    /**
+     * Removes run directories beyond the retained limit, ordered by their
+     * `run.json:startedAt`. Best-effort — a failure to prune never blocks a run.
+     */
+    private pruneOldRuns;
+}

package/dist/types/store/observability-store-reader.d.ts

@@ -0,0 +1,55 @@
+import { ObservabilityConfiguration } from "../observability-configuration";
+import { RunMetadata } from "../models/run-metadata.model";
+import { RequestSummary } from "../models/request-summary.model";
+import { SerializedTrace } from "./trace-deserializer";
+/**
+ * Read-only access to the observability store. Used by the `logs`, `trace` and `requests`
+ * CLI commands. Pure filesystem reads — no kernel, no running app required; it reads what
+ * a separate `pristine start` process wrote.
+ */
+export declare class ObservabilityStoreReader {
+    private readonly paths;
+    constructor(configuration: ObservabilityConfiguration);
+    /**
+     * The run id the `latest.json` pointer references, or undefined when the store is empty.
+     */
+    latestRunId(): string | undefined;
+    /**
+     * Resolves an explicit run id, or falls back to the latest run.
+     */
+    resolveRunId(explicit?: string): string | undefined;
+    /**
+     * Every run's metadata, most-recent first.
+     */
+    listRuns(): RunMetadata[];
+    /**
+     * Reads a run's `run.json`, or undefined when absent/corrupt.
+     */
+    readRunMetadata(runId: string): RunMetadata | undefined;
+    /**
+     * The request summaries for a run, most-recent first, optionally capped to `limit`.
+     */
+    readRequests(runId: string, limit?: number): RequestSummary[];
+    /**
+     * The raw log entries for a run, in write order. Each is a parsed `logs.jsonl` line.
+     */
+    readLogs(runId: string): Record<string, any>[];
+    /**
+     * The absolute `logs.jsonl` path for a run — handed to `LogTailer` for `--follow`.
+     */
+    logsFilePath(runId: string): string;
+    /**
+     * Finds and reads a trace by id. Searches the preferred run first (when given), then
+     * every other run most-recent first. Returns the parsed trace and the run it was found
+     * in, or undefined when no run contains it.
+     */
+    findTrace(traceId: string, preferredRunId?: string): {
+        trace: SerializedTrace;
+        runId: string;
+    } | undefined;
+    /**
+     * The most recently seen trace ids across the latest run — used by the REPL completer.
+     */
+    recentTraceIds(limit: number): string[];
+    private readJsonl;
+}

package/dist/types/store/serializers/serialized-span.interface.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The plain-object shape of a stored span — as produced by `TraceRenderer.serialize`
+ * and rehydrated by `SpanDeserializer`.
+ */
+export interface SerializedSpan {
+    id?: string;
+    keyname: string;
+    startDate: number;
+    endDate?: number;
+    context?: {
+        [key: string]: string;
+    };
+    children?: SerializedSpan[];
+}

package/dist/types/store/serializers/serialized-trace.interface.d.ts

@@ -0,0 +1,14 @@
+import { SerializedSpan } from "./serialized-span.interface";
+/**
+ * The plain-object shape of a stored trace — as written to disk by
+ * `ObservabilityTracer` and rehydrated by `TraceDeserializer`.
+ */
+export interface SerializedTrace {
+    id: string;
+    startDate: number;
+    endDate?: number;
+    context?: {
+        [key: string]: string;
+    };
+    rootSpan?: SerializedSpan;
+}

package/dist/types/store/serializers/span-deserializer.d.ts

@@ -0,0 +1,11 @@
+import { Span, Trace } from "@pristine-ts/common";
+import { SerializedSpan } from "./serialized-span.interface";
+/**
+ * Rebuilds a `Span` (with its full child tree) from the stored plain object. Used by
+ * `TraceDeserializer` for the trace's root span and recursively for every descendant —
+ * so `traceRenderer.renderTree`/`renderFlat`, which call instance methods like
+ * `getDuration()`, work unchanged on stored traces.
+ */
+export declare class SpanDeserializer {
+    static deserialize(serialized: SerializedSpan, trace: Trace): Span;
+}

package/dist/types/store/serializers/trace-deserializer.d.ts

@@ -0,0 +1,9 @@
+import { Trace } from "@pristine-ts/common";
+import { SerializedTrace } from "./serialized-trace.interface";
+/**
+ * Rehydrates a stored trace JSON (the shape written by `ObservabilityTracer`) back into
+ * a `Trace` instance, with its full span tree rebuilt via `SpanDeserializer`.
+ */
+export declare class TraceDeserializer {
+    static deserialize(serialized: SerializedTrace): Trace;
+}

package/dist/types/store/store.d.ts

@@ -0,0 +1,2 @@
+export * from "./log-store";
+export * from "./trace-store";

package/dist/types/store/trace-deserializer.d.ts

@@ -0,0 +1,41 @@
+import { Trace } from "@pristine-ts/common";
+/**
+ * The plain-object shape of a stored span (as produced by `TraceRenderer.serialize`).
+ */
+interface SerializedSpan {
+    id?: string;
+    keyname: string;
+    startDate: number;
+    endDate?: number;
+    context?: {
+        [key: string]: string;
+    };
+    children?: SerializedSpan[];
+}
+/**
+ * The plain-object shape of a stored trace.
+ */
+export interface SerializedTrace {
+    id: string;
+    startDate: number;
+    endDate?: number;
+    context?: {
+        [key: string]: string;
+    };
+    rootSpan?: SerializedSpan;
+}
+/**
+ * Rehydrates a stored trace JSON (the shape written by `ObservabilityTracer`) back into
+ * `Trace`/`Span` instances, so `traceRenderer.renderTree`/`renderFlat` — which call
+ * instance methods like `getDuration()` — work unchanged on stored traces.
+ *
+ * Stateless; instantiate once and reuse, or use the static `deserialize`.
+ */
+export declare class TraceDeserializer {
+    /**
+     * Rebuilds a `Trace` (with its full span tree) from the stored plain object.
+     */
+    static deserialize(serialized: SerializedTrace): Trace;
+    private static deserializeSpan;
+}
+export {};

package/dist/types/store/trace-store.d.ts

@@ -0,0 +1,88 @@
+import { Trace } from "@pristine-ts/common";
+import { RequestSummary } from "../models/request-summary.model";
+import { SerializedTrace } from "../interfaces/serialized-trace.interface";
+/**
+ * The read/write layer for captured traces. The `ObservabilityTracer` (a `Tracer`-
+ * tagged transport) calls `append` on every completed trace; the CLI's `trace` and
+ * `requests` commands call `find` / `recentRequests` / `recentTraceIds`. The REPL also
+ * reads `recentTraceIds` for its tab-completion.
+ *
+ * Writes both `traces/<eventId>.json` (the full tree) and an appended one-line
+ * `RequestSummary` in `requests.jsonl` (the fast index for `pristine requests`) as a
+ * single coupled operation. The summary additionally serves as the lookup table that
+ * resolves `requestId` / `traceId` back to the canonical `eventId` when they differ.
+ *
+ * Internally, each pristine process writes to its own per-process directory (keyed by
+ * the kernel instantiation id) so concurrent processes never race. That partition is
+ * invisible to callers — `find` and `recentRequests` walk every directory newest-first.
+ *
+ * Singleton so multiple appenders within the same process share the in-memory `pruned`
+ * latch.
+ */
+export declare class TraceStore {
+    private readonly enabled;
+    private readonly retainedInstances;
+    private readonly partitionId;
+    private readonly paths;
+    private directoryEnsured;
+    private pruned;
+    constructor(enabled: boolean, directory: string, retainedInstances: number, partitionId: string);
+    /**
+     * Persists a completed trace: writes `traces/<eventId>.json` (the full tree) and
+     * appends a `RequestSummary` to `requests.jsonl`. No-op when observability is
+     * disabled.
+     *
+     * The summary's optional `traceId` / `requestId` fields are written only when they
+     * differ from the canonical `eventId` (typically only `requestId` for HTTP requests
+     * with an `x-pristine-request-id` header that disagreed with the mapper's event id,
+     * and `traceId` for distributed-tracing scenarios). The common case is a one-id
+     * line — `{eventId, startedAt, durationMs, rootKeyname, ...http}`.
+     */
+    append(trace: Trace): void;
+    /**
+     * Finds and rehydrates a trace by any of `eventId` / `traceId` / `requestId`, returning
+     * a `Trace` instance with its full span tree rebuilt (instance methods like
+     * `getDuration()` work directly). Searches partitions newest-first.
+     */
+    find(id: string): {
+        trace: Trace;
+        eventId: string;
+    } | undefined;
+    /**
+     * Same as `find`, but returns the raw stored JSON. The escape hatch for callers that
+     * want to render the on-disk shape verbatim — e.g. `pristine trace --format json`.
+     */
+    findSerialized(id: string): {
+        trace: SerializedTrace;
+        eventId: string;
+    } | undefined;
+    /**
+     * Recent request summaries across every partition, most-recent first, optionally
+     * capped to `limit`.
+     */
+    recentRequests(limit?: number): RequestSummary[];
+    /**
+     * The most recent event ids across all partitions — used by the REPL completer.
+     */
+    recentTraceIds(limit: number): string[];
+    private buildSummary;
+    /**
+     * The canonical id for a trace. Today the trace's own `id` is set from the kernel's
+     * event id at trace creation, so they're equal. A custom `context["event.id"]`
+     * override wins when present — that's the explicit hook for distributed-tracing setups
+     * where the trace id was overwritten from a propagated `traceparent`.
+     */
+    private eventIdOf;
+    private resolveEventIdFromSummaries;
+    private tryLoadTrace;
+    private readSummaries;
+    private ensurePartitionDirectory;
+    /**
+     * Drops partition directories beyond the retained limit, ordered by `mtime`. Once
+     * per process. Best-effort: a failure to prune never blocks a write.
+     */
+    private pruneOldPartitions;
+    private partitionsNewestFirst;
+    private directoryMtime;
+    private readJsonl;
+}

package/dist/types/tailers/log-tailer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Follows a growing `.jsonl` file and emits each newly-appended complete line. The
+ * `logs --follow` command and the REPL use this for a `tail -f`-style live view.
+ *
+ * Watches the file's parent directory (watching a not-yet-created file directly is
+ * unreliable across platforms) and reads the byte delta on each change. Partial trailing
+ * lines are buffered until their terminating newline arrives.
+ *
+ * Not a DI service — a plain utility. Instantiate, `follow()`, and `stop()` when done.
+ */
+export declare class LogTailer {
+    private readonly filePath;
+    private watcher?;
+    private offset;
+    private buffer;
+    constructor(filePath: string);
+    /**
+     * Starts following. Existing content is skipped — only lines appended after this call
+     * are emitted. Call `stop()` to release the watch.
+     */
+    follow(onLine: (line: string) => void): void;
+    /**
+     * Stops following and releases the filesystem watch.
+     */
+    stop(): void;
+    private drain;
+}

package/dist/types/tailers/tailers.d.ts

@@ -0,0 +1 @@
+export * from "./log-tailer";

package/dist/types/tracers/observability.tracer.d.ts

@@ -0,0 +1,16 @@
+import { Readable } from "stream";
+import { TracerInterface } from "@pristine-ts/telemetry";
+import { TraceStore } from "../store/trace-store";
+/**
+ * A `Tracer` transport that forwards every completed trace to `TraceStore`. Thin adapter
+ * — all file I/O, request-summary computation, retention, and per-process partitioning
+ * live in `TraceStore`.
+ *
+ * Crash-isolated: a write failure becomes a stderr line rather than propagating.
+ */
+export declare class ObservabilityTracer implements TracerInterface {
+    private readonly traceStore;
+    traceEndedStream: Readable;
+    constructor(traceStore: TraceStore);
+    private reportFailure;
+}

package/dist/types/tracers/tracers.d.ts

@@ -0,0 +1 @@
+export * from "./observability.tracer";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pristine-ts/observability",
+  "version": "2.0.16",
+  "description": "",
+  "module": "dist/lib/esm/observability.module.js",
+  "main": "dist/lib/cjs/observability.module.js",
+  "types": "dist/types/observability.module.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json",
+    "prepublish": "npm run build",
+    "test": "jest",
+    "test:cov": "jest --coverage"
+  },
+  "dependencies": {
+    "@pristine-ts/common": "^2.0.16",
+    "@pristine-ts/configuration": "^2.0.16",
+    "@pristine-ts/logging": "^2.0.16",
+    "@pristine-ts/telemetry": "^2.0.16"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "jest": {
+    "transform": {
+      ".(ts|tsx)": "ts-jest"
+    },
+    "globals": {
+      "ts-jest": {
+        "tsconfig": {
+          "strictNullChecks": false
+        }
+      }
+    },
+    "testEnvironment": "node",
+    "testRegex": "(/__tests__/.*|\\.(test|spec))\\.(ts|tsx|js)$",
+    "moduleFileExtensions": [
+      "ts",
+      "tsx",
+      "js"
+    ],
+    "coveragePathIgnorePatterns": [
+      "/node_modules/",
+      "/test/"
+    ],
+    "collectCoverageFrom": [
+      "src/*.{js,ts}"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/magieno/pristine-ts.git",
+    "directory": "packages/observability"
+  },
+  "gitHead": "a55d7d59862672a8cbbca4088fed090779b37705"
+}