logquill 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,83 +1,113 @@
-/** Log levels, shared by name and numeric weight with the logquill-python contract. */
-declare enum Level {
-    TRACE = 5,
-    DEBUG = 10,
-    INFO = 20,
-    WARN = 30,
-    ERROR = 40,
-    FATAL = 50
-}
-/** A level given as a `Level`, a level name (any case), or its numeric weight. */
-type LevelInput = Level | number | string;
-/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
-declare function levelName(level: Level): string;
-/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
-declare function parseLevel(level: LevelInput): Level;
+import { P as Plugin, L as LogRecord, a as Level, T as Transport, b as LevelInput, F as Formatter } from './logger-D1_THnBJ.cjs';
+export { C as CollectingTransport, c as FunctionPlugin, J as JSONFormatter, d as Logger, e as LoggerOptions, M as MiddlewareFunc, S as SpanOptions, f as createRecord, l as levelName, p as parseLevel, u as utcTimestamp } from './logger-D1_THnBJ.cjs';
 
-/** The cross-language record shape shared with logquill-python. */
-interface LogRecord {
-    timestamp: string;
-    level: string;
-    logger: string;
-    message: string;
-    meta: Record<string, unknown>;
+/**
+ * Injects fixed key/value pairs into every record's `meta`.
+ * A value already present in a record's own `meta` wins over the fixed context.
+ */
+declare class ContextPlugin implements Plugin {
+    readonly context: Record<string, unknown>;
+    constructor(context: Record<string, unknown>);
+    beforeLog(record: LogRecord): LogRecord;
 }
-/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
-declare function utcTimestamp(): string;
-declare function createRecord(params: {
-    level: Level;
-    logger: string;
-    message: string;
-    meta: Record<string, unknown>;
-}): LogRecord;
 
-/** `format(record) -> string`, per the transport contract shared with logquill-python. */
-interface Formatter {
-    format(record: LogRecord): string;
+interface RunPluginOptions {
+    runId?: string;
 }
-/** Serializes a record to the canonical JSON line shape. */
-declare class JSONFormatter implements Formatter {
-    format(record: LogRecord): string;
+/**
+ * Stamps `meta.runId` — a stable id grouping every record from one agent
+ * run — plus an incrementing `meta.step` counter, one per record processed
+ * through this plugin instance.
+ *
+ * Distinct from `TraceContextPlugin`'s `traceId`: `runId` scopes one agent
+ * run, `traceId` follows one request across services. A run can span
+ * multiple traces (e.g. an agent that calls several downstream services);
+ * the two ids are independent.
+ *
+ * One instance is one run: attach a fresh `RunPlugin()` per run (typically
+ * via `logger.child("agent").use(new RunPlugin())`), never a process-wide
+ * singleton shared across runs — otherwise concurrent runs would share both
+ * the run id and the step counter.
+ *
+ * A record that already carries `meta.runId` (e.g. propagated from an
+ * upstream call) keeps its existing value; `meta.step` is always set from
+ * this instance's own counter.
+ */
+declare class RunPlugin implements Plugin {
+    readonly runId: string;
+    private step;
+    constructor(options?: RunPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
 }
 
 /**
- * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
- * `afterLog`, `onError`. All hooks are optional — implement only what you need.
- * A hook that throws cannot crash logging: the pipeline catches it, routes it
- * to `onError`, and moves on.
+ * Sets the inbound trace header for the current execution context (e.g.
+ * request-scoped HTTP middleware, before the handler runs) — the
+ * propagation mechanism framework middleware uses to hand `TraceContextPlugin`
+ * an inbound header without threading it through every log call. Backed by
+ * `AsyncLocalStorage`, so it's isolated per concurrent request. Returns a
+ * function that restores the previous value; call it (typically in a
+ * `finally` block) once the request is done.
  */
-interface Plugin {
-    /** Return a (possibly modified) record, or `null` to drop it. */
-    beforeLog?(record: LogRecord): LogRecord | null;
-    /** Called after the record has been dispatched to every transport. */
-    afterLog?(record: LogRecord): void;
-    /** Called when one of this plugin's own hooks throws. */
-    onError?(error: unknown, record: LogRecord): void;
-}
-/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
-type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+declare function setTraceparent(value: string | undefined): () => void;
+/** The header most recently set via `setTraceparent()` for this execution context. */
+declare function getTraceparent(): string | undefined;
+/** A fresh 32-hex-char id, matching the shape of an OTel/W3C trace id. */
+declare function generateTraceId(): string;
 /**
- * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
- * builds one of these automatically when given a function instead of a
- * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
- * read the `Plugin` interface first. There's no `next()` chaining: the
- * pipeline already calls hooks in sequence, so this is sugar for a
- * single-method `Plugin`, not a new execution model.
+ * Extracts a 32-hex-char trace id from a W3C `traceparent`, AWS X-Ray
+ * `X-Amzn-Trace-Id`, or GCP `X-Cloud-Trace-Context` header value. Returns
+ * `undefined` if `header` doesn't match any of the three shapes.
  */
-declare class FunctionPlugin implements Plugin {
-    private readonly func;
-    constructor(func: MiddlewareFunc);
-    beforeLog(record: LogRecord): LogRecord | null;
+declare function parseTraceHeader(header: string): string | undefined;
+/**
+ * Best-effort, synchronous lookup of the active OpenTelemetry span's trace
+ * id via a plain `require("@opentelemetry/api")` — `@opentelemetry/api` is
+ * never a declared dependency of this package (matching `logquill-python`'s
+ * lazy `import opentelemetry`); this returns `undefined` whenever it isn't
+ * installed, or no span is currently active, rather than throwing.
+ *
+ * A `require()` (via `createRequire`) rather than a dynamic `import()` is
+ * deliberate: `Plugin.beforeLog` is synchronous, so this has to be too.
+ */
+declare function defaultResolveActiveOtelTraceId(): string | undefined;
+interface TraceContextPluginOptions {
+    /** `meta` key the trace id is written to. Default `"traceId"`. */
+    traceKey?: string;
+    /** An inbound trace header to resolve on every record, bypassing `setTraceparent()`. */
+    traceparent?: string;
+    /** Override for testing, or to plug in a non-Node OTel API surface. Defaults to `defaultResolveActiveOtelTraceId`. */
+    resolveActiveOtelTraceId?: () => string | undefined;
 }
-
 /**
- * Injects fixed key/value pairs into every record's `meta`.
- * A value already present in a record's own `meta` wins over the fixed context.
+ * Stamps `meta.traceId` for cross-service correlation — distinct from
+ * `RunPlugin`'s `runId`: `traceId` follows one request across services,
+ * `runId` scopes one agent run.
+ *
+ * A record that already carries `meta[traceKey]` (e.g. because
+ * `SamplingPlugin`'s tail-based elevation, or an upstream plugin, already
+ * set one) is left alone. Otherwise resolves a trace id in priority order:
+ *
+ * 1. An active OpenTelemetry span's trace id, if `@opentelemetry/api` is
+ *    installed and a span is current — read directly, not just inbound
+ *    headers.
+ * 2. The `traceparent` constructor option, if given.
+ * 3. Whatever `setTraceparent()` most recently set for the current
+ *    execution context.
+ * 4. A freshly generated trace id, if none of the above produced one.
+ *
+ * Header parsing understands W3C `traceparent`, AWS X-Ray
+ * `X-Amzn-Trace-Id`, and GCP `X-Cloud-Trace-Context` — see
+ * `parseTraceHeader`. A header that doesn't parse is treated the same as no
+ * header: falls through to generating a new trace id.
  */
-declare class ContextPlugin implements Plugin {
-    readonly context: Record<string, unknown>;
-    constructor(context: Record<string, unknown>);
+declare class TraceContextPlugin implements Plugin {
+    readonly traceKey: string;
+    private readonly explicitTraceparent;
+    private readonly resolveActiveOtelTraceId;
+    constructor(options?: TraceContextPluginOptions);
     beforeLog(record: LogRecord): LogRecord;
+    private resolveTraceId;
 }
 
 declare const DEFAULT_REDACTED_KEYS: readonly string[];
@@ -133,27 +163,6 @@ declare class PIIRedactPlugin implements Plugin {
     private redactText;
 }
 
-/**
- * Sink for log records, per the cross-language transport contract:
- * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
- */
-declare abstract class Transport {
-    formatter: Formatter;
-    constructor(formatter?: Formatter);
-    format(record: LogRecord): string;
-    abstract write(formatted: string, record: LogRecord): void;
-    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
-    close(): void;
-}
-/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
-declare class CollectingTransport extends Transport {
-    readonly formatted: string[];
-    readonly records: LogRecord[];
-    closed: boolean;
-    write(formatted: string, record: LogRecord): void;
-    close(): void;
-}
-
 interface SamplingPluginOptions {
     rng?: () => number;
     /** `meta` key holding the trace/run id used to group buffered records. Default `"traceId"`. */
@@ -1233,42 +1242,6 @@ declare class HTTPTransport extends Transport {
     close(): void;
 }
 
-interface LoggerOptions {
-    level?: LevelInput;
-    transports?: Transport[];
-    plugins?: (Plugin | MiddlewareFunc)[];
-    meta?: Record<string, unknown>;
-}
-declare class Logger {
-    readonly name: string;
-    readonly transports: Transport[];
-    readonly plugins: Plugin[];
-    private currentLevel;
-    private readonly baseMeta;
-    constructor(name: string, options?: LoggerOptions);
-    get level(): Level;
-    setLevel(level: LevelInput): void;
-    /**
-     * Register a plugin, or a plain `beforeLog`-style function. A function is
-     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
-     * same middleware ergonomics as Express/Koa, without needing to read the
-     * `Plugin` interface first. Returns `this` so calls can be chained.
-     */
-    use(plugin: Plugin | MiddlewareFunc): this;
-    /** Close every attached transport. Call on shutdown to flush buffered writes. */
-    close(): void;
-    /** A logger scoped under this one, inheriting its level, transports, and plugins. */
-    child(name: string, meta?: Record<string, unknown>): Logger;
-    private notifyError;
-    private dispatch;
-    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
-}
-
 declare const VERSION = "0.3.0";
 
-export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, type Formatter, FunctionPlugin, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, JSONFormatter, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MiddlewareFunc, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, type Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, Formatter, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, LevelInput, LogRecord, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, RunPlugin, type RunPluginOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, TraceContextPlugin, type TraceContextPluginOptions, Transport, VERSION, defaultResolveActiveOtelTraceId, generateTraceId, getTraceparent, parseTraceHeader, setTraceparent };

package/dist/index.d.ts

@@ -1,83 +1,113 @@
-/** Log levels, shared by name and numeric weight with the logquill-python contract. */
-declare enum Level {
-    TRACE = 5,
-    DEBUG = 10,
-    INFO = 20,
-    WARN = 30,
-    ERROR = 40,
-    FATAL = 50
-}
-/** A level given as a `Level`, a level name (any case), or its numeric weight. */
-type LevelInput = Level | number | string;
-/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
-declare function levelName(level: Level): string;
-/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
-declare function parseLevel(level: LevelInput): Level;
+import { P as Plugin, L as LogRecord, a as Level, T as Transport, b as LevelInput, F as Formatter } from './logger-D1_THnBJ.js';
+export { C as CollectingTransport, c as FunctionPlugin, J as JSONFormatter, d as Logger, e as LoggerOptions, M as MiddlewareFunc, S as SpanOptions, f as createRecord, l as levelName, p as parseLevel, u as utcTimestamp } from './logger-D1_THnBJ.js';
 
-/** The cross-language record shape shared with logquill-python. */
-interface LogRecord {
-    timestamp: string;
-    level: string;
-    logger: string;
-    message: string;
-    meta: Record<string, unknown>;
+/**
+ * Injects fixed key/value pairs into every record's `meta`.
+ * A value already present in a record's own `meta` wins over the fixed context.
+ */
+declare class ContextPlugin implements Plugin {
+    readonly context: Record<string, unknown>;
+    constructor(context: Record<string, unknown>);
+    beforeLog(record: LogRecord): LogRecord;
 }
-/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
-declare function utcTimestamp(): string;
-declare function createRecord(params: {
-    level: Level;
-    logger: string;
-    message: string;
-    meta: Record<string, unknown>;
-}): LogRecord;
 
-/** `format(record) -> string`, per the transport contract shared with logquill-python. */
-interface Formatter {
-    format(record: LogRecord): string;
+interface RunPluginOptions {
+    runId?: string;
 }
-/** Serializes a record to the canonical JSON line shape. */
-declare class JSONFormatter implements Formatter {
-    format(record: LogRecord): string;
+/**
+ * Stamps `meta.runId` — a stable id grouping every record from one agent
+ * run — plus an incrementing `meta.step` counter, one per record processed
+ * through this plugin instance.
+ *
+ * Distinct from `TraceContextPlugin`'s `traceId`: `runId` scopes one agent
+ * run, `traceId` follows one request across services. A run can span
+ * multiple traces (e.g. an agent that calls several downstream services);
+ * the two ids are independent.
+ *
+ * One instance is one run: attach a fresh `RunPlugin()` per run (typically
+ * via `logger.child("agent").use(new RunPlugin())`), never a process-wide
+ * singleton shared across runs — otherwise concurrent runs would share both
+ * the run id and the step counter.
+ *
+ * A record that already carries `meta.runId` (e.g. propagated from an
+ * upstream call) keeps its existing value; `meta.step` is always set from
+ * this instance's own counter.
+ */
+declare class RunPlugin implements Plugin {
+    readonly runId: string;
+    private step;
+    constructor(options?: RunPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
 }
 
 /**
- * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
- * `afterLog`, `onError`. All hooks are optional — implement only what you need.
- * A hook that throws cannot crash logging: the pipeline catches it, routes it
- * to `onError`, and moves on.
+ * Sets the inbound trace header for the current execution context (e.g.
+ * request-scoped HTTP middleware, before the handler runs) — the
+ * propagation mechanism framework middleware uses to hand `TraceContextPlugin`
+ * an inbound header without threading it through every log call. Backed by
+ * `AsyncLocalStorage`, so it's isolated per concurrent request. Returns a
+ * function that restores the previous value; call it (typically in a
+ * `finally` block) once the request is done.
  */
-interface Plugin {
-    /** Return a (possibly modified) record, or `null` to drop it. */
-    beforeLog?(record: LogRecord): LogRecord | null;
-    /** Called after the record has been dispatched to every transport. */
-    afterLog?(record: LogRecord): void;
-    /** Called when one of this plugin's own hooks throws. */
-    onError?(error: unknown, record: LogRecord): void;
-}
-/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
-type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+declare function setTraceparent(value: string | undefined): () => void;
+/** The header most recently set via `setTraceparent()` for this execution context. */
+declare function getTraceparent(): string | undefined;
+/** A fresh 32-hex-char id, matching the shape of an OTel/W3C trace id. */
+declare function generateTraceId(): string;
 /**
- * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
- * builds one of these automatically when given a function instead of a
- * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
- * read the `Plugin` interface first. There's no `next()` chaining: the
- * pipeline already calls hooks in sequence, so this is sugar for a
- * single-method `Plugin`, not a new execution model.
+ * Extracts a 32-hex-char trace id from a W3C `traceparent`, AWS X-Ray
+ * `X-Amzn-Trace-Id`, or GCP `X-Cloud-Trace-Context` header value. Returns
+ * `undefined` if `header` doesn't match any of the three shapes.
  */
-declare class FunctionPlugin implements Plugin {
-    private readonly func;
-    constructor(func: MiddlewareFunc);
-    beforeLog(record: LogRecord): LogRecord | null;
+declare function parseTraceHeader(header: string): string | undefined;
+/**
+ * Best-effort, synchronous lookup of the active OpenTelemetry span's trace
+ * id via a plain `require("@opentelemetry/api")` — `@opentelemetry/api` is
+ * never a declared dependency of this package (matching `logquill-python`'s
+ * lazy `import opentelemetry`); this returns `undefined` whenever it isn't
+ * installed, or no span is currently active, rather than throwing.
+ *
+ * A `require()` (via `createRequire`) rather than a dynamic `import()` is
+ * deliberate: `Plugin.beforeLog` is synchronous, so this has to be too.
+ */
+declare function defaultResolveActiveOtelTraceId(): string | undefined;
+interface TraceContextPluginOptions {
+    /** `meta` key the trace id is written to. Default `"traceId"`. */
+    traceKey?: string;
+    /** An inbound trace header to resolve on every record, bypassing `setTraceparent()`. */
+    traceparent?: string;
+    /** Override for testing, or to plug in a non-Node OTel API surface. Defaults to `defaultResolveActiveOtelTraceId`. */
+    resolveActiveOtelTraceId?: () => string | undefined;
 }
-
 /**
- * Injects fixed key/value pairs into every record's `meta`.
- * A value already present in a record's own `meta` wins over the fixed context.
+ * Stamps `meta.traceId` for cross-service correlation — distinct from
+ * `RunPlugin`'s `runId`: `traceId` follows one request across services,
+ * `runId` scopes one agent run.
+ *
+ * A record that already carries `meta[traceKey]` (e.g. because
+ * `SamplingPlugin`'s tail-based elevation, or an upstream plugin, already
+ * set one) is left alone. Otherwise resolves a trace id in priority order:
+ *
+ * 1. An active OpenTelemetry span's trace id, if `@opentelemetry/api` is
+ *    installed and a span is current — read directly, not just inbound
+ *    headers.
+ * 2. The `traceparent` constructor option, if given.
+ * 3. Whatever `setTraceparent()` most recently set for the current
+ *    execution context.
+ * 4. A freshly generated trace id, if none of the above produced one.
+ *
+ * Header parsing understands W3C `traceparent`, AWS X-Ray
+ * `X-Amzn-Trace-Id`, and GCP `X-Cloud-Trace-Context` — see
+ * `parseTraceHeader`. A header that doesn't parse is treated the same as no
+ * header: falls through to generating a new trace id.
  */
-declare class ContextPlugin implements Plugin {
-    readonly context: Record<string, unknown>;
-    constructor(context: Record<string, unknown>);
+declare class TraceContextPlugin implements Plugin {
+    readonly traceKey: string;
+    private readonly explicitTraceparent;
+    private readonly resolveActiveOtelTraceId;
+    constructor(options?: TraceContextPluginOptions);
     beforeLog(record: LogRecord): LogRecord;
+    private resolveTraceId;
 }
 
 declare const DEFAULT_REDACTED_KEYS: readonly string[];
@@ -133,27 +163,6 @@ declare class PIIRedactPlugin implements Plugin {
     private redactText;
 }
 
-/**
- * Sink for log records, per the cross-language transport contract:
- * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
- */
-declare abstract class Transport {
-    formatter: Formatter;
-    constructor(formatter?: Formatter);
-    format(record: LogRecord): string;
-    abstract write(formatted: string, record: LogRecord): void;
-    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
-    close(): void;
-}
-/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
-declare class CollectingTransport extends Transport {
-    readonly formatted: string[];
-    readonly records: LogRecord[];
-    closed: boolean;
-    write(formatted: string, record: LogRecord): void;
-    close(): void;
-}
-
 interface SamplingPluginOptions {
     rng?: () => number;
     /** `meta` key holding the trace/run id used to group buffered records. Default `"traceId"`. */
@@ -1233,42 +1242,6 @@ declare class HTTPTransport extends Transport {
     close(): void;
 }
 
-interface LoggerOptions {
-    level?: LevelInput;
-    transports?: Transport[];
-    plugins?: (Plugin | MiddlewareFunc)[];
-    meta?: Record<string, unknown>;
-}
-declare class Logger {
-    readonly name: string;
-    readonly transports: Transport[];
-    readonly plugins: Plugin[];
-    private currentLevel;
-    private readonly baseMeta;
-    constructor(name: string, options?: LoggerOptions);
-    get level(): Level;
-    setLevel(level: LevelInput): void;
-    /**
-     * Register a plugin, or a plain `beforeLog`-style function. A function is
-     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
-     * same middleware ergonomics as Express/Koa, without needing to read the
-     * `Plugin` interface first. Returns `this` so calls can be chained.
-     */
-    use(plugin: Plugin | MiddlewareFunc): this;
-    /** Close every attached transport. Call on shutdown to flush buffered writes. */
-    close(): void;
-    /** A logger scoped under this one, inheriting its level, transports, and plugins. */
-    child(name: string, meta?: Record<string, unknown>): Logger;
-    private notifyError;
-    private dispatch;
-    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
-    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
-}
-
 declare const VERSION = "0.3.0";
 
-export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, type Formatter, FunctionPlugin, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, JSONFormatter, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MiddlewareFunc, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, type Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, Formatter, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, LevelInput, LogRecord, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, RunPlugin, type RunPluginOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, TraceContextPlugin, type TraceContextPluginOptions, Transport, VERSION, defaultResolveActiveOtelTraceId, generateTraceId, getTraceparent, parseTraceHeader, setTraceparent };