@mks2508/better-logger 0.18.2-alpha.2 → 0.18.4

package/dist/transports/OtlpTraceTransport.d.ts

@@ -0,0 +1,118 @@
+import type { SpanRecord, TransportRecord } from '../types/index.js';
+import { HttpTransport } from './HttpTransport.js';
+import { type OtlpAttributeValue, type OtlpTransportOptions } from './OtlpTransport.js';
+/**
+ * Opciones de configuración para {@link OtlpTraceTransport}. Hereda todas las
+ * opciones de {@link OtlpTransportOptions} (endpoint, serviceName,
+ * ingestKeyEnvVar, batching, retry, ...) porque el transport de traces espeja
+ * al de logs.
+ */
+export interface OtlpTraceTransportOptions extends OtlpTransportOptions {
+    /**
+     * Versión del scope que emite los spans (`scopeSpans[].scope.version`).
+     * Opcional: si se omite, el bloque `scope` se emite sin `version` en vez
+     * de inventar una.
+     */
+    scopeVersion?: string;
+}
+/**
+ * Shape del body JSON de un request OTLP/HTTP para traces. Coincide con el
+ * JSON mapping del proto `TracesData` para `/v1/traces`. Ver
+ * https://opentelemetry.io/docs/specs/otlp/#json-protobuf-encoding
+ */
+interface OtlpTracesPayload {
+    resourceSpans: Array<{
+        resource: {
+            attributes: Array<{
+                key: string;
+                value: {
+                    stringValue: string;
+                };
+            }>;
+        };
+        scopeSpans: Array<{
+            scope: {
+                name: string;
+                version?: string;
+            };
+            spans: Array<OtlpSpan>;
+        }>;
+    }>;
+}
+/**
+ * Span individual dentro del payload OTLP. Mappea 1:1 los campos del
+ * `SpanRecord` al proto `Span` de la spec OTel Trace.
+ * @see https://opentelemetry.io/docs/specs/otel/trace/api/#span
+ */
+interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: Array<{
+        key: string;
+        value: OtlpAttributeValue;
+    }>;
+    status?: {
+        code: number;
+        message?: string;
+    };
+}
+/**
+ * Transport OTLP/HTTP para traces (spans) — POST a `<endpoint>/v1/traces`.
+ *
+ * Espeja {@link OtlpTransport} (que va a `/v1/logs`): hereda de
+ * {@link HttpTransport} el batch, retry con backoff, buffer acotado, close
+ * asincrónico y el hook on-error. Solo cambia la shape del payload y acepta
+ * exclusivamente records de kind `'span'` (`accepts = ['span']`): el
+ * {@link TransportManager} garantiza que jamás recibe un log record.
+ *
+ * @example
+ * ```ts
+ * logger.addTransport({
+ *   target: new OtlpTraceTransport({
+ *     endpoint: 'https://otelcollector.example.com:4318',
+ *     serviceName: 'my-app',
+ *     scopeVersion: '1.2.3'
+ *   })
+ * });
+ *
+ * await logger.span('db.query', { table: 'users' }, async () => {
+ *   await db.select();
+ * });
+ * ```
+ */
+export declare class OtlpTraceTransport extends HttpTransport {
+    readonly name = "otlp-trace";
+    /** Este transport SOLO acepta spans — jamás recibe log records. */
+    readonly accepts: readonly ["span"];
+    private readonly resource;
+    private readonly scopeVersion;
+    /** Resuelto al construir. Nunca se loguea, nunca se escribe a source. */
+    private readonly ingestKeyValue;
+    constructor(options: OtlpTraceTransportOptions);
+    /**
+     * Construye el payload JSON OTLP/HTTP a partir de los spans bufferizados.
+     * Un bloque `resourceSpans` por batch. Expuesto para tests y subclasses.
+     *
+     * @param spans - Spans a serializar dentro del payload.
+     * @returns Objeto `TracesData` listo para `JSON.stringify`.
+     */
+    buildPayload(spans: SpanRecord[]): OtlpTracesPayload;
+    /**
+     * Serializa un batch al body JSON del request OTLP/HTTP. Override de
+     * {@link HttpTransport.serializeBody}.
+     */
+    protected serializeBody(records: TransportRecord[]): string;
+    /**
+     * Construye los headers del request. Agrega `signoz-ingestion-key` con el
+     * valor resuelto al construir.
+     */
+    protected buildHeaders(): Record<string, string>;
+    private toOtlpSpan;
+}
+export {};
+//# sourceMappingURL=OtlpTraceTransport.d.ts.map

package/dist/transports/OtlpTraceTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtlpTraceTransport.d.ts","sourceRoot":"","sources":["../../src/transports/OtlpTraceTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAgB,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAIH,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAC5B,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,yBAA0B,SAAQ,oBAAoB;IACnE;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,UAAU,iBAAiB;IACvB,aAAa,EAAE,KAAK,CAAC;QACjB,QAAQ,EAAE;YACN,UAAU,EAAE,KAAK,CAAC;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE;oBAAE,WAAW,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAC,CAAC;SACtE,CAAC;QACF,UAAU,EAAE,KAAK,CAAC;YACd,KAAK,EAAE;gBACH,IAAI,EAAE,MAAM,CAAC;gBACb,OAAO,CAAC,EAAE,MAAM,CAAC;aACpB,CAAC;YACF,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;SAC1B,CAAC,CAAC;KACN,CAAC,CAAC;CACN;AAED;;;;GAIG;AACH,UAAU,QAAQ;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAAC;IAC/D,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;IACjD,SAAkB,IAAI,gBAAgB;IAEtC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,oBAAqB;IAErC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,OAAO,EAAE,yBAAyB;IAsC9C;;;;;;OAMG;IACH,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,iBAAiB;IAuBpD;;;OAGG;cACgB,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM;IAMpE;;;OAGG;cACgB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQzD,OAAO,CAAC,UAAU;CA+BrB"}

package/dist/transports/OtlpTransport.d.ts

@@ -95,7 +95,7 @@ interface OtlpLogRecord {
  * mixtos).
  * @see https://opentelemetry.io/docs/specs/otel/common/
  */
-type OtlpAttributeValue = {
+export type OtlpAttributeValue = {
     stringValue: string;
 } | {
     intValue: number;
@@ -161,5 +161,31 @@ export declare class OtlpTransport extends HttpTransport {
     protected buildHeaders(): Record<string, string>;
     private toLogRecord;
 }
+/**
+ * Quita la barra final de un endpoint si la lleva.
+ *
+ * @internal Compartido con {@link OtlpTraceTransport}; no es API pública.
+ */
+export declare function stripTrailingSlash(value: string): string;
+/**
+ * Lee la ingest API key desde `process.env[name]`. Devuelve `undefined`
+ * silenciosamente si `process` no está disponible (bundles estrictos de
+ * browser) o si la variable no está seteada. Nunca throwea, nunca loguea
+ * el valor.
+ *
+ * @internal Helper del constructor de {@link OtlpTransport} y
+ *   {@link OtlpTraceTransport}; no es API pública.
+ * @param envVarName - Nombre de la env var a leer.
+ * @returns Valor de la key, o `undefined` si no está disponible.
+ */
+export declare function readIngestKey(envVarName: string | undefined): string | undefined;
+/**
+ * Convierte un valor JS a un `AnyValue` de OTel. Compartido con
+ * {@link OtlpTraceTransport} para serializar attributes de span con el mismo
+ * mapping.
+ *
+ * @internal Exportado para reuse entre transports OTLP; no es API pública.
+ */
+export declare function toOtlpAttribute(value: unknown): OtlpAttributeValue | null;
 export {};
 //# sourceMappingURL=OtlpTransport.d.ts.map

package/dist/transports/OtlpTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OtlpTransport.d.ts","sourceRoot":"","sources":["../../src/transports/OtlpTransport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"OtlpTransport.d.ts","sourceRoot":"","sources":["../../src/transports/OtlpTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,YAAY,EAGf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,UAAU,eAAe;IACrB,YAAY,EAAE,KAAK,CAAC;QAChB,QAAQ,EAAE;YACN,UAAU,EAAE,KAAK,CAAC;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE;oBAAE,WAAW,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAC,CAAC;SACtE,CAAC;QACF,SAAS,EAAE,KAAK,CAAC;YACb,KAAK,EAAE;gBACH,IAAI,EAAE,MAAM,CAAC;gBACb,OAAO,EAAE,MAAM,CAAC;aACnB,CAAC;YACF,UAAU,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;SACpC,CAAC,CAAC;KACN,CAAC,CAAC;CACN;AAED;;;;;GAKG;AACH,UAAU,aAAa;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAAC;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GACxB;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GACvB;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpB;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GACvB;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GACtB;IAAE,UAAU,EAAE;QAAE,MAAM,EAAE,kBAAkB,EAAE,CAAA;KAAE,CAAA;CAAE,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC5C,SAAkB,IAAI,UAAU;IAEhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,OAAO,EAAE,oBAAoB;IAqCzC;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,eAAe;IAuBzD;;;;;;OAMG;cACgB,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM;IAIpE;;;;;OAKG;cACgB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQzD,OAAO,CAAC,WAAW;CAuBtB;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOhF;AA6BD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAkBzE"}

package/dist/transports/SpanRuntime.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview SpanRuntime — runtime de spans del trio API
+ * `event` / `span` / `startSpan`.
+ *
+ * Vive en transports/ porque es la extensión del pipeline de dispatch: los
+ * {@link SpanRecord} que produce viajan por el {@link TransportManager} junto
+ * a los log records, enrutados por kind (`accepts`).
+ *
+ * Tres responsabilidades:
+ *   - **ALS singleton del módulo**: un único `AsyncLocalStorage<SpanRecord>`
+ *     compartido por TODAS las instancias de Logger — "qué instancia lleva el
+ *     span" es ambiguo con MDC por-instancia, el span activo es una propiedad
+ *     del call stack, no del logger.
+ *   - **Generación de ids** conforme a W3C Trace Context (traceId 16 bytes →
+ *     32 hex, spanId 8 bytes → 16 hex) vía `crypto.getRandomValues`.
+ *   - **Leak-safety**: registry de spans abiertos; en flush/shutdown se
+ *     fuerzan a `end()` con `incomplete: true` y se exportan — nunca se tiran.
+ */
+import type { Span, SpanAttributes, SpanRecord } from '../types/index.js';
+/**
+ * Span activo en el call stack corriente (dentro de `span(fn)`), si lo hay.
+ * Lo consumen la correlación log→span (`TransportRecord.traceId/spanId`) y la
+ * resolución de `parentSpanId` en spans hijos.
+ *
+ * Sin `run()` previo el store estaría vacío igual, así que el guard por
+ * flag es observable-identico a consultar el ALS real.
+ */
+export declare function getActiveSpan(): SpanRecord | undefined;
+/**
+ * Ejecuta `fn` con `record` como span activo. Sin ALS disponible (browser),
+ * ejecuta `fn` directamente — sin correlación pero funcional.
+ */
+export declare function runWithActiveSpan<R>(record: SpanRecord, fn: () => R): R;
+/** Nanosegundos Unix actuales como string decimal (formato OTLP). */
+export declare function nowUnixNano(): string;
+/** Trace id W3C: 16 bytes → 32 chars hex. */
+export declare function generateTraceId(): string;
+/** Span id W3C: 8 bytes → 16 chars hex. */
+export declare function generateSpanId(): string;
+/**
+ * Crea el record de span y su {@link Span} handle. El handle registra el
+ * span en el registry de abiertos; `onEnd` se invoca una única vez, con el
+ * record final (duración real o `incomplete: true`), para su export al
+ * pipeline de transports.
+ *
+ * `end()` solo fija `endTimeUnixNano` si no se fijó antes — así los
+ * point-spans (`event()`) pueden fijar `end = start` exacto.
+ *
+ * @param name - Nombre de la operación.
+ * @param attributes - Attributes iniciales (copia propia del record).
+ * @param scope - Scope del logger emisor.
+ * @param onEnd - Callback de export; recibe el record cerrado.
+ * @returns El record (para el ALS store) y el handle del span.
+ */
+export declare function createSpan(name: string, attributes: SpanAttributes | undefined, scope: string, onEnd: (record: SpanRecord) => void): {
+    record: SpanRecord;
+    span: Span;
+};
+/**
+ * Emite un point-span (`event()`): start = end exactamente, sin registro en
+ * abiertos tras el cierre — no hay leak posible. El `parentSpanId` se resuelve
+ * contra el span activo si existe, pero NO fija contexto ALS.
+ */
+export declare function emitEventSpan(name: string, attributes: SpanAttributes | undefined, scope: string, onEnd: (record: SpanRecord) => void): void;
+/**
+ * Fuerza el cierre de todos los spans abiertos (`incomplete: true`) y los
+ * exporta vía el `onEnd` de cada uno. Lo invocan `flushTransports()` /
+ * `closeTransports()` / `cleanup()` ANTES del flush real — un span abierto
+ * nunca se tira en shutdown.
+ *
+ * @returns Los records forzados a cerrar (para diagnóstico/tests).
+ */
+export declare function forceCloseOpenSpans(): SpanRecord[];
+/** Número de spans actualmente abiertos (expuesto para tests/diagnóstico). */
+export declare function openSpanCount(): number;
+//# sourceMappingURL=SpanRuntime.d.ts.map

package/dist/transports/SpanRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpanRuntime.d.ts","sourceRoot":"","sources":["../../src/transports/SpanRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAiC1E;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,SAAS,CAGtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAGvE;AAED,qEAAqE;AACrE,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAyBD,6CAA6C;AAC7C,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,2CAA2C;AAC3C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CACtB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,cAAc,GAAG,SAAS,EACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GACpC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAkEpC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,cAAc,GAAG,SAAS,EACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GACpC,IAAI,CAIN;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,EAAE,CAOlD;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/transports/TransportManager.d.ts

@@ -1,4 +1,4 @@
-import type { TransportRecord, TransportTarget, TransportOptions, ITransport, ITransportManager, LogLevel } from '../types/index.js';
+import type { TransportTarget, TransportOptions, ITransport, ITransportManager, LogLevel, TransportDispatchRecord } from '../types/index.js';
 /**
  * Firma del constructor de los transports registrados en el registry
  * built-in. Acepta el tipo propio de options del transport; el pass-through
@@ -157,16 +157,22 @@ export declare class TransportManager implements ITransportManager {
      */
     remove(id: string): boolean;
     /**
-     * Dispatcha un {@link TransportRecord} a todos los transports activos
-     * que pasen el filtro de nivel.
+     * Dispatcha un {@link TransportRecord} o {@link SpanRecord} a todos los
+     * transports activos que acepten su kind.
      *
      * Por cada transport, en orden:
-     *   1. **Filtro de nivel**: si `record.levelValue < entry.levelValue`,
-     *      se skipa (ese transport no recibe este record).
-     *   2. **Transform**: si `entry.options.transform` está seteado, se
-     *      aplica al record. Si devuelve `null`, el record se droppea para
-     *      este transport (no para los demás).
-     *   3. **Write**: se llama a `transport.write(transformedRecord)`. Si
+     *   1. **Routing por kind**: el kind del record (`'log'` o `'span'`)
+     *      debe estar en el `accepts` del transport (default `['log']` cuando
+     *      no lo declara). Un `SpanRecord` JAMÁS llega a un transport
+     *      log-only, y viceversa — esto evita que un `OtlpTransport` serialice
+     *      spans como `logRecords` hacia `/v1/logs`.
+     *   2. **Filtro de nivel** (solo logs): si `record.levelValue <
+     *      entry.levelValue`, se skipa. Los spans no tienen nivel.
+     *   3. **Transform** (solo logs): si `entry.options.transform` está
+     *      seteado, se aplica al record. Si devuelve `null`, el record se
+     *      droppea para este transport. Los spans NO pasan por transform —
+     *      su contrato asume shape de log (muta `record.message`).
+     *   4. **Write**: se llama a `transport.write(record)`. Si
      *      devuelve una Promise, se añade al batch await. Toda excepción
      *      sincrónica o rechazo de Promise se captura y se loguea por
      *      consola — el log call original del caller nunca rompe por un
@@ -176,7 +182,7 @@ export declare class TransportManager implements ITransportManager {
      * resuelto (o fallado) su write. Para fire-and-forget desde el Logger,
      * el caller puede ignorar la Promise.
      *
-     * @param {TransportRecord} record - Record a dispatchar.
+     * @param {TransportDispatchRecord} record - Record (log o span) a dispatchar.
      * @returns {Promise<void>} Resuelve cuando todos los writes terminaron
      *   (exitosos o fallidos). Nunca rechaza.
      *
@@ -187,8 +193,9 @@ export declare class TransportManager implements ITransportManager {
      * });
      *
      * @see {@link TransportRecord}
+     * @see {@link SpanRecord}
      */
-    write(record: TransportRecord): Promise<void>;
+    write(record: TransportDispatchRecord): Promise<void>;
     /**
      * Flushea todos los transports que expongan `flush()` (buffered transports
      * como {@link HttpTransport}, {@link FileTransport}, {@link OtlpTransport}).

package/dist/transports/TransportManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransportManager.d.ts","sourceRoot":"","sources":["../../src/transports/TransportManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACX,MAAM,mBAAmB,CAAC;AAmB3B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,OAAO,CAAC,EAAE,gBAAgB,KAAK,UAAU,CAAC;AAuClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACtD,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgE;IAEzF;;;;;;;;;;OAUG;gBACS,YAAY,CAAC,EAAE,QAAQ;IAMnC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAOxD;;;;;;;;;;OAUG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IA+BpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAc3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCnD;;;;;;;;;;;;;;OAcG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B5B;;;;;;;OAOG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,MAAM,EAAE;CAGnB"}
+{"version":3,"file":"TransportManager.d.ts","sourceRoot":"","sources":["../../src/transports/TransportManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAER,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EAER,uBAAuB,EAC1B,MAAM,mBAAmB,CAAC;AAoB3B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,OAAO,CAAC,EAAE,gBAAgB,KAAK,UAAU,CAAC;AAiDlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACtD,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgE;IAEzF;;;;;;;;;;OAUG;gBACS,YAAY,CAAC,EAAE,QAAQ;IAMnC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAOxD;;;;;;;;;;OAUG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IA+BpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAc3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,KAAK,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8C3D;;;;;;;;;;;;;;OAcG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B5B;;;;;;;OAOG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,MAAM,EAAE;CAGnB"}

package/dist/transports/index.d.ts

@@ -3,4 +3,5 @@ export { ConsoleTransport } from './ConsoleTransport.js';
 export { FileTransport, type FileTransportOptions } from './FileTransport.js';
 export { HttpTransport, type HttpTransportOptions } from './HttpTransport.js';
 export { OtlpTransport, type OtlpTransportOptions } from './OtlpTransport.js';
+export { OtlpTraceTransport, type OtlpTraceTransportOptions } from './OtlpTraceTransport.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/transports/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/transports-module.d.ts

@@ -1,10 +1,12 @@
 /**
  * @fileoverview Entry point for ./transports subpath.
- * Transport classes: FileTransport, HttpTransport, OtlpTransport, ConsoleTransport.
+ * Transport classes: FileTransport, HttpTransport, OtlpTransport,
+ * OtlpTraceTransport, ConsoleTransport.
  */
 export { TransportManager } from './transports/index.js';
 export { ConsoleTransport } from './transports/index.js';
 export { FileTransport, type FileTransportOptions } from './transports/index.js';
 export { HttpTransport, type HttpTransportOptions } from './transports/index.js';
 export { OtlpTransport, type OtlpTransportOptions } from './transports/index.js';
+export { OtlpTraceTransport, type OtlpTraceTransportOptions } from './transports/index.js';
 //# sourceMappingURL=transports-module.d.ts.map

package/dist/transports-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports-module.d.ts","sourceRoot":"","sources":["../src/transports-module.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"transports-module.d.ts","sourceRoot":"","sources":["../src/transports-module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/transports.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_transports = require("./chunks/transports-yK6CL0Ml.cjs");
+const require_transports = require("./chunks/transports-BZ-Mc2IT.cjs");
 exports.ConsoleTransport = require_transports.ConsoleTransport;
 exports.FileTransport = require_transports.FileTransport;
 exports.HttpTransport = require_transports.HttpTransport;
+exports.OtlpTraceTransport = require_transports.OtlpTraceTransport;
 exports.OtlpTransport = require_transports.OtlpTransport;
 exports.TransportManager = require_transports.TransportManager;

package/dist/transports.js

@@ -1,2 +1,2 @@
-import { a as ConsoleTransport, i as FileTransport, n as OtlpTransport, r as HttpTransport, t as TransportManager } from "./chunks/transports-BGfwwakw.js";
-export { ConsoleTransport, FileTransport, HttpTransport, OtlpTransport, TransportManager };
+import { a as FileTransport, i as HttpTransport, n as OtlpTraceTransport, o as ConsoleTransport, r as OtlpTransport, t as TransportManager } from "./chunks/transports-DvaLAeGJ.js";
+export { ConsoleTransport, FileTransport, HttpTransport, OtlpTraceTransport, OtlpTransport, TransportManager };

package/dist/types/index.d.ts

@@ -6,6 +6,6 @@ export { LOG_LEVELS, SUCCESS_LEVEL } from './core.js';
 export type { LogMetadata, ILogHandler, } from './handlers.js';
 export type { SerializerFn, SerializerContext, SerializerEntry, SerializerConfig, ISerializerRegistry, } from './serializers.js';
 export type { HookLogEntry, HookEvent, HookCallback, MiddlewareFn, HookRegistration, MiddlewareRegistration, IHookManager, } from './hooks.js';
-export type { TransportRecord, TransportOptions, TransportTarget, ITransport, IBufferedTransport, ITransportManager, ILogResource, ILogAttributes, LogAttributeValue, } from './transports.js';
+export type { TransportRecord, TransportOptions, TransportTarget, ITransport, IBufferedTransport, ITransportManager, ILogResource, ILogAttributes, LogAttributeValue, TransportRecordKind, TransportDispatchRecord, SpanRecord, Span, SpanAttributes, SpanAttributeValue, SpanStatus, } from './transports.js';
 export { LOG_LEVEL_TO_SEVERITY_NUMBER, LOG_LEVEL_TO_SEVERITY_TEXT, } from './transports.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,eAAe,EACf,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGtD,YAAY,EACR,WAAW,EACX,WAAW,GACd,MAAM,eAAe,CAAC;AAGvB,YAAY,EACR,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACR,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,GACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EACR,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACH,4BAA4B,EAC5B,0BAA0B,GAC7B,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACR,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,aAAa,EACb,SAAS,EACT,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,eAAe,EACf,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGtD,YAAY,EACR,WAAW,EACX,WAAW,GACd,MAAM,eAAe,CAAC;AAGvB,YAAY,EACR,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACR,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,GACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EACR,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,EACV,IAAI,EACJ,cAAc,EACd,kBAAkB,EAClB,UAAU,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACH,4BAA4B,EAC5B,0BAA0B,GAC7B,MAAM,iBAAiB,CAAC"}

package/dist/types/transports.d.ts

@@ -75,6 +75,108 @@ export interface TransportRecord {
     /** Tag especial "success" — lo setea `Logger.success()`. */
     tag?: LogTag;
 }
+/**
+ * Kind de record que circula por el pipeline de transports. Los transports
+ * declaran cuáles aceptan vía {@link ITransport.accepts}; el
+ * {@link ITransportManager} enruta cada record solo a los transports cuyo
+ * `accepts` lo incluye.
+ */
+export type TransportRecordKind = 'log' | 'span';
+/**
+ * Valor admitido en los attributes de un {@link SpanRecord}. Deliberadamente
+ * más estrecho que {@link LogAttributeValue}: el JSON mapping de OTLP traces
+ * solo acepta primitivos en `span.attributes` sin schema extra.
+ */
+export type SpanAttributeValue = string | number | boolean;
+/**
+ * Bag de attributes de un span (compatible con el modelo de attributes de
+ * OpenTelemetry para traces).
+ */
+export interface SpanAttributes {
+    [key: string]: SpanAttributeValue;
+}
+/**
+ * Status de finalización de un span, conforme al proto OTel `Status`.
+ * `code: 2` = `STATUS_CODE_ERROR`.
+ *
+ * @see https://opentelemetry.io/docs/specs/otel/trace/api/#set-status
+ */
+export interface SpanStatus {
+    code: number;
+    message?: string;
+}
+/**
+ * Record de span (trace) que emite el trio API `event`/`span`/`startSpan`.
+ * A diferencia de {@link TransportRecord}, NO atraviesa el hook path de logs:
+ * el {@link ITransportManager} lo despacha solo a transports cuyo
+ * {@link ITransport.accepts} incluye `'span'`.
+ *
+ * `traceId` son 16 bytes en hex (32 chars) y `spanId` 8 bytes en hex
+ * (16 chars), conforme a la spec W3C Trace Context que exige OTLP/HTTP.
+ */
+export interface SpanRecord {
+    kind: 'span';
+    /** Trace id hex de 32 chars. Se hereda del span activo si existe. */
+    traceId: string;
+    /** Span id hex de 16 chars. */
+    spanId: string;
+    /** Span id del padre, tomado del span activo en el ALS al crearse. */
+    parentSpanId?: string;
+    /** Nombre de la operación (`db.query`, `http.request`, ...). */
+    name: string;
+    /** Span kind OTel numérico. 1 = SPAN_KIND_INTERNAL. */
+    spanKind: number;
+    /** Instante de inicio en nanosegundos (string decimal). */
+    startTimeUnixNano: string;
+    /** Instante de fin en nanosegundos (string decimal). `'0'` hasta end(). */
+    endTimeUnixNano: string;
+    /** Attributes del span. Mutables vía {@link Span.set} hasta el end(). */
+    attributes: SpanAttributes;
+    /** Status de finalización. Presente si el span terminó con `fail()`. */
+    status?: SpanStatus;
+    /** `true` cuando el span se cerró por flush sin `end()` explícito. */
+    incomplete?: boolean;
+    /** Scope del logger que emitió el span (nombre del scoped logger). */
+    scope: string;
+}
+/**
+ * Handle de un span externally-ended. Lo devuelven `startSpan()` y el
+ * callback de `span(fn)`.
+ */
+export interface Span {
+    /**
+     * Añade o actualiza un attribute del span.
+     *
+     * @param key - Nombre del attribute.
+     * @param value - Valor primitivo (string | number | boolean).
+     * @returns `this`, para encadenar.
+     */
+    set(key: string, value: SpanAttributeValue): this;
+    /**
+     * Finaliza el span: fija `endTimeUnixNano` y encola el
+     * {@link SpanRecord} para export. Llamadas posteriores son no-op.
+     *
+     * @param attributes - Attributes finales a mergear antes del export.
+     */
+    end(attributes?: SpanAttributes): void;
+    /**
+     * Marca el span como fallido (`status.code = 2` con el mensaje del
+     * error) y luego lo finaliza como {@link end}.
+     *
+     * @param err - Error (o valor) que causó el fallo.
+     */
+    fail(err: unknown): void;
+    /** Trace id hex de 32 chars del span. */
+    readonly traceId: string;
+    /** Span id hex de 16 chars del span. */
+    readonly spanId: string;
+}
+/**
+ * Unión de todo record que puede atravesar el {@link ITransportManager}:
+ * un log ({@link TransportRecord}) o un span ({@link SpanRecord}).
+ * El routing por kind lo hace el manager vía {@link ITransport.accepts}.
+ */
+export type TransportDispatchRecord = TransportRecord | SpanRecord;
 /**
  * Opciones aceptadas por cualquier transport al registrarse.
  */
@@ -102,10 +204,23 @@ export interface TransportTarget {
 }
 /**
  * Contrato mínimo que todo transport debe satisfacer.
+ *
+ * Un transport declara qué kinds de record acepta vía {@link accepts}:
+ * ausente o `['log']` → log-only (default, comportamiento de todos los
+ * transports históricos); `['span']` → solo spans (p.ej. `OtlpTraceTransport`);
+ * `['log', 'span']` → ambos. El {@link ITransportManager} garantiza que un
+ * transport jamás recibe un record de un kind que no declaró — un
+ * `SpanRecord` nunca llega a un transport de logs.
  */
 export interface ITransport {
     readonly name: string;
-    write(record: TransportRecord): void | Promise<void>;
+    /**
+     * Kinds de record que este transport acepta. **Default `['log']` cuando
+     * está ausente** — los transports existentes siguen siendo log-only sin
+     * cambios.
+     */
+    readonly accepts?: readonly TransportRecordKind[];
+    write(record: TransportDispatchRecord): void | Promise<void>;
     flush?(): void | Promise<void>;
     close?(): void | Promise<void>;
     isReady?(): boolean;
@@ -125,7 +240,11 @@ export interface IBufferedTransport extends ITransport {
 export interface ITransportManager {
     add(target: TransportTarget): string;
     remove(id: string): boolean;
-    write(record: TransportRecord): Promise<void>;
+    /**
+     * Dispatcha un record (log o span) a los transports que acepten su kind
+     * y (para logs) pasen el filtro de nivel del transport.
+     */
+    write(record: TransportDispatchRecord): Promise<void>;
     flush(): Promise<void>;
     close(): Promise<void>;
 }

package/dist/types/transports.d.ts.map

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

package/dist/utils/asyncLocalStorage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Resolución compartida de `AsyncLocalStorage` — utilidad
+ * interna, NO exportada por el barrel público (`src/utils/index.ts`).
+ *
+ * Único punto de verdad para resolver `node:async_hooks` por capas. Lo
+ * consumen tanto `transports/SpanRuntime.ts` (ALS singleton de spans) como
+ * `context/LogContext.ts` (ALS singleton de MDC). Antes había dos copias de
+ * este conocimiento: una acertaba (SpanRuntime, la que sigue este archivo) y
+ * otra usaba `typeof AsyncLocalStorage !== 'undefined'` — un feature-detect
+ * roto, porque en Node y Bun el constructor NO es global, así que esa rama
+ * quedaba siempre en `undefined` y el MDC de logs era no-op silencioso fuera
+ * del browser.
+ */
+/**
+ * Forma mínima de `AsyncLocalStorage<T>` que necesita este paquete.
+ */
+export interface AsyncLocalStorageLike<T> {
+    run<R>(store: T, fn: () => R): R;
+    getStore(): T | undefined;
+}
+/**
+ * Resuelve `AsyncLocalStorage` por capas:
+ *   1. global `AsyncLocalStorage` (runtimes/polyfills que lo exponen),
+ *   2. `process.getBuiltinModule('async_hooks')` (Node >= 22.3, Bun),
+ *   3. `require('node:async_hooks')` (CJS interop),
+ *   4. `undefined` → browser estricto: sin correlación (degradación
+ *      documentada; el caller decide qué hacer sin ALS).
+ *
+ * Nota: NO basta con `typeof AsyncLocalStorage !== 'undefined'` — en Node y
+ * Bun el constructor NO es global y hay que ir a `node:async_hooks`.
+ */
+export declare function resolveAsyncLocalStorage<T>(): AsyncLocalStorageLike<T> | undefined;
+//# sourceMappingURL=asyncLocalStorage.d.ts.map

package/dist/utils/asyncLocalStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncLocalStorage.d.ts","sourceRoot":"","sources":["../../src/utils/asyncLocalStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACpC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACjC,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,KAAK,qBAAqB,CAAC,CAAC,CAAC,GAAG,SAAS,CAiClF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mks2508/better-logger",
-  "version": "0.18.2-alpha.2",
+  "version": "0.18.4",
   "type": "module",
   "files": [
     "dist",