@adonis-agora/telescope 0.18.0 → 0.20.0

package/dist/src/otel/mapper.d.ts

@@ -0,0 +1,118 @@
+import type { Entry } from '../entry.js';
+/**
+ * The generic diagnostics-entry → OTel mapper. Pure, dependency-free (no
+ * `@opentelemetry/*` import anywhere in this file) so it is trivially unit-testable
+ * and so importing it never pulls in the OTel SDK — only `otel_exporter.ts` (which
+ * consumes this module's OUTPUT) does that, and only when OTel export is enabled.
+ *
+ * ## The mapping, in one paragraph
+ *
+ * Every recorded entry already carries a uniform shape (`type`, `content`, `tags`,
+ * `durationMs`, `traceId`, `createdAt` — see `entry.ts`). This module turns that
+ * shape into either a {@link SpanExportInput} or a {@link LogExportInput}:
+ *
+ * - **Has a duration → SPAN.** {@link resolveDurationMs} looks for it in two
+ *   places: the entry's own top-level `durationMs` (set for every `diagnostic`
+ *   entry whose envelope carried `@adonis-agora/diagnostics`'s `emit(..., {
+ *   durationMs })`), or — when absent — a numeric `payload.durationMs` field
+ *   (the convention several libs use when they stuff a richer lifecycle-event
+ *   object as the payload; `@adonis-agora/durable`'s diagnostics bridge is exactly
+ *   this: `emit('durable', event.type, event)` with `event.durationMs` inside).
+ *   The span's start time is reconstructed as `end - durationMs` (the event is
+ *   ALREADY FINISHED by the time telescope observes it — there is no live span to
+ *   attach to, only a historical record — the same reconstruction
+ *   `@adonis-agora/durable`'s bespoke `attachDurableOtel` uses for its step spans).
+ * - **No duration → LOG.** A point-in-time occurrence becomes an OTel log record
+ *   instead of a zero-duration span, which is both more idiomatic (Loki, not
+ *   Tempo, is where "something happened" belongs) and cheaper (one log record vs.
+ *   a full span with an implicit trace).
+ *
+ * Both forms share: a name/body of `agora.<lib>.<event>` (matching the naming
+ * `@adonis-agora/diagnostics`'s OWN OTel bridge uses for the SAME channels, so a
+ * host running both sees consistent naming), flattened scalar/array payload
+ * fields as `agora.payload.<key>` attributes, `agora.lib`/`agora.event` attributes,
+ * `agora.entry_id` (the Telescope entry id, so a span/log in Grafana links back to
+ * the exact entry in the Telescope dashboard), and error detection reusing the
+ * SAME `isErrorEntry` heuristic the sampling store already uses for `keepErrors`
+ * (kept consistent on purpose: "this looks like an error" should mean the same
+ * thing everywhere in this package) plus a couple of diagnostics-specific
+ * additions (`payload.error` truthy, or an event name containing `error`/`fail`)
+ * that `isErrorEntry` cannot see because it only reads shallow, entry-type-generic
+ * fields.
+ *
+ * ## Trace correlation
+ *
+ * `entry.traceId` is the trace id `@adonis-agora/context` resolved at record time —
+ * either a fresh random 16-byte value, or (when the inbound HTTP request carried
+ * one) the EXACT W3C `traceparent` trace-id, parsed byte-for-byte. When it is
+ * present AND well-formed (32 lowercase hex chars, not all-zero — see
+ * {@link isValidW3cTraceId}), the mapper carries it through so the exporter can
+ * parent the reconstructed span/log under it — the same correlation id a real
+ * OTel span from an instrumented gateway upstream would have used, so Tempo/Loki
+ * group them into the SAME trace even though telescope's span was synthesized
+ * after the fact from a diagnostics event, not from a live OTel context.
+ */
+/**
+ * An OTel attribute value: a primitive, or a HOMOGENEOUS array of one primitive
+ * type — matching `@opentelemetry/api`'s own `AttributeValue` exactly (a mixed
+ * `(string | number)[]` array is not a valid OTel attribute value), so a caller
+ * can pass this straight through to `Span.setAttribute`/`startSpan({ attributes })`
+ * with no cast.
+ */
+export type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+/** A flat attribute bag — every key namespaced `agora.*` by the builders below. */
+export type AttributeMap = Record<string, AttributeValue>;
+/** The pure, OTel-SDK-agnostic description of one reconstructed span. */
+export interface SpanExportInput {
+    /** `agora.<lib>.<event>`. */
+    name: string;
+    /** Epoch millis the operation started (`endTimeMs - durationMs`). */
+    startTimeMs: number;
+    /** Epoch millis the operation completed (the entry's timestamp). */
+    endTimeMs: number;
+    attributes: AttributeMap;
+    status: 'OK' | 'ERROR';
+    /** Present only when {@link status} is `'ERROR'`. */
+    errorMessage?: string;
+    /** A valid W3C trace id to parent the span under, or `null` when unavailable. */
+    traceId: string | null;
+}
+/** The pure, OTel-SDK-agnostic description of one log record. */
+export interface LogExportInput {
+    /** `agora.<lib>.<event>`. */
+    body: string;
+    /** Epoch millis the event occurred. */
+    timestampMs: number;
+    /** OTel numeric severity (`SeverityNumber` values — kept as a literal so this file needs no OTel import). */
+    severityNumber: number;
+    severityText: 'INFO' | 'WARN' | 'ERROR';
+    attributes: AttributeMap;
+    traceId: string | null;
+}
+/** Discriminated mapper result. `null` when the entry has no interpretable shape. */
+export type MappedEntry = {
+    kind: 'span';
+    span: SpanExportInput;
+} | {
+    kind: 'log';
+    log: LogExportInput;
+} | null;
+/** Whether `id` is a well-formed, non-zero W3C trace id (32 lowercase hex chars). */
+export declare function isValidW3cTraceId(id: string | null | undefined): id is string;
+/**
+ * Resolve the duration this entry describes, in ms, or `null` when it is a
+ * point-in-time occurrence with no associated duration. Checks the entry's own
+ * top-level `durationMs` first (the standard, entry-type-generic field every
+ * watcher can set — see `entry.ts`), falling back to a numeric
+ * `content.payload.durationMs` (the convention a diagnostics-bridged lifecycle
+ * event, e.g. `@adonis-agora/durable`'s, uses instead).
+ */
+export declare function resolveDurationMs(entry: Entry): number | null;
+/**
+ * Map one recorded {@link Entry} to a span or log export input, or `null` when it
+ * has no interpretable `{ lib, event }` shape (only `diagnostic`-shaped content —
+ * `lib`/`event` strings — is currently mapped; entries of other configured
+ * `entryTypes` degrade to `null`, i.e. skipped, until they get their own mapping).
+ */
+export declare function mapEntryToOtel(entry: Entry): MappedEntry;
+//# sourceMappingURL=mapper.d.ts.map

package/dist/src/otel/mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../../../src/otel/mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;AAEzF,mFAAmF;AACnF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE1D,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,YAAY,CAAC;IACzB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,6GAA6G;IAC7G,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACxC,UAAU,EAAE,YAAY,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,cAAc,CAAA;CAAE,GACpC,IAAI,CAAC;AAeT,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,EAAE,IAAI,MAAM,CAE7E;AASD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAI7D;AAgHD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,CAqCxD"}

package/dist/src/otel/mapper.js

@@ -0,0 +1,205 @@
+import { isErrorEntry } from '../sampling/sampling.js';
+const SEVERITY_NUMBER = {
+    // Mirrors `@opentelemetry/api-logs`' `SeverityNumber` enum values exactly
+    // (INFO=9, WARN=13, ERROR=17) without importing the package — this file must
+    // stay dependency-free. `otel_exporter.ts` only ever reads these as opaque
+    // numbers it forwards verbatim to the real `LogRecord`.
+    INFO: 9,
+    WARN: 13,
+    ERROR: 17,
+};
+const W3C_TRACE_ID_RE = /^[0-9a-f]{32}$/;
+const ALL_ZERO_TRACE_ID = '0'.repeat(32);
+/** Whether `id` is a well-formed, non-zero W3C trace id (32 lowercase hex chars). */
+export function isValidW3cTraceId(id) {
+    return typeof id === 'string' && W3C_TRACE_ID_RE.test(id) && id !== ALL_ZERO_TRACE_ID;
+}
+/** Best-effort read of a positive, finite numeric field off an unknown value. */
+function readPositiveNumber(value, key) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const raw = value[key];
+    return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : null;
+}
+/**
+ * Resolve the duration this entry describes, in ms, or `null` when it is a
+ * point-in-time occurrence with no associated duration. Checks the entry's own
+ * top-level `durationMs` first (the standard, entry-type-generic field every
+ * watcher can set — see `entry.ts`), falling back to a numeric
+ * `content.payload.durationMs` (the convention a diagnostics-bridged lifecycle
+ * event, e.g. `@adonis-agora/durable`'s, uses instead).
+ */
+export function resolveDurationMs(entry) {
+    if (typeof entry.durationMs === 'number' && entry.durationMs >= 0)
+        return entry.durationMs;
+    const content = entry.content;
+    return readPositiveNumber(content?.payload, 'durationMs');
+}
+/**
+ * True when `value` is a valid OTel attribute value: a primitive, or a
+ * HOMOGENEOUS array of one primitive type (nulls/undefined allowed as array
+ * holes, matching `@opentelemetry/api`'s own `AttributeValue`). A mixed-type
+ * array (`[1, 'a']`) is rejected — it has no valid OTel representation.
+ */
+function isAttributeValue(value) {
+    if (value === null || value === undefined)
+        return false;
+    const t = typeof value;
+    if (t === 'string' || t === 'number' || t === 'boolean')
+        return true;
+    if (Array.isArray(value)) {
+        const types = new Set(value.filter((v) => v !== null && v !== undefined).map((v) => typeof v));
+        if (types.size > 1)
+            return false;
+        const [only] = types;
+        return only === undefined || only === 'string' || only === 'number' || only === 'boolean';
+    }
+    return false;
+}
+/**
+ * Flatten a payload's own enumerable scalar/array fields into namespaced
+ * `agora.payload.<key>` attributes. Best-effort and bounded to the payload's OWN
+ * keys (one level — this is attribute flattening for search/filter, not a full
+ * structural dump; the complete payload is still visible in the Telescope entry
+ * itself via `agora.entry_id`). Never throws.
+ */
+function payloadAttributes(payload) {
+    const attrs = {};
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return attrs;
+    for (const [key, value] of Object.entries(payload)) {
+        if (isAttributeValue(value))
+            attrs[`agora.payload.${key}`] = value;
+    }
+    return attrs;
+}
+function asDiagnosticLike(content) {
+    if (content === null || typeof content !== 'object' || Array.isArray(content))
+        return null;
+    return content;
+}
+/**
+ * Whether this entry "looks like an error", for span status / log severity.
+ * Layers two checks:
+ *  1. {@link isErrorEntry} — the SAME shallow heuristic the sampling store's
+ *     `keepErrors` already uses (`tags` has `'failed'`, `content.failed === true`,
+ *     `content.statusCode >= 500`, or `content.level` is warn/error/fatal).
+ *  2. Diagnostics-specific additions `isErrorEntry` cannot see: a truthy
+ *     `payload.error` field (the `{ error }` shape lifecycle-event bridges commonly
+ *     use, e.g. `@adonis-agora/durable`'s `EngineEvent`), or an `event` name
+ *     containing `error`/`fail` (`'run.failed'`, `'step.failed'`, …).
+ */
+function looksLikeError(entry) {
+    if (isErrorEntry({ type: entry.type, content: entry.content, tags: entry.tags }))
+        return true;
+    const content = asDiagnosticLike(entry.content);
+    if (content === null)
+        return false;
+    const payload = content.payload;
+    if (payload !== null && typeof payload === 'object' && !Array.isArray(payload)) {
+        const error = payload.error;
+        if (error !== undefined && error !== null && error !== false)
+            return true;
+    }
+    if (typeof content.event === 'string') {
+        const lower = content.event.toLowerCase();
+        if (lower.includes('error') || lower.includes('fail'))
+            return true;
+    }
+    return false;
+}
+/** Read an explicit log level off the payload/content, when present, normalized to our severity trio. */
+function explicitSeverity(entry) {
+    const content = asDiagnosticLike(entry.content);
+    const payload = content?.payload !== null && typeof content?.payload === 'object'
+        ? content.payload
+        : null;
+    const raw = payload?.level ?? entry.content?.level;
+    if (typeof raw !== 'string')
+        return null;
+    const lower = raw.toLowerCase();
+    if (lower === 'warn' || lower === 'warning')
+        return 'WARN';
+    if (lower === 'error' || lower === 'fatal')
+        return 'ERROR';
+    if (lower === 'info' || lower === 'debug' || lower === 'trace')
+        return 'INFO';
+    return null;
+}
+/**
+ * Shared attribute base for both span and log mappings. `agora.trace_id` is
+ * whatever `@adonis-agora/context` resolved verbatim — a plain search/filter
+ * attribute, kept even when it is not valid W3C shape. This is deliberately
+ * SEPARATE from `SpanExportInput.traceId`/`LogExportInput.traceId` (strictly
+ * {@link isValidW3cTraceId}-checked), which is used for the actual OTel
+ * parent-context correlation and must never be malformed.
+ */
+function baseAttributes(entry, lib, event) {
+    const content = asDiagnosticLike(entry.content);
+    return {
+        'agora.lib': lib,
+        'agora.event': event,
+        'agora.entry_id': entry.id,
+        ...(entry.traceId ? { 'agora.trace_id': entry.traceId } : {}),
+        ...payloadAttributes(content?.payload),
+    };
+}
+/**
+ * Map one recorded {@link Entry} to a span or log export input, or `null` when it
+ * has no interpretable `{ lib, event }` shape (only `diagnostic`-shaped content —
+ * `lib`/`event` strings — is currently mapped; entries of other configured
+ * `entryTypes` degrade to `null`, i.e. skipped, until they get their own mapping).
+ */
+export function mapEntryToOtel(entry) {
+    const content = asDiagnosticLike(entry.content);
+    if (content === null || typeof content.lib !== 'string' || typeof content.event !== 'string') {
+        return null;
+    }
+    const { lib, event } = content;
+    const name = `agora.${lib}.${event}`;
+    const traceId = isValidW3cTraceId(entry.traceId) ? entry.traceId : null;
+    const errored = looksLikeError(entry);
+    const durationMs = resolveDurationMs(entry);
+    const ts = typeof content.ts === 'number' ? content.ts : null;
+    if (durationMs !== null) {
+        const endTimeMs = ts ?? entry.createdAt.getTime();
+        const span = {
+            name,
+            startTimeMs: endTimeMs - durationMs,
+            endTimeMs,
+            attributes: baseAttributes(entry, lib, event),
+            status: errored ? 'ERROR' : 'OK',
+            ...(errored ? { errorMessage: errorMessageOf(content) ?? `${name} failed` } : {}),
+            traceId,
+        };
+        return { kind: 'span', span };
+    }
+    const severity = explicitSeverity(entry) ?? (errored ? 'ERROR' : 'INFO');
+    const log = {
+        body: name,
+        timestampMs: ts ?? entry.createdAt.getTime(),
+        severityNumber: SEVERITY_NUMBER[severity],
+        severityText: severity,
+        attributes: baseAttributes(entry, lib, event),
+        traceId,
+    };
+    return { kind: 'log', log };
+}
+/** Best-effort extraction of a human-readable error message from a diagnostic payload. */
+function errorMessageOf(content) {
+    const payload = content.payload;
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const error = payload.error;
+    if (error instanceof Error)
+        return error.message;
+    if (error !== undefined && error !== null && typeof error === 'object') {
+        const message = error.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    if (typeof error === 'string')
+        return error;
+    return undefined;
+}
+//# sourceMappingURL=mapper.js.map

package/dist/src/otel/mapper.js.map

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

package/dist/src/otel/otel_exporter.d.ts

@@ -0,0 +1,17 @@
+import type { ResolvedOtelConfig } from '../define_config.js';
+import type { LogExportInput, SpanExportInput } from './mapper.js';
+/** What `telescope_otel_exporting_store.ts` calls per mapped entry. */
+export interface OtelExporter {
+    exportSpan(input: SpanExportInput): void;
+    exportLog(input: LogExportInput): void;
+    /** Flush + shut down both providers. Called at telescope provider shutdown. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Build the OTel exporter from resolved config. Each call constructs its own
+ * private `BasicTracerProvider` + `LoggerProvider` (with a `BatchSpanProcessor` /
+ * `BatchLogRecordProcessor` batching to the configured OTLP/HTTP endpoint) — cheap
+ * enough to build once at provider boot and reuse for the process lifetime.
+ */
+export declare function createOtelExporter(config: ResolvedOtelConfig): OtelExporter;
+//# sourceMappingURL=otel_exporter.d.ts.map

package/dist/src/otel/otel_exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel_exporter.d.ts","sourceRoot":"","sources":["../../../src/otel/otel_exporter.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA0BnE,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAaD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAmE3E"}

package/dist/src/otel/otel_exporter.js

@@ -0,0 +1,107 @@
+import { context as otelContext, trace as otelTrace, SpanKind, SpanStatusCode, TraceFlags, } from '@opentelemetry/api';
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
+import { BasicTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+/**
+ * THE ONLY FILE in this package that imports `@opentelemetry/*` at the module
+ * top level. It is loaded exclusively via a dynamic `import()` from
+ * `telescope_provider.ts`'s `applyOtel`, and ONLY when `config.otel.enabled` is
+ * `true` — so a host who never turns this on never pays for (or needs to install)
+ * any OTel package. Mirrors the exact convention `stores/factory.ts` uses for the
+ * `lucid` driver's peer dependency.
+ *
+ * Deliberately minimal: `BasicTracerProvider`/`LoggerProvider` from `sdk-trace-base`
+ * / `sdk-logs` plus their OTLP/HTTP exporters — no auto-instrumentation SDK, no
+ * Node context-manager registration, no global provider registration
+ * (`trace.setGlobalTracerProvider` is never called). This bridge owns a PRIVATE
+ * tracer/logger pair and reads span context explicitly per call — it never
+ * touches (or conflicts with) a host's own OTel setup (e.g. `@adonisjs/otel`),
+ * which may already have its own global provider wired for live request tracing.
+ */
+/** A non-existent parent span id used to synthesize a "remote parent" `SpanContext`
+ *  carrying only a known trace id (see the module doc on `mapper.ts` for why: telescope
+ *  only ever learns a trace ID, never a real parent span id, for an already-finished
+ *  diagnostics event). Any valid (non-all-zero) 16-hex value works — Tempo/Grafana group
+ *  by trace id, so this never needs to resolve to a real span. */
+const SYNTHETIC_PARENT_SPAN_ID = '0000000000000001';
+/** Build the `Context` carrying a synthesized remote-parent `SpanContext` for `traceId`. */
+function contextFor(traceId) {
+    if (traceId === null)
+        return undefined;
+    return otelTrace.setSpanContext(otelContext.active(), {
+        traceId,
+        spanId: SYNTHETIC_PARENT_SPAN_ID,
+        traceFlags: TraceFlags.SAMPLED,
+        isRemote: true,
+    });
+}
+/**
+ * Build the OTel exporter from resolved config. Each call constructs its own
+ * private `BasicTracerProvider` + `LoggerProvider` (with a `BatchSpanProcessor` /
+ * `BatchLogRecordProcessor` batching to the configured OTLP/HTTP endpoint) — cheap
+ * enough to build once at provider boot and reuse for the process lifetime.
+ */
+export function createOtelExporter(config) {
+    const resource = resourceFromAttributes({ 'service.name': config.serviceName });
+    const traceExporter = new OTLPTraceExporter({
+        url: `${config.endpoint}${config.tracesPath}`,
+        headers: config.headers,
+        timeoutMillis: config.timeoutMs,
+    });
+    const tracerProvider = new BasicTracerProvider({
+        resource,
+        spanProcessors: [new BatchSpanProcessor(traceExporter)],
+    });
+    const tracer = tracerProvider.getTracer('@adonis-agora/telescope');
+    const logExporter = new OTLPLogExporter({
+        url: `${config.endpoint}${config.logsPath}`,
+        headers: config.headers,
+        timeoutMillis: config.timeoutMs,
+    });
+    const loggerProvider = new LoggerProvider({
+        resource,
+        processors: [new BatchLogRecordProcessor({ exporter: logExporter })],
+    });
+    const logger = loggerProvider.getLogger('@adonis-agora/telescope');
+    return {
+        exportSpan(input) {
+            const span = tracer.startSpan(input.name, {
+                startTime: input.startTimeMs,
+                kind: SpanKind.INTERNAL,
+                attributes: input.attributes,
+            }, contextFor(input.traceId) ?? otelContext.active());
+            if (input.status === 'ERROR') {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    ...(input.errorMessage !== undefined ? { message: input.errorMessage } : {}),
+                });
+                if (input.errorMessage !== undefined)
+                    span.recordException(input.errorMessage);
+            }
+            else {
+                span.setStatus({ code: SpanStatusCode.OK });
+            }
+            span.end(input.endTimeMs);
+        },
+        exportLog(input) {
+            // `input.severityNumber` is already the OTel `SeverityNumber` numeric value
+            // (mapper.ts documents the 9/13/17 literals it uses) — passed through
+            // verbatim so this file needn't import `@opentelemetry/api-logs` at all.
+            const ctx = contextFor(input.traceId);
+            logger.emit({
+                body: input.body,
+                timestamp: input.timestampMs,
+                severityNumber: input.severityNumber,
+                severityText: input.severityText,
+                attributes: input.attributes,
+                ...(ctx !== undefined ? { context: ctx } : {}),
+            });
+        },
+        async shutdown() {
+            await Promise.allSettled([tracerProvider.shutdown(), loggerProvider.shutdown()]);
+        },
+    };
+}
+//# sourceMappingURL=otel_exporter.js.map

package/dist/src/otel/otel_exporter.js.map

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

package/dist/src/otel/otel_exporting_store.d.ts

@@ -0,0 +1,49 @@
+import type { Entry, RecordInput } from '../entry.js';
+import type { EntryQuery, TelescopeStore } from '../store.js';
+import type { OtelExporter } from './otel_exporter.js';
+/**
+ * A {@link TelescopeStore} decorator that exports each PERSISTED entry (of a
+ * configured `entryTypes`) to an OTel Collector via {@link OtelExporter}, as
+ * either a span (has a duration) or a log record (point-in-time) — see
+ * `mapper.ts` for the exact mapping.
+ *
+ * Placed in the provider's chain the SAME way {@link
+ * import('../stream/streaming_store.js').StreamingTelescopeStore} is: AFTER
+ * redaction and sampling, so it only ever sees the final, already-scrubbed entry
+ * that actually got stored:
+ *
+ * - **Redaction**: `record()` delegates to `inner.record()` FIRST and exports
+ *   from the RETURNED entry, never the raw input — so whatever the redacting
+ *   decorator masked is what leaves the process as OTel attributes/log bodies,
+ *   never the pre-redaction content. This is deliberate ordering, not an
+ *   accident: exporting to an external Collector is a strictly bigger
+ *   exfiltration surface than the local Telescope store, so it must never see
+ *   anything the local store itself wasn't already allowed to keep.
+ * - **Sampling**: a sampled-away entry comes back with `sequence: -1` (the
+ *   sampling decorator's synthetic placeholder, never persisted) — skipped here
+ *   exactly like `StreamingTelescopeStore` skips it, so a dropped-from-storage
+ *   entry costs no OTel export either (same tail-sampling decision, no separate
+ *   OTel-side sampling knob; see the `otel` docs page for why this was the
+ *   chosen default over an independent rate).
+ * - **Overload guard**: checked EXPLICITLY here (`getTelescopeRuntime().paused`)
+ *   before doing any export work. This is IN ADDITION to whatever the ingestion
+ *   entry point itself does — it guarantees that even if a producer's `paused`
+ *   check has already let an entry through, no NEW export work (an OTLP HTTP
+ *   call) starts while the guard has shed load. The entry is still recorded/
+ *   returned normally either way; only the export side-effect is skipped.
+ */
+export declare class OtelExportingTelescopeStore implements TelescopeStore {
+    private readonly inner;
+    private readonly exporter;
+    private readonly entryTypes;
+    constructor(inner: TelescopeStore, exporter: OtelExporter, entryTypes: readonly string[]);
+    record<TContent>(input: RecordInput<TContent>): Promise<Entry<TContent>>;
+    /** Map + export one entry, swallowing every failure — observability must never break recording. */
+    private export;
+    get(id: string): Promise<Entry | null>;
+    list(query?: EntryQuery): Promise<Entry[]>;
+    count(): Promise<number>;
+    prune(olderThan: Date, keepLast?: number): Promise<number>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=otel_exporting_store.d.ts.map

package/dist/src/otel/otel_exporting_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel_exporting_store.d.ts","sourceRoot":"","sources":["../../../src/otel/otel_exporting_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,2BAA4B,YAAW,cAAc;IAI9D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IAEjD,YACmB,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,YAAY,EACvC,UAAU,EAAE,SAAS,MAAM,EAAE,EAG9B;IAEK,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAM7E;IAED,mGAAmG;IACnG,OAAO,CAAC,MAAM;IAcd,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAED,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAEzC;IAED,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAEvB;IAED,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzD;IAED,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;CACF"}

package/dist/src/otel/otel_exporting_store.js

@@ -0,0 +1,83 @@
+import { getTelescopeRuntime } from '../registry.js';
+import { mapEntryToOtel } from './mapper.js';
+/**
+ * A {@link TelescopeStore} decorator that exports each PERSISTED entry (of a
+ * configured `entryTypes`) to an OTel Collector via {@link OtelExporter}, as
+ * either a span (has a duration) or a log record (point-in-time) — see
+ * `mapper.ts` for the exact mapping.
+ *
+ * Placed in the provider's chain the SAME way {@link
+ * import('../stream/streaming_store.js').StreamingTelescopeStore} is: AFTER
+ * redaction and sampling, so it only ever sees the final, already-scrubbed entry
+ * that actually got stored:
+ *
+ * - **Redaction**: `record()` delegates to `inner.record()` FIRST and exports
+ *   from the RETURNED entry, never the raw input — so whatever the redacting
+ *   decorator masked is what leaves the process as OTel attributes/log bodies,
+ *   never the pre-redaction content. This is deliberate ordering, not an
+ *   accident: exporting to an external Collector is a strictly bigger
+ *   exfiltration surface than the local Telescope store, so it must never see
+ *   anything the local store itself wasn't already allowed to keep.
+ * - **Sampling**: a sampled-away entry comes back with `sequence: -1` (the
+ *   sampling decorator's synthetic placeholder, never persisted) — skipped here
+ *   exactly like `StreamingTelescopeStore` skips it, so a dropped-from-storage
+ *   entry costs no OTel export either (same tail-sampling decision, no separate
+ *   OTel-side sampling knob; see the `otel` docs page for why this was the
+ *   chosen default over an independent rate).
+ * - **Overload guard**: checked EXPLICITLY here (`getTelescopeRuntime().paused`)
+ *   before doing any export work. This is IN ADDITION to whatever the ingestion
+ *   entry point itself does — it guarantees that even if a producer's `paused`
+ *   check has already let an entry through, no NEW export work (an OTLP HTTP
+ *   call) starts while the guard has shed load. The entry is still recorded/
+ *   returned normally either way; only the export side-effect is skipped.
+ */
+export class OtelExportingTelescopeStore {
+    inner;
+    exporter;
+    entryTypes;
+    constructor(inner, exporter, entryTypes) {
+        this.inner = inner;
+        this.exporter = exporter;
+        this.entryTypes = new Set(entryTypes);
+    }
+    async record(input) {
+        const entry = await this.inner.record(input);
+        if (entry.sequence >= 0 && this.entryTypes.has(entry.type) && !getTelescopeRuntime().paused) {
+            this.export(entry);
+        }
+        return entry;
+    }
+    /** Map + export one entry, swallowing every failure — observability must never break recording. */
+    export(entry) {
+        try {
+            const mapped = mapEntryToOtel(entry);
+            if (mapped === null)
+                return;
+            if (mapped.kind === 'span') {
+                this.exporter.exportSpan(mapped.span);
+            }
+            else {
+                this.exporter.exportLog(mapped.log);
+            }
+        }
+        catch (err) {
+            console.error('@adonis-agora/telescope: OTel export failed for one entry:', err);
+        }
+    }
+    get(id) {
+        return this.inner.get(id);
+    }
+    list(query) {
+        return this.inner.list(query);
+    }
+    count() {
+        return this.inner.count();
+    }
+    prune(olderThan, keepLast) {
+        return this.inner.prune(olderThan, keepLast);
+    }
+    clear() {
+        return this.inner.clear();
+    }
+}
+//# sourceMappingURL=otel_exporting_store.js.map

package/dist/src/otel/otel_exporting_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel_exporting_store.js","sourceRoot":"","sources":["../../../src/otel/otel_exporting_store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,2BAA2B;IAInB,KAAK;IACL,QAAQ;IAJV,UAAU,CAAsB;IAEjD,YACmB,KAAqB,EACrB,QAAsB,EACvC,UAA6B;qBAFZ,KAAK;wBACL,QAAQ;QAGzB,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,MAAM,CAAW,KAA4B;QACjD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,MAAM,EAAE,CAAC;YAC5F,IAAI,CAAC,MAAM,CAAC,KAAc,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mGAAmG;IAC3F,MAAM,CAAC,KAAY;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YACrC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO;YAC5B,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC3B,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACxC,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,4DAA4D,EAAE,GAAG,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,CAAC,KAAkB;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,SAAe,EAAE,QAAiB;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF"}

package/dist/src/profiling/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.20.0";
 export { aggregateCpuProfile } from './aggregate-profile.js';
 export type { CpuProfilerOptions, CpuProfilerResult, InspectorSessionLike, SessionFactory, } from './cpu-profiler.js';
 export { CpuProfiler, defaultSessionFactory } from './cpu-profiler.js';

package/dist/src/profiling/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.18.0';
+export const VERSION = '0.20.0';
 export { aggregateCpuProfile } from './aggregate-profile.js';
 export { CpuProfiler, defaultSessionFactory } from './cpu-profiler.js';
 export { defineConfig, resolveConfig } from './define_config.js';