@pristine-ts/observability 2.0.16

package/dist/lib/esm/store/trace-store.js

@@ -0,0 +1,245 @@
+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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import * as fs from "fs";
+import { inject, injectable, singleton } from "tsyringe";
+import { injectConfig, InternalContainerParameterEnum, moduleScoped } from "@pristine-ts/common";
+import { traceRenderer } from "@pristine-ts/telemetry";
+import { ObservabilityModuleKeyname } from "../observability.module.keyname";
+import { ObservabilityConfigurationKeys } from "../observability.configuration-keys";
+import { RequestSummary } from "../models/request-summary.model";
+import { ObservabilityPaths } from "../paths/observability-paths";
+import { TraceDeserializer } from "../serializers/trace-deserializer";
+/**
+ * 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.
+ */
+let TraceStore = class TraceStore {
+    constructor(enabled, directory, retainedInstances, partitionId) {
+        this.enabled = enabled;
+        this.retainedInstances = retainedInstances;
+        this.partitionId = partitionId;
+        this.directoryEnsured = false;
+        this.pruned = false;
+        this.paths = new ObservabilityPaths(directory);
+    }
+    /**
+     * 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) {
+        if (this.enabled === false) {
+            return;
+        }
+        this.ensurePartitionDirectory();
+        const eventId = this.eventIdOf(trace);
+        const traceContent = traceRenderer.renderJson(trace);
+        const summary = this.buildSummary(trace, eventId);
+        const requestLine = JSON.stringify(summary) + "\n";
+        fs.writeFileSync(this.paths.traceFile(this.partitionId, eventId), traceContent);
+        fs.appendFileSync(this.paths.requestsFile(this.partitionId), requestLine);
+    }
+    /**
+     * 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) {
+        const serialized = this.findSerialized(id);
+        if (serialized === undefined) {
+            return undefined;
+        }
+        return { trace: TraceDeserializer.deserialize(serialized.trace), eventId: serialized.eventId };
+    }
+    /**
+     * 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) {
+        for (const partition of this.partitionsNewestFirst()) {
+            // Try direct file lookup first — `id` IS the eventId in the common case.
+            const direct = this.tryLoadTrace(partition, id);
+            if (direct !== undefined) {
+                return { trace: direct, eventId: id };
+            }
+            // Else resolve via the summary index — `id` might be a divergent traceId/requestId.
+            const eventId = this.resolveEventIdFromSummaries(partition, id);
+            if (eventId !== undefined) {
+                const trace = this.tryLoadTrace(partition, eventId);
+                if (trace !== undefined) {
+                    return { trace, eventId };
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Recent request summaries across every partition, most-recent first, optionally
+     * capped to `limit`.
+     */
+    recentRequests(limit) {
+        const all = [];
+        for (const partition of this.partitionsNewestFirst()) {
+            all.push(...this.readSummaries(partition));
+        }
+        all.sort((a, b) => b.startedAt - a.startedAt);
+        return limit === undefined ? all : all.slice(0, limit);
+    }
+    /**
+     * The most recent event ids across all partitions — used by the REPL completer.
+     */
+    recentTraceIds(limit) {
+        return this.recentRequests(limit).map(summary => summary.eventId);
+    }
+    buildSummary(trace, eventId) {
+        var _a, _b, _c;
+        const context = (_a = trace.context) !== null && _a !== void 0 ? _a : {};
+        const summary = new RequestSummary(eventId, trace.startDate, trace.getDuration(), (_c = (_b = trace.rootSpan) === null || _b === void 0 ? void 0 : _b.keyname) !== null && _c !== void 0 ? _c : "");
+        // Only persist divergent ids — the common case is all three values equal.
+        if (trace.id !== eventId) {
+            summary.traceId = trace.id;
+        }
+        const requestId = context["request.id"];
+        if (typeof requestId === "string" && requestId !== eventId) {
+            summary.requestId = requestId;
+        }
+        summary.httpMethod = context["http.method"];
+        summary.httpPath = context["http.path"];
+        const status = context["http.statusCode"];
+        if (status !== undefined) {
+            const parsed = Number(status);
+            summary.httpStatus = Number.isNaN(parsed) ? undefined : parsed;
+        }
+        return summary;
+    }
+    /**
+     * 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`.
+     */
+    eventIdOf(trace) {
+        var _a;
+        const fromContext = (_a = trace.context) === null || _a === void 0 ? void 0 : _a["event.id"];
+        return typeof fromContext === "string" && fromContext.length > 0 ? fromContext : trace.id;
+    }
+    resolveEventIdFromSummaries(partition, id) {
+        for (const summary of this.readSummaries(partition)) {
+            if (summary.eventId === id || summary.traceId === id || summary.requestId === id) {
+                return summary.eventId;
+            }
+        }
+        return undefined;
+    }
+    tryLoadTrace(partition, eventId) {
+        try {
+            return JSON.parse(fs.readFileSync(this.paths.traceFile(partition, eventId), "utf8"));
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    readSummaries(partition) {
+        return this.readJsonl(this.paths.requestsFile(partition));
+    }
+    ensurePartitionDirectory() {
+        if (this.directoryEnsured) {
+            return;
+        }
+        fs.mkdirSync(this.paths.tracesDirectory(this.partitionId), { recursive: true });
+        this.directoryEnsured = true;
+        this.pruneOldPartitions();
+    }
+    /**
+     * Drops partition directories beyond the retained limit, ordered by `mtime`. Once
+     * per process. Best-effort: a failure to prune never blocks a write.
+     */
+    pruneOldPartitions() {
+        if (this.pruned) {
+            return;
+        }
+        this.pruned = true;
+        try {
+            const ordered = this.partitionsNewestFirst();
+            for (const stale of ordered.slice(Math.max(this.retainedInstances, 1))) {
+                fs.rmSync(this.paths.instanceDirectory(stale), { recursive: true, force: true });
+            }
+        }
+        catch (_a) {
+            // Best-effort.
+        }
+    }
+    partitionsNewestFirst() {
+        try {
+            return fs.readdirSync(this.paths.root, { withFileTypes: true })
+                .filter(entry => entry.isDirectory())
+                .map(entry => ({ name: entry.name, mtime: this.directoryMtime(entry.name) }))
+                .sort((a, b) => b.mtime - a.mtime)
+                .map(entry => entry.name);
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+    directoryMtime(name) {
+        try {
+            return fs.statSync(this.paths.instanceDirectory(name)).mtimeMs;
+        }
+        catch (_a) {
+            return 0;
+        }
+    }
+    readJsonl(filePath) {
+        try {
+            return fs.readFileSync(filePath, "utf8")
+                .split("\n")
+                .filter(line => line.trim().length > 0)
+                .map(line => JSON.parse(line));
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+};
+TraceStore = __decorate([
+    moduleScoped(ObservabilityModuleKeyname),
+    singleton(),
+    injectable(),
+    __param(0, injectConfig(ObservabilityConfigurationKeys.Enabled)),
+    __param(1, injectConfig(ObservabilityConfigurationKeys.Directory)),
+    __param(2, injectConfig(ObservabilityConfigurationKeys.RetainedInstances)),
+    __param(3, inject(InternalContainerParameterEnum.KernelInstantiationId)),
+    __metadata("design:paramtypes", [Boolean, String, Number, String])
+], TraceStore);
+export { TraceStore };
+//# sourceMappingURL=trace-store.js.map

package/dist/lib/esm/store/trace-store.js.map

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

package/dist/lib/esm/tailers/log-tailer.js

@@ -0,0 +1,73 @@
+import * as fs from "fs";
+import * as path from "path";
+/**
+ * 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 class LogTailer {
+    constructor(filePath) {
+        this.filePath = filePath;
+        this.offset = 0;
+        this.buffer = "";
+    }
+    /**
+     * Starts following. Existing content is skipped — only lines appended after this call
+     * are emitted. Call `stop()` to release the watch.
+     */
+    follow(onLine) {
+        this.offset = fs.existsSync(this.filePath) ? fs.statSync(this.filePath).size : 0;
+        const directory = path.dirname(this.filePath);
+        const filename = path.basename(this.filePath);
+        this.watcher = fs.watch(directory, (_eventType, changed) => {
+            if (changed !== null && changed !== filename) {
+                return;
+            }
+            this.drain(onLine);
+        });
+    }
+    /**
+     * Stops following and releases the filesystem watch.
+     */
+    stop() {
+        var _a;
+        (_a = this.watcher) === null || _a === void 0 ? void 0 : _a.close();
+        this.watcher = undefined;
+    }
+    drain(onLine) {
+        var _a;
+        if (fs.existsSync(this.filePath) === false) {
+            return;
+        }
+        const size = fs.statSync(this.filePath).size;
+        if (size <= this.offset) {
+            // Truncated or unchanged — reset to the new end so we don't replay stale bytes.
+            this.offset = size;
+            return;
+        }
+        const fd = fs.openSync(this.filePath, "r");
+        try {
+            const length = size - this.offset;
+            const chunk = Buffer.alloc(length);
+            fs.readSync(fd, chunk, 0, length, this.offset);
+            this.offset = size;
+            this.buffer += chunk.toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        const lines = this.buffer.split("\n");
+        this.buffer = (_a = lines.pop()) !== null && _a !== void 0 ? _a : "";
+        for (const line of lines) {
+            if (line.length > 0) {
+                onLine(line);
+            }
+        }
+    }
+}
+//# sourceMappingURL=log-tailer.js.map

package/dist/lib/esm/tailers/log-tailer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-tailer.js","sourceRoot":"","sources":["../../../../src/tailers/log-tailer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;GASG;AACH,MAAM,OAAO,SAAS;IAKpB,YAA6B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;QAHrC,WAAM,GAAG,CAAC,CAAC;QACX,WAAM,GAAG,EAAE,CAAC;IAGpB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,MAA8B;QACnC,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAEjF,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE9C,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE;YACzD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC7C,OAAO;YACT,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI;;QACF,MAAA,IAAI,CAAC,OAAO,0CAAE,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;IAC3B,CAAC;IAEO,KAAK,CAAC,MAA8B;;QAC1C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,KAAK,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;QAC7C,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACxB,gFAAgF;YAChF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,OAAO;QACT,CAAC;QAED,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;YAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACnC,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC/C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;gBAAS,CAAC;YACT,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACnB,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAA,KAAK,CAAC,GAAG,EAAE,mCAAI,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,CAAC,CAAC;YACf,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/lib/esm/tailers/tailers.js

@@ -0,0 +1,2 @@
+export * from "./log-tailer";
+//# sourceMappingURL=tailers.js.map

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

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

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

@@ -0,0 +1,62 @@
+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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Readable } from "stream";
+import { injectable, singleton } from "tsyringe";
+import { moduleScoped, ServiceDefinitionTagEnum, tag } from "@pristine-ts/common";
+import { ObservabilityModuleKeyname } from "../observability.module.keyname";
+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.
+ */
+let ObservabilityTracer = class ObservabilityTracer {
+    constructor(traceStore) {
+        this.traceStore = traceStore;
+        this.traceEndedStream = new Readable({
+            objectMode: true,
+            read(_size) { return true; },
+        });
+        this.traceEndedStream.on("data", (trace) => {
+            try {
+                this.traceStore.append(trace);
+            }
+            catch (error) {
+                this.reportFailure(error);
+            }
+        });
+        this.traceEndedStream.on("error", (error) => {
+            this.reportFailure(error);
+        });
+    }
+    reportFailure(error) {
+        try {
+            // Stringification happens inside the guard — `error.name`/`error.message`/`String(error)`
+            // can all throw on pathological inputs (throwing getters, exotic `Symbol.toPrimitive`,
+            // etc.). The safety net must not become the new failure source.
+            const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            process.stderr.write(`[pristine][observability-tracer] ${message}\n`);
+        }
+        catch (_a) {
+            // If even stringifying or writing fails, there is nothing useful left to do.
+        }
+    }
+};
+ObservabilityTracer = __decorate([
+    moduleScoped(ObservabilityModuleKeyname),
+    singleton(),
+    tag(ServiceDefinitionTagEnum.Tracer),
+    injectable(),
+    __metadata("design:paramtypes", [TraceStore])
+], ObservabilityTracer);
+export { ObservabilityTracer };
+//# sourceMappingURL=observability.tracer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observability.tracer.js","sourceRoot":"","sources":["../../../../src/tracers/observability.tracer.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAC,YAAY,EAAE,wBAAwB,EAAE,GAAG,EAAQ,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAAC,0BAA0B,EAAC,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAC,UAAU,EAAC,MAAM,sBAAsB,CAAC;AAEhD;;;;;;GAMG;AAKI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAG9B,YAA6B,UAAsB;QAAtB,eAAU,GAAV,UAAU,CAAY;QACjD,IAAI,CAAC,gBAAgB,GAAG,IAAI,QAAQ,CAAC;YACnC,UAAU,EAAE,IAAI;YAChB,IAAI,CAAC,KAAa,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC;SACrC,CAAC,CAAC;QAEH,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAY,EAAE,EAAE;YAChD,IAAI,CAAC;gBACH,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,aAAa,CAAC,KAAc;QAClC,IAAI,CAAC;YACH,0FAA0F;YAC1F,uFAAuF;YACvF,gEAAgE;YAChE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,OAAO,IAAI,CAAC,CAAC;QACxE,CAAC;QAAC,WAAM,CAAC;YACP,6EAA6E;QAC/E,CAAC;IACH,CAAC;CACF,CAAA;AAjCY,mBAAmB;IAJ/B,YAAY,CAAC,0BAA0B,CAAC;IACxC,SAAS,EAAE;IACX,GAAG,CAAC,wBAAwB,CAAC,MAAM,CAAC;IACpC,UAAU,EAAE;qCAI8B,UAAU;GAHxC,mBAAmB,CAiC/B"}

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

@@ -0,0 +1,2 @@
+export * from "./observability.tracer";
+//# sourceMappingURL=tracers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tracers.js","sourceRoot":"","sources":["../../../../src/tracers/tracers.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}