@pristine-ts/telemetry 2.0.1 → 2.0.3

package/dist/lib/esm/utils/trace-renderer.js

@@ -0,0 +1,124 @@
+/**
+ * Pure-function renderers for `Trace` objects. Used by both `ConsoleTracer` (writes to
+ * stdout) and `FileTracer` (writes to disk) so the visual output is identical regardless
+ * of destination. All methods are stateless — instantiate once and reuse, or use the
+ * exported singleton `traceRenderer` if you don't care.
+ */
+export class TraceRenderer {
+    /**
+     * Indented ASCII tree mirroring the span hierarchy. Right-aligned durations, slowest
+     * leaf span flagged as `← bottleneck`. Best for human readers.
+     *
+     * Internal/parent spans are skipped for bottleneck detection on purpose: a parent's
+     * duration is the sum of its children's work, so it would always dwarf any single
+     * leaf and the flag would never highlight where the actual time was spent.
+     */
+    renderTree(trace) {
+        const lines = [];
+        lines.push(`Trace ${trace.id} — ${trace.getDuration()}ms`);
+        if (trace.rootSpan === undefined) {
+            lines.push("  (no rootSpan)");
+            return lines.join("\n");
+        }
+        // Pre-walk to find the slowest leaf for the bottleneck flag.
+        let slowestSpan;
+        let slowestDuration = -1;
+        this.walkSpans(trace.rootSpan, (s) => {
+            if (s.children.length > 0)
+                return;
+            const d = s.getDuration();
+            if (d > slowestDuration) {
+                slowestDuration = d;
+                slowestSpan = s;
+            }
+        });
+        const rows = [];
+        const renderNode = (span, ancestorIsLast) => {
+            const prefix = ancestorIsLast.length === 0
+                ? ""
+                : ancestorIsLast.slice(0, -1).map(isLast => isLast ? "    " : "│   ").join("")
+                    + (ancestorIsLast[ancestorIsLast.length - 1] ? "└── " : "├── ");
+            rows.push({
+                prefix,
+                name: span.keyname,
+                duration: span.getDuration(),
+                isBottleneck: span === slowestSpan && slowestDuration > 0,
+            });
+            span.children.forEach((child, idx) => {
+                const isLast = idx === span.children.length - 1;
+                renderNode(child, [...ancestorIsLast, isLast]);
+            });
+        };
+        renderNode(trace.rootSpan, []);
+        // Pad name column so durations line up.
+        const nameColumnWidth = Math.max(...rows.map(r => r.prefix.length + r.name.length));
+        for (const row of rows) {
+            const padding = " ".repeat(Math.max(1, nameColumnWidth - row.prefix.length - row.name.length + 2));
+            const durationCell = `${row.duration}ms`.padStart(8);
+            const marker = row.isBottleneck ? "  ← bottleneck" : "";
+            lines.push(`${row.prefix}${row.name}${padding}${durationCell}${marker}`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * One line per span sorted by start time, no indentation. Best for grep / log
+     * aggregation.
+     */
+    renderFlat(trace) {
+        const lines = [`Trace ${trace.id} — ${trace.getDuration()}ms`];
+        const all = [];
+        if (trace.rootSpan !== undefined) {
+            this.walkSpans(trace.rootSpan, (s) => all.push(s));
+        }
+        all.sort((a, b) => a.startDate - b.startDate);
+        for (const span of all) {
+            lines.push(`  ${span.keyname.padEnd(48)} ${`${span.getDuration()}ms`.padStart(8)}`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Pretty-printed JSON dump of the trace + every span. Best for piping into a downstream
+     * tool that wants structured access.
+     */
+    renderJson(trace) {
+        return JSON.stringify(this.serialize(trace), null, 2);
+    }
+    /**
+     * Serializes a trace to a plain JSON-friendly object. Exposed for callers that want to
+     * embed the structured form in a larger payload (e.g. a NDJSON line).
+     */
+    serialize(trace) {
+        return {
+            id: trace.id,
+            startDate: trace.startDate,
+            endDate: trace.endDate,
+            duration: trace.getDuration(),
+            context: trace.context,
+            rootSpan: trace.rootSpan ? this.serializeSpan(trace.rootSpan) : undefined,
+        };
+    }
+    serializeSpan(span) {
+        return {
+            id: span.id,
+            keyname: span.keyname,
+            startDate: span.startDate,
+            endDate: span.endDate,
+            duration: span.getDuration(),
+            context: span.context,
+            children: span.children.map(s => this.serializeSpan(s)),
+        };
+    }
+    /** Depth-first traversal helper. Visits the root and every descendant once. */
+    walkSpans(span, visit) {
+        visit(span);
+        for (const child of span.children) {
+            this.walkSpans(child, visit);
+        }
+    }
+}
+/**
+ * Default singleton. Use this from any caller that doesn't care to construct its own —
+ * the class is stateless so sharing is safe.
+ */
+export const traceRenderer = new TraceRenderer();
+//# sourceMappingURL=trace-renderer.js.map

package/dist/lib/esm/utils/trace-renderer.js.map

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

package/dist/lib/esm/utils/utils.js

@@ -0,0 +1,3 @@
+export * from "./span-runner";
+export * from "./trace-renderer";
+//# sourceMappingURL=utils.js.map

package/dist/lib/esm/utils/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/utils/utils.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC"}

package/dist/types/decorators/decorators.d.ts

@@ -0,0 +1 @@
+export * from "./traced.decorator";

package/dist/types/decorators/traced.decorator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Method decorator that wraps the decorated method in a span. The span is automatically
+ * ended when the method returns or throws, and the `TracingManager` is auto-resolved
+ * from the active `EventContext` — no need to inject it manually.
+ *
+ * ```ts
+ * class PaymentService {
+ *   @traced()                                // span name = "PaymentService.charge"
+ *   async charge(amount: number) { ... }
+ *
+ *   @traced("payment.refund.action")         // explicit name
+ *   async refund(chargeId: string) { ... }
+ * }
+ * ```
+ *
+ * **Behavior outside an event context.** When the decorated method runs without an
+ * active `EventContext` (e.g. a unit test calling the method directly, or background
+ * work that escaped the event lifecycle), the decorator is a no-op — the original
+ * method runs unchanged. Tracing must never throw or alter semantics.
+ *
+ * **Sync methods become async.** The decorator awaits the wrapped method internally,
+ * so any decorated method returns a `Promise`. Decorating a sync method changes its
+ * signature visible to callers — apply `@traced` to methods you'd already be awaiting
+ * (DB calls, HTTP, expensive computations), not to tight sync helpers.
+ *
+ * **Type-level caveat.** TypeScript's parameter and method decorator types don't carry
+ * enough information for the compiler to verify that the wrapped method's return type
+ * is compatible with `Promise<T>`. The wrapper is type-safe at runtime; the call site's
+ * static types are unchanged. Pair with explicit `: Promise<T>` annotations on the
+ * method when you want the static type to match what's actually returned.
+ *
+ * @param spanName Optional explicit name for the span. Defaults to
+ *   `${ClassName}.${methodName}`.
+ */
+export declare function traced(spanName?: string): MethodDecorator;

package/dist/types/enums/console-tracer-output-mode.enum.d.ts

@@ -0,0 +1,11 @@
+/**
+ * How `ConsoleTracer` renders a completed trace.
+ */
+export declare enum ConsoleTracerOutputModeEnum {
+    /** Indented ASCII tree mirroring the span hierarchy. Best for human readers. */
+    Tree = "tree",
+    /** Pretty-printed JSON dump of the trace + every span. Best for piping into a tool. */
+    Json = "json",
+    /** One span per line, no indentation, sorted by start time. Best for grep. */
+    Flat = "flat"
+}

package/dist/types/enums/enums.d.ts

@@ -1 +1,2 @@
+export * from "./console-tracer-output-mode.enum";
 export * from "./span-keyname.enum";

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

@@ -8,6 +8,14 @@ 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.
+ *
+ * **Lifecycle: container-scoped, not singleton.** Each per-event DI child container gets
+ * its own `TracingManager` instance with its own `trace` and `spans` state. Earlier
+ * versions used `@singleton()` — a single instance shared across every event — which
+ * was a latent bug: parallel events would clobber each other's `this.trace`. Resolving
+ * `TracingManager` from the root container still returns the root instance (used for
+ * kernel-initialization spans before any event has started); resolving from a child
+ * container returns the per-event instance, which is what application code wants.
  */
 export declare class TracingManager implements TracingManagerInterface {
     private readonly tracers;
@@ -53,7 +61,9 @@ export declare class TracingManager implements TracingManagerInterface {
      * @param parentId The id of the parent span.
      * @param context The context if there is one.
      */
-    startSpan(keyname: string, parentKeyname?: string, parentId?: string, context?: any): Span;
+    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.

package/dist/types/telemetry.configuration-keys.d.ts

@@ -12,7 +12,15 @@
 export declare const TelemetryConfigurationKeys: {
     readonly Active: "pristine.telemetry.active";
     readonly Debug: "pristine.telemetry.debug";
+    readonly ConsoleTracerActivated: "pristine.telemetry.console-tracer.activated";
+    readonly ConsoleTracerOutputMode: "pristine.telemetry.console-tracer.output-mode";
+    readonly ConsoleTracerMinimumDurationMs: "pristine.telemetry.console-tracer.minimum-duration-ms";
+    readonly FileTracerActivated: "pristine.telemetry.file-tracer.activated";
+    readonly FileTracerOutputMode: "pristine.telemetry.file-tracer.output-mode";
+    readonly FileTracerDirectory: "pristine.telemetry.file-tracer.directory";
+    readonly FileTracerFilenamePattern: "pristine.telemetry.file-tracer.filename-pattern";
 };
+import { ConsoleTracerOutputModeEnum } from "./enums/console-tracer-output-mode.enum";
 /**
  * The expected runtime types for each configuration value defined by `@pristine-ts/telemetry`.
  * See `AwsConfigurationValueMap` in `@pristine-ts/aws` for the full pattern + caveats.
@@ -20,6 +28,13 @@ export declare const TelemetryConfigurationKeys: {
 export interface TelemetryConfigurationValueMap {
     "pristine.telemetry.active": boolean;
     "pristine.telemetry.debug": boolean;
+    "pristine.telemetry.console-tracer.activated": boolean;
+    "pristine.telemetry.console-tracer.output-mode": ConsoleTracerOutputModeEnum;
+    "pristine.telemetry.console-tracer.minimum-duration-ms": number;
+    "pristine.telemetry.file-tracer.activated": boolean;
+    "pristine.telemetry.file-tracer.output-mode": ConsoleTracerOutputModeEnum;
+    "pristine.telemetry.file-tracer.directory": string;
+    "pristine.telemetry.file-tracer.filename-pattern": string;
 }
 /**
  * Augments the global `PristineConfigurationValueMap` (defined in `@pristine-ts/common`)

package/dist/types/telemetry.module.d.ts

@@ -1,8 +1,10 @@
 import { ModuleInterface } from "@pristine-ts/common";
+export * from "./decorators/decorators";
 export * from "./enums/enums";
 export * from "./interfaces/interfaces";
 export * from "./managers/managers";
 export * from "./models/models";
 export * from "./tracers/tracers";
+export * from "./utils/utils";
 export * from "./telemetry.configuration-keys";
 export declare const TelemetryModule: ModuleInterface;

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

@@ -0,0 +1,28 @@
+import { Readable } from "stream";
+import { LogHandlerInterface } from "@pristine-ts/logging";
+import { TracerInterface } from "../interfaces/tracer.interface";
+import { ConsoleTracerOutputModeEnum } from "../enums/console-tracer-output-mode.enum";
+/**
+ * `ConsoleTracer` prints a completed trace to stdout when the trace ends. Its main purpose
+ * is **developer-readable feedback during local development**: see what spans ran, in what
+ * order, and which one was the bottleneck — without wiring up an external tracing backend.
+ *
+ * Off by default. Enable via `pristine.telemetry.console-tracer.activated = true` (or
+ * `PRISTINE_TELEMETRY_CONSOLE_TRACER_ACTIVATED=true`). Three output modes:
+ *   - `tree` (default): indented ASCII tree, durations right-aligned, slowest leaf flagged.
+ *   - `json`: pretty-printed JSON dump.
+ *   - `flat`: one line per span, no indentation, start-time-sorted.
+ *
+ * Crash-isolated: a throw inside the formatting code becomes a stderr line, never an
+ * unhandled error or process crash.
+ */
+export declare class ConsoleTracer implements TracerInterface {
+    private readonly activated;
+    private readonly outputMode;
+    private readonly minimumDurationMs;
+    private readonly logHandler;
+    traceEndedStream: Readable;
+    constructor(activated: boolean, outputMode: ConsoleTracerOutputModeEnum, minimumDurationMs: number, logHandler: LogHandlerInterface);
+    private handleTraceEnded;
+    private reportFailure;
+}

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

@@ -0,0 +1,34 @@
+import { Readable } from "stream";
+import { LogHandlerInterface } from "@pristine-ts/logging";
+import { TracerInterface } from "../interfaces/tracer.interface";
+import { ConsoleTracerOutputModeEnum } from "../enums/console-tracer-output-mode.enum";
+/**
+ * `FileTracer` writes one file per completed trace to a configured directory. Files are
+ * named after the trace's id (= eventId throughout Pristine), so locating a request's
+ * trace is `cat traces/<eventId>.json`.
+ *
+ * Off by default. Enable via `pristine.telemetry.file-tracer.activated = true`.
+ *
+ * Configuration:
+ *   - `file-tracer.directory`         — defaults to `./traces`
+ *   - `file-tracer.filename-pattern`  — defaults to `<traceId>.json`. Placeholders:
+ *                                       `<traceId>`, `<date>` (UTC YYYY-MM-DD), `<timestamp>` (ms epoch).
+ *   - `file-tracer.output-mode`       — `json` (default), `tree`, or `flat`.
+ *
+ * Crash-isolated: a write failure (read-only fs, missing permissions, etc.) becomes a
+ * stderr line, never an unhandled error. The framework continues and the next trace is
+ * attempted independently.
+ */
+export declare class FileTracer implements TracerInterface {
+    private readonly activated;
+    private readonly outputMode;
+    private readonly directory;
+    private readonly filenamePattern;
+    private readonly logHandler;
+    traceEndedStream: Readable;
+    constructor(activated: boolean, outputMode: ConsoleTracerOutputModeEnum, directory: string, filenamePattern: string, logHandler: LogHandlerInterface);
+    private handleTraceEnded;
+    private renderTrace;
+    private expandFilenamePattern;
+    private reportFailure;
+}

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

@@ -1 +1,2 @@
-export * from "./basic.tracer";
+export * from "./console.tracer";
+export * from "./file.tracer";

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

@@ -0,0 +1,55 @@
+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.
+ *
+ * Two call shapes are supported:
+ *
+ * **Explicit form** (`runWithSpan(tracingManager, name, fn)`) — pass the manager you've
+ * already injected. Works anywhere, including outside an event context. Use this when
+ * you have a `TracingManager` reference in hand:
+ *
+ * ```ts
+ * return spanRunner.runWithSpan(this.tracingManager, "payment.charge",
+ *   () => this.client.charge(amount));
+ * ```
+ *
+ * **ALS form** (`runWithSpan(name, fn)`) — auto-resolves the `TracingManager` from the
+ * active `EventContext`'s container. Concise; works when called from anywhere inside
+ * a Pristine event (controller, service, etc.) without needing the manager threaded
+ * through:
+ *
+ * ```ts
+ * return spanRunner.runWithSpan("payment.charge", () => this.client.charge(amount));
+ * ```
+ *
+ * If the ALS form is used outside any `EventContext` (e.g. a unit test that doesn't
+ * boot a kernel), no span is created and `fn` runs unchanged — same no-throw contract
+ * as the rest of the tracing layer.
+ *
+ * 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 {
+    runWithSpan<T>(tracingManager: TracingManagerInterface, spanKeyname: string, fn: () => Promise<T> | T, options?: SpanRunnerOptions): Promise<T>;
+    runWithSpan<T>(spanKeyname: string, fn: () => Promise<T> | T, options?: SpanRunnerOptions): Promise<T>;
+}
+/**
+ * Default singleton. Stateless so sharing is safe.
+ */
+export declare const spanRunner: SpanRunner;

package/dist/types/utils/trace-renderer.d.ts

@@ -0,0 +1,41 @@
+import { Trace } from "../models/trace.model";
+/**
+ * Pure-function renderers for `Trace` objects. Used by both `ConsoleTracer` (writes to
+ * stdout) and `FileTracer` (writes to disk) so the visual output is identical regardless
+ * of destination. All methods are stateless — instantiate once and reuse, or use the
+ * exported singleton `traceRenderer` if you don't care.
+ */
+export declare class TraceRenderer {
+    /**
+     * Indented ASCII tree mirroring the span hierarchy. Right-aligned durations, slowest
+     * leaf span flagged as `← bottleneck`. Best for human readers.
+     *
+     * Internal/parent spans are skipped for bottleneck detection on purpose: a parent's
+     * duration is the sum of its children's work, so it would always dwarf any single
+     * leaf and the flag would never highlight where the actual time was spent.
+     */
+    renderTree(trace: Trace): string;
+    /**
+     * One line per span sorted by start time, no indentation. Best for grep / log
+     * aggregation.
+     */
+    renderFlat(trace: Trace): string;
+    /**
+     * Pretty-printed JSON dump of the trace + every span. Best for piping into a downstream
+     * tool that wants structured access.
+     */
+    renderJson(trace: Trace): string;
+    /**
+     * Serializes a trace to a plain JSON-friendly object. Exposed for callers that want to
+     * embed the structured form in a larger payload (e.g. a NDJSON line).
+     */
+    serialize(trace: Trace): Record<string, unknown>;
+    private serializeSpan;
+    /** Depth-first traversal helper. Visits the root and every descendant once. */
+    private walkSpans;
+}
+/**
+ * Default singleton. Use this from any caller that doesn't care to construct its own —
+ * the class is stateless so sharing is safe.
+ */
+export declare const traceRenderer: TraceRenderer;

package/dist/types/utils/utils.d.ts

@@ -0,0 +1,2 @@
+export * from "./span-runner";
+export * from "./trace-renderer";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/telemetry",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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.1",
-    "@pristine-ts/logging": "^2.0.1",
+    "@pristine-ts/common": "^2.0.3",
+    "@pristine-ts/logging": "^2.0.3",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
@@ -61,7 +61,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "a5e40ea0fcdeaf743666c1981a9315bfde9c4c00",
+  "gitHead": "c741bb430ab8f6286068dc3870fcadf4cefd0023",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",

package/dist/lib/cjs/tracers/basic.tracer.js

@@ -1,50 +0,0 @@
-"use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.XrayTracer = void 0;
-const tsyringe_1 = require("tsyringe");
-const common_1 = require("@pristine-ts/common");
-const stream_1 = require("stream");
-/**
- * We need this to have at least one tracer so the @injectAll(ServiceDefinitionTagEnum.Tracer) does not fail
- * Until there's a fix for: https://github.com/microsoft/tsyringe/issues/63
- */
-let XrayTracer = class XrayTracer {
-    constructor() {
-        this.spanStartedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.spanEndedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceStartedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceEndedStream = new stream_1.Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-    }
-};
-exports.XrayTracer = XrayTracer;
-exports.XrayTracer = XrayTracer = __decorate([
-    (0, common_1.tag)(common_1.ServiceDefinitionTagEnum.Tracer),
-    (0, tsyringe_1.injectable)()
-], XrayTracer);
-//# sourceMappingURL=basic.tracer.js.map

package/dist/lib/cjs/tracers/basic.tracer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"basic.tracer.js","sourceRoot":"","sources":["../../../../src/tracers/basic.tracer.ts"],"names":[],"mappings":";;;;;;;;;AAAA,uCAAoC;AACpC,gDAAkE;AAClE,mCAAgC;AAGhC;;;GAGG;AAGI,IAAM,UAAU,GAAhB,MAAM,UAAU;IAAhB;QACL,sBAAiB,GAAc,IAAI,iBAAQ,CAAC;YAC1C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,oBAAe,GAAc,IAAI,iBAAQ,CAAC;YACxC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,uBAAkB,GAAc,IAAI,iBAAQ,CAAC;YAC3C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,qBAAgB,GAAc,IAAI,iBAAQ,CAAC;YACzC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;IACL,CAAC;CAAA,CAAA;AAzBY,gCAAU;qBAAV,UAAU;IAFtB,IAAA,YAAG,EAAC,iCAAwB,CAAC,MAAM,CAAC;IACpC,IAAA,qBAAU,GAAE;GACA,UAAU,CAyBtB"}

package/dist/lib/esm/tracers/basic.tracer.js

@@ -1,47 +0,0 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { injectable } from "tsyringe";
-import { ServiceDefinitionTagEnum, tag } from "@pristine-ts/common";
-import { Readable } from "stream";
-/**
- * We need this to have at least one tracer so the @injectAll(ServiceDefinitionTagEnum.Tracer) does not fail
- * Until there's a fix for: https://github.com/microsoft/tsyringe/issues/63
- */
-let XrayTracer = class XrayTracer {
-    constructor() {
-        this.spanStartedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.spanEndedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceStartedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-        this.traceEndedStream = new Readable({
-            objectMode: true,
-            read(size) {
-                return true;
-            }
-        });
-    }
-};
-XrayTracer = __decorate([
-    tag(ServiceDefinitionTagEnum.Tracer),
-    injectable()
-], XrayTracer);
-export { XrayTracer };
-//# sourceMappingURL=basic.tracer.js.map

package/dist/lib/esm/tracers/basic.tracer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"basic.tracer.js","sourceRoot":"","sources":["../../../../src/tracers/basic.tracer.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AACpC,OAAO,EAAC,wBAAwB,EAAE,GAAG,EAAC,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAC,QAAQ,EAAC,MAAM,QAAQ,CAAC;AAGhC;;;GAGG;AAGI,IAAM,UAAU,GAAhB,MAAM,UAAU;IAAhB;QACL,sBAAiB,GAAc,IAAI,QAAQ,CAAC;YAC1C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,oBAAe,GAAc,IAAI,QAAQ,CAAC;YACxC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,uBAAkB,GAAc,IAAI,QAAQ,CAAC;YAC3C,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;QACH,qBAAgB,GAAc,IAAI,QAAQ,CAAC;YACzC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,IAAY;gBACf,OAAO,IAAI,CAAC;YACd,CAAC;SACF,CAAC,CAAC;IACL,CAAC;CAAA,CAAA;AAzBY,UAAU;IAFtB,GAAG,CAAC,wBAAwB,CAAC,MAAM,CAAC;IACpC,UAAU,EAAE;GACA,UAAU,CAyBtB"}

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

@@ -1,12 +0,0 @@
-import { Readable } from "stream";
-import { TracerInterface } from "../interfaces/tracer.interface";
-/**
- * We need this to have at least one tracer so the @injectAll(ServiceDefinitionTagEnum.Tracer) does not fail
- * Until there's a fix for: https://github.com/microsoft/tsyringe/issues/63
- */
-export declare class XrayTracer implements TracerInterface {
-    spanStartedStream?: Readable;
-    spanEndedStream?: Readable;
-    traceStartedStream?: Readable;
-    traceEndedStream?: Readable;
-}