@pristine-ts/telemetry 2.0.2 → 2.0.4

package/dist/types/interfaces/tracing-manager.interface.d.ts

@@ -1,50 +1 @@
-import { Span } from "../models/span.model";
-import { Trace } from "../models/trace.model";
-/**
- * This interface specifies what a tracing manager should implement.
- */
-export interface TracingManagerInterface {
-    /**
-     * This property contains a reference to the active trace.
-     */
-    trace?: Trace;
-    /**
-     * This methods starts the Tracing. This should be the first method called before doing anything else.
-     * @param spanRootKeyname The keyname of the span at the root.
-     * @param traceId The trace id if there is one.
-     * @param context The context if there is one.
-     */
-    startTracing(spanRootKeyname?: string, traceId?: string, context?: {
-        [key: string]: string;
-    }): Span;
-    /**
-     * This method ends the trace entirely.
-     */
-    endTrace(): void;
-    /**
-     * This method starts a new span.
-     * @param keyname The keyname for this new span.
-     * @param parentKeyname The keyname of the parent span.
-     * @param parentId The id of the parent span.
-     * @param context The context if there is one.
-     */
-    startSpan(keyname: string, parentKeyname?: string, parentId?: string, context?: {
-        [key: string]: string;
-    }): Span;
-    /**
-     * This methods adds an already created Span to the trace. It assumes that it its hierarchy is correct.
-     * @param span The span to add.
-     */
-    addSpan(span: Span): Span;
-    /**
-     * This methods ends the span by setting the end date and by calling the tracers.
-     * It will also end the trace if the rootspan is being ended.
-     * @param span The span to end.
-     */
-    endSpan(span: Span): void;
-    /**
-     * This method ends the span using a keyname.
-     * @param keyname The keyname of the span to end.
-     */
-    endSpanKeyname(keyname: string): void;
-}
+export { TracingManagerInterface } from "@pristine-ts/common";

package/dist/types/managers/tracing.manager.d.ts

@@ -8,6 +8,24 @@ import { LogHandlerInterface } from "@pristine-ts/logging";
  * The Tracing Manager provides methods to help with tracing.
  * It is tagged and can be injected using TracingManagerInterface which facilitates mocking.
  * It is module scoped to the TelemetryModuleKeyname.
+ *
+ * **Where the active `Trace` lives.** The active trace is stored on `EventContext.trace`,
+ * propagated via `AsyncLocalStorage`. Every `TracingManager` instance — whether resolved
+ * from the root container (kernel boot) or from a per-event child container — reads and
+ * writes spans through the same `EventContext.trace` reference, so a span started in the
+ * kernel and an event added in a controller belong to the same trace tree.
+ *
+ * **Fallback `this.trace`.** During kernel boot (`Kernel.start()` and friends), there is
+ * no `EventContext` yet — the framework hasn't started handling an event. In that window
+ * the manager falls back to `this.trace`. This is the only time `this.trace` is touched.
+ *
+ * **Lifecycle: container-scoped, not singleton.** Each per-event DI child container gets
+ * its own `TracingManager` instance. The per-instance `this.trace` fallback is what keeps
+ * parallel events isolated *if* tracing is somehow started outside an EventContext.
+ * Resolving `TracingManager` from the root container returns the root instance (used for
+ * kernel-initialization spans); resolving from a child container returns the per-event
+ * instance — both will agree on what trace is active inside an event because they read
+ * from EventContext.
  */
 export declare class TracingManager implements TracingManagerInterface {
     private readonly tracers;
@@ -16,15 +34,10 @@ export declare class TracingManager implements TracingManagerInterface {
     private readonly debug;
     private readonly tracingContext;
     /**
-     * This property contains a reference to the active trace.
+     * Fallback trace used only during kernel boot when no `EventContext` is active.
+     * Inside an event, the active trace lives on `EventContext.trace` instead.
      */
     trace?: Trace;
-    /**
-     * This object contains a map of all the spans sorted by their keyname.
-     */
-    spans: {
-        [keyname: string]: Span[];
-    };
     /**
      * The Tracing Manager provides methods to help with tracing.
      * It is tagged and can be injected using TracingManagerInterface which facilitates mocking.
@@ -37,6 +50,16 @@ export declare class TracingManager implements TracingManagerInterface {
      * @param tracingContext The tracing context.
      */
     constructor(tracers: TracerInterface[], loghandler: LogHandlerInterface, isActive: boolean, debug: boolean, tracingContext: TracingContext);
+    /**
+     * Returns the currently active trace from the EventContext, falling back to the
+     * per-instance `this.trace` when no EventContext is active (kernel boot).
+     */
+    private getActiveTrace;
+    /**
+     * Stores `trace` as the active trace — on `EventContext.trace` when an event is active,
+     * otherwise on the instance fallback `this.trace`.
+     */
+    private setActiveTrace;
     /**
      * This methods starts the Tracing. This should be the first method called before doing anything else.
      * @param spanRootKeyname The keyname of the span at the root.
@@ -76,4 +99,47 @@ export declare class TracingManager implements TracingManagerInterface {
      * This method ends the trace entirely.
      */
     endTrace(): void;
+    /**
+     * Attaches a named, timestamped event to the most-recently-started in-progress span.
+     * Use for noteworthy moments that don't warrant a child span — "validation passed",
+     * "found 50 rows", "rate limit ok". Cheap (just pushes onto an array); shows up in
+     * the trace rendered by tracers (ConsoleTracer, FileTracer, X-Ray, etc.).
+     *
+     * If no span is currently active (no trace started, or every span has already ended),
+     * a warning is logged and the marker is dropped. The warning is the explicit signal
+     * that "this marker call had nowhere to go" — usually the sign of a missing
+     * `startTracing()` call earlier in the flow.
+     */
+    addEventToCurrentSpan(message: string, attributes?: {
+        [key: string]: string;
+    }): void;
+    /**
+     * Returns the active trace's spans + their events as a flat, timestamp-sorted list of
+     * `{kind, name, date, attributes}` entries. Public utility for custom tracers, debug
+     * endpoints, test helpers, or anyone who wants "the active trace as a flat list."
+     * Returns an empty array when no active trace exists.
+     */
+    getCurrentTrail(): Array<{
+        kind: "span" | "event";
+        name: string;
+        date: Date;
+        attributes: {
+            [key: string]: string;
+        };
+    }>;
+    /**
+     * Finds the deepest in-progress span — the leaf of the still-open subtree. Used as
+     * the target for `addEventToCurrentSpan`. Intuition: events attach to whatever is
+     * currently open at the bottom of the call stack.
+     *
+     * Walking the in-progress subtree (rather than ranking all spans by start date)
+     * avoids the edge case where a parent and child have the same `Date.now()` value —
+     * picking the "latest started" by raw timestamp would incorrectly attach to the
+     * parent. Depth-first traversal of in-progress children naturally lands on the
+     * deepest leaf. Tie-broken by latest start date when multiple leaves exist.
+     *
+     * Returns undefined when nothing is in progress (no trace, or every span has ended).
+     * @private
+     */
+    private findActiveLeafSpan;
 }

package/dist/types/models/models.d.ts

@@ -1,2 +1,3 @@
+export * from "./span-event.model";
 export * from "./span.model";
 export * from "./trace.model";

package/dist/types/models/span-event.model.d.ts

@@ -0,0 +1 @@
+export { SpanEvent } from "@pristine-ts/common";

package/dist/types/models/span.model.d.ts

@@ -1,73 +1 @@
-import { Trace } from "./trace.model";
-import { TracingManagerInterface } from "../interfaces/tracing-manager.interface";
-/**
- * This model represents a span.
- */
-export declare class Span {
-    keyname: string;
-    /**
-     * The unique id of the span.
-     */
-    id: string;
-    /**
-     * The tracing manager.
-     */
-    tracingManager?: TracingManagerInterface;
-    /**
-     * The trace the span is attached to.
-     */
-    trace?: Trace;
-    /**
-     * The timestamp in milliseconds at which the span was started.
-     */
-    startDate: number;
-    /**
-     * The timestamp in milliseconds at which the span was ended.
-     */
-    endDate?: number;
-    /**
-     * The parent span.
-     */
-    parentSpan?: Span;
-    /**
-     * The children spans.
-     */
-    children: Span[];
-    /**
-     * The context associated with the span.
-     */
-    context: {
-        [key: string]: string;
-    };
-    /**
-     * Whether or not the span is in progress, meaning it has not ended.
-     */
-    inProgress: boolean;
-    /**
-     * This model represents a span.
-     * @param keyname The keyname of the span.
-     * @param id The unique id of the span.
-     * @param context The context to associate with the span.
-     */
-    constructor(keyname: string, id?: string, context?: {
-        [key: string]: string;
-    });
-    /**
-     * This method returns the duration of the span in milliseconds.
-     */
-    getDuration(): number;
-    /**
-     * This method ends the span.
-     */
-    end(): void;
-    /**
-     * This method sets the trace for the span and all of its children.
-     * @param trace The trace the span should be attached to.
-     */
-    setTrace(trace: Trace): void;
-    /**
-     * This method adds a child span to the current span. It only adds it if it's not already part of the children.
-     * @param span The span to add as a child.
-     */
-    addChild(span: Span): void;
-}
+export { Span, SpanLifecycleOwnerInterface } from "@pristine-ts/common";

package/dist/types/models/trace.model.d.ts

@@ -1,44 +1 @@
-import { Span } from "./span.model";
-/**
- * This model represents a trace.
- */
-export declare class Trace {
-    /**
-     * The unique id of the trace.
-     */
-    id: string;
-    /**
-     * The timestamp in milliseconds at which the trace was started.
-     */
-    startDate: number;
-    /**
-     * The timestamp in milliseconds at which the trace was ended.
-     */
-    endDate?: number;
-    /**
-     * The span that is at the root.
-     */
-    rootSpan?: Span;
-    /**
-     * The context associated with the trace.
-     */
-    context?: {
-        [key: string]: string;
-    };
-    /**
-     * Whether or not the trace was ended.
-     */
-    hasEnded: boolean;
-    /**
-     * This model represents a trace.
-     * @param id The unique id of the trace.
-     * @param context The context associated with the trace.
-     */
-    constructor(id?: string, context?: {
-        [key: string]: string;
-    });
-    /**
-     * This returns the duration of the trace in miliseconds.
-     */
-    getDuration(): number;
-}
+export { Trace } from "@pristine-ts/common";

package/dist/types/utils/span-runner.d.ts

@@ -1,59 +1 @@
-import { TracingManagerInterface } from "../interfaces/tracing-manager.interface";
-/**
- * Options to scope a `runWithSpan` call beyond just naming the span.
- */
-export interface SpanRunnerOptions {
-    /** When set, attach the new span as a child of the most recent span with this keyname. */
-    parentKeyname?: string;
-    /** Disambiguates parents when multiple spans share the same `parentKeyname`. */
-    parentId?: string;
-    /** Free-form context recorded on the span and surfaced in the rendered output. */
-    context?: {
-        [key: string]: string;
-    };
-}
-/**
- * Runs a function inside a span that is automatically ended when the function returns
- * or throws.
- *
- * Replaces the manual `start → try → finally end()` boilerplate:
- *
- * ```ts
- * // Before:
- * const span = this.tracingManager.startSpan("payment.charge");
- * try {
- *   return await this.client.charge(amount);
- * } finally {
- *   span.end();
- * }
- *
- * // After:
- * return spanRunner.runWithSpan(this.tracingManager, "payment.charge",
- *   () => this.client.charge(amount));
- * ```
- *
- * Why pass `tracingManager` explicitly? The manager is registered per-container, and
- * Pristine creates a child container per event. A "magic" lookup that finds the right
- * one requires AsyncLocalStorage propagation — deferred until that infrastructure
- * exists. For now, services inject `@inject("TracingManagerInterface") private readonly
- * tracingManager: TracingManagerInterface` and pass it through.
- *
- * On thrown errors: the error's name/message is attached to the span's context (visible
- * in the rendered tree/json output) and then re-thrown. The span is ended either way.
- *
- * Stateless — instantiate once and reuse, or use the exported singleton `spanRunner`.
- */
-export declare class SpanRunner {
-    /**
-     * Runs `fn` inside a span. See class docs for full semantics.
-     *
-     * @typeParam T The return type of `fn`. Always wrapped in `Promise<T>` because the
-     *   helper awaits internally — a sync `fn` works fine, but the return type loses its
-     *   sync-ness.
-     */
-    runWithSpan<T>(tracingManager: TracingManagerInterface, spanKeyname: string, fn: () => Promise<T> | T, options?: SpanRunnerOptions): Promise<T>;
-}
-/**
- * Default singleton. Stateless so sharing is safe.
- */
-export declare const spanRunner: SpanRunner;
+export { SpanRunner, SpanRunnerOptions, spanRunner } from "@pristine-ts/common";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/telemetry",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "",
   "module": "dist/lib/esm/telemetry.module.js",
   "main": "dist/lib/cjs/telemetry.module.js",
@@ -12,8 +12,8 @@
     "test:cov": "jest --coverage"
   },
   "dependencies": {
-    "@pristine-ts/common": "^2.0.2",
-    "@pristine-ts/logging": "^2.0.2",
+    "@pristine-ts/common": "^2.0.4",
+    "@pristine-ts/logging": "^2.0.4",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
@@ -61,7 +61,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "b0899c7eb6b34a99c6df0739507b1458549a0009",
+  "gitHead": "f376d34e13c1b17b7764c0b47708148e4e51390b",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",