logquill 0.3.0 → 1.0.0

package/dist/index.mjs

@@ -1,4 +1,6 @@
-import { createHash } from 'crypto';
+import { AsyncLocalStorage } from 'async_hooks';
+import { randomUUID, randomBytes, createHash } from 'crypto';
+import { createRequire } from 'module';
 import { gzipSync } from 'zlib';
 import { mkdirSync, openSync, writeSync, fstatSync, closeSync, existsSync, unlinkSync, renameSync } from 'fs';
 import { dirname } from 'path';
@@ -54,6 +56,7 @@ function createRecord(params) {
 
 // src/core/formatter.ts
 var JSONFormatter = class {
+  /** Returns `JSON.stringify(record)`. */
   format(record) {
     return JSON.stringify(record);
   }
@@ -72,6 +75,7 @@ var FunctionPlugin = class {
 
 // src/plugins/context-plugin.ts
 var ContextPlugin = class {
+  /** Fixed key/value pairs merged into every record's `meta`. */
   context;
   constructor(context) {
     this.context = context;
@@ -80,11 +84,297 @@ var ContextPlugin = class {
     return { ...record, meta: { ...this.context, ...record.meta } };
   }
 };
+var contextStore = new AsyncLocalStorage();
+function currentContext() {
+  return contextStore.getStore() ?? {};
+}
+function bindContext(values, fn) {
+  return contextStore.run({ ...currentContext(), ...values }, fn);
+}
+
+// src/plugins/rate-limit-plugin.ts
+function defaultKey(record) {
+  return `${record.logger}:${record.level}`;
+}
+var RateLimitPlugin = class {
+  /** Records allowed per key within a `perSeconds` window before further records for that key are dropped. */
+  maxRecords;
+  /** Length, in seconds, of each key's rolling window. */
+  perSeconds;
+  /** Distinct keys tracked at once before the least-recently-seen one is evicted. */
+  maxKeys;
+  keyFunc;
+  clock;
+  windows = /* @__PURE__ */ new Map();
+  constructor(maxRecords, perSeconds, options = {}) {
+    if (maxRecords < 1) {
+      throw new Error(`maxRecords must be at least 1, got ${String(maxRecords)}`);
+    }
+    if (perSeconds <= 0) {
+      throw new Error(`perSeconds must be positive, got ${String(perSeconds)}`);
+    }
+    this.maxRecords = maxRecords;
+    this.perSeconds = perSeconds;
+    this.keyFunc = options.keyFunc ?? defaultKey;
+    this.maxKeys = options.maxKeys ?? 1e3;
+    this.clock = options.clock ?? (() => performance.now() / 1e3);
+  }
+  beforeLog(record) {
+    const key = this.keyFunc(record);
+    const now = this.clock();
+    const window = this.windows.get(key);
+    if (window === void 0 || now - window.start >= this.perSeconds) {
+      this.windows.delete(key);
+      this.windows.set(key, { start: now, count: 1 });
+      while (this.windows.size > this.maxKeys) {
+        this.evictOldest();
+      }
+      return record;
+    }
+    this.windows.delete(key);
+    this.windows.set(key, window);
+    if (window.count >= this.maxRecords) {
+      return null;
+    }
+    window.count += 1;
+    return record;
+  }
+  evictOldest() {
+    const oldest = this.windows.keys().next();
+    if (!oldest.done) {
+      this.windows.delete(oldest.value);
+    }
+  }
+};
+
+// src/bridges/level-dispatch.ts
+function callAtLevel(log, level, message, meta) {
+  switch (level) {
+    case 5 /* TRACE */:
+      log.trace(message, meta);
+      return;
+    case 10 /* DEBUG */:
+      log.debug(message, meta);
+      return;
+    case 20 /* INFO */:
+      log.info(message, meta);
+      return;
+    case 30 /* WARN */:
+      log.warn(message, meta);
+      return;
+    case 40 /* ERROR */:
+      log.error(message, meta);
+      return;
+    case 50 /* FATAL */:
+      log.fatal(message, meta);
+      return;
+  }
+}
+
+// src/bridges/pino-destination.ts
+var DEFAULT_PINO_LEVEL_MAP = {
+  10: 5 /* TRACE */,
+  20: 10 /* DEBUG */,
+  30: 20 /* INFO */,
+  40: 30 /* WARN */,
+  50: 40 /* ERROR */,
+  60: 50 /* FATAL */
+};
+var LogQuillPinoDestination = class {
+  /**
+   * Pino only recognizes a bare object passed as its sole argument
+   * (`pino(destination)`, without a separate options argument) as a
+   * destination stream, rather than an options object, if it looks
+   * stream-like — checking for `.writable`/`._writableState`, the same
+   * duck-typing `stream.Writable` itself satisfies. Without this, `pino()`
+   * would silently fall back to writing to `process.stdout` instead.
+   */
+  writable = true;
+  target;
+  levelMap;
+  constructor(logquillLogger, options = {}) {
+    this.target = logquillLogger;
+    this.levelMap = options.levelMap ?? DEFAULT_PINO_LEVEL_MAP;
+  }
+  /** Node `Writable`-compatible write hook — splits `chunk` into NDJSON lines and dispatches each as a `Logger` call. */
+  write(chunk) {
+    for (const line of chunk.split("\n")) {
+      if (line.trim()) {
+        this.writeLine(line);
+      }
+    }
+    return true;
+  }
+  writeLine(line) {
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      return;
+    }
+    const entry = parsed;
+    const pinoLevel = typeof entry.level === "number" ? entry.level : 30;
+    const message = typeof entry.msg === "string" ? entry.msg : "";
+    const meta = {};
+    for (const key of Object.keys(entry)) {
+      if (key !== "level" && key !== "msg") {
+        meta[key] = entry[key];
+      }
+    }
+    callAtLevel(this.target, this.levelMap[pinoLevel] ?? 20 /* INFO */, message, meta);
+  }
+};
+var RunPlugin = class {
+  /** Id stamped onto `meta.runId` for every record this instance processes. */
+  runId;
+  step = 0;
+  constructor(options = {}) {
+    this.runId = options.runId ?? randomUUID();
+  }
+  beforeLog(record) {
+    record.meta.runId ??= this.runId;
+    record.meta.step = this.step++;
+    return record;
+  }
+};
+var traceparentStore = new AsyncLocalStorage();
+function setTraceparent(value) {
+  const previous = traceparentStore.getStore();
+  traceparentStore.enterWith(value);
+  return () => {
+    traceparentStore.enterWith(previous);
+  };
+}
+function getTraceparent() {
+  return traceparentStore.getStore();
+}
+function generateTraceId() {
+  return randomBytes(16).toString("hex");
+}
+var W3C_TRACEPARENT_RE = /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/;
+var XRAY_ROOT_RE = /Root=1-([0-9a-f]{8})-([0-9a-f]{24})/;
+var GCP_TRACE_RE = /^([0-9a-f]{32})\/\d+(;o=\d)?$/;
+function parseTraceHeader(header) {
+  const trimmed = header.trim();
+  const w3c = W3C_TRACEPARENT_RE.exec(trimmed);
+  if (w3c?.[1]) {
+    return w3c[1];
+  }
+  const xray = XRAY_ROOT_RE.exec(trimmed);
+  if (xray?.[1] && xray[2]) {
+    return xray[1] + xray[2];
+  }
+  const gcp = GCP_TRACE_RE.exec(trimmed);
+  if (gcp?.[1]) {
+    return gcp[1];
+  }
+  return void 0;
+}
+function defaultResolveActiveOtelTraceId() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const otel = require2("@opentelemetry/api");
+    const span = otel.trace.getActiveSpan();
+    if (!span) {
+      return void 0;
+    }
+    const spanContext = span.spanContext();
+    if (!otel.trace.isSpanContextValid(spanContext)) {
+      return void 0;
+    }
+    return spanContext.traceId;
+  } catch {
+    return void 0;
+  }
+}
+var TraceContextPlugin = class {
+  /** `meta` key the trace id is written to. */
+  traceKey;
+  explicitTraceparent;
+  resolveActiveOtelTraceId;
+  constructor(options = {}) {
+    this.traceKey = options.traceKey ?? "traceId";
+    this.explicitTraceparent = options.traceparent;
+    this.resolveActiveOtelTraceId = options.resolveActiveOtelTraceId ?? defaultResolveActiveOtelTraceId;
+  }
+  beforeLog(record) {
+    if (record.meta[this.traceKey] != null) {
+      return record;
+    }
+    record.meta[this.traceKey] = this.resolveTraceId();
+    return record;
+  }
+  resolveTraceId() {
+    const fromOtel = this.resolveActiveOtelTraceId();
+    if (fromOtel) {
+      return fromOtel;
+    }
+    const header = this.explicitTraceparent ?? getTraceparent();
+    if (header) {
+      const parsed = parseTraceHeader(header);
+      if (parsed) {
+        return parsed;
+      }
+    }
+    return generateTraceId();
+  }
+};
+
+// src/plugins/otel-span-processor.ts
+var OTEL_STATUS_CODE_ERROR = 2;
+var OtelSpanProcessor = class {
+  log;
+  attributesKey;
+  constructor(log, options = {}) {
+    this.log = log;
+    this.attributesKey = options.attributesKey ?? "attributes";
+  }
+  /** Called by the tracer provider when a span starts — emits `.action()`. */
+  onStart(span) {
+    this.log.action(span.name, this.baseMeta(span));
+  }
+  /** Called by the tracer provider when a span ends — emits `.observation()`, or `.error()` if the span's status is an error. */
+  onEnd(span) {
+    const meta = {
+      ...this.baseMeta(span),
+      durationMs: span.duration[0] * 1e3 + span.duration[1] / 1e6
+    };
+    if (span.status.code === OTEL_STATUS_CODE_ERROR) {
+      this.log.error(span.name, {
+        ...meta,
+        error: span.status.message ?? "span ended with an error status"
+      });
+      return;
+    }
+    this.log.observation(span.name, meta);
+  }
+  /** No internal buffering to flush — every span is forwarded to the `Logger` immediately. */
+  async forceFlush() {
+  }
+  /** No resources of its own to release; flush/close the wrapped `Logger` separately. */
+  async shutdown() {
+  }
+  baseMeta(span) {
+    const meta = { spanId: span.spanContext().spanId };
+    const parentSpanId = span.parentSpanContext?.spanId ?? span.parentSpanId;
+    if (parentSpanId) {
+      meta.parentSpanId = parentSpanId;
+    }
+    if (Object.keys(span.attributes).length > 0) {
+      meta[this.attributesKey] = span.attributes;
+    }
+    return meta;
+  }
+};
 
 // src/plugins/redact-plugin.ts
 var DEFAULT_REDACTED_KEYS = ["password", "token", "secret", "api_key", "authorization"];
 var RedactPlugin = class {
   keys;
+  /** Placeholder a matched value is replaced with. */
   replacement;
   constructor(options = {}) {
     this.keys = new Set((options.keys ?? DEFAULT_REDACTED_KEYS).map((key) => key.toLowerCase()));
@@ -108,7 +398,9 @@ var DEFAULT_PII_PATTERNS = {
 };
 var MAX_DEPTH = 50;
 var PIIRedactPlugin = class {
+  /** Named patterns scanned for in every string `meta` value. */
   patterns;
+  /** Placeholder a matched substring is replaced with. */
   replacement;
   constructor(options = {}) {
     this.patterns = options.patterns ?? DEFAULT_PII_PATTERNS;
@@ -156,11 +448,17 @@ var PIIRedactPlugin = class {
 
 // src/plugins/sampling-plugin.ts
 var SamplingPlugin = class {
+  /** Fraction of non-elevated records kept, in `[0, 1]`. */
   rate;
+  /** `meta` key holding the trace/run id used to group buffered records. */
   traceKey;
+  /** A record at or above this level elevates its whole trace. */
   elevateAt;
+  /** Transports buffered records are flushed straight to on elevation; `undefined` disables tail-based elevation. */
   transports;
+  /** Total buffered records allowed across every trace before the oldest trace is evicted. */
   maxBufferedRecords;
+  /** Distinct trace ids held at once before the oldest is evicted. */
   maxTraces;
   rng;
   buffer = /* @__PURE__ */ new Map();
@@ -306,8 +604,11 @@ function defaultDedupeKey(record) {
   return `${record.level}:${record.logger}:${record.message}`;
 }
 var AlertingPlugin = class {
+  /** A record at or above this level fires an alert. */
   threshold;
+  /** How long a dedupe window stays open before a collapsed follow-up alert (if any) fires. */
   dedupeWindowMs;
+  /** Distinct concurrent dedupe keys tracked at once; beyond this, new keys are dropped rather than tracked. */
   maxTrackedKeys;
   dedupeKeyFn;
   windows = /* @__PURE__ */ new Map();
@@ -381,6 +682,7 @@ function formatMessage(record, occurrences) {
   return `[${record.level}] ${record.logger}: ${record.message}${suffix}`;
 }
 var SlackAlertPlugin = class extends AlertingPlugin {
+  /** Slack "Incoming Webhook" URL every alert is posted to. */
   webhookUrl;
   sender;
   constructor(webhookUrl, options = {}) {
@@ -410,6 +712,7 @@ async function fetchPagerDutySender(body) {
   }
 }
 var PagerDutyAlertPlugin = class extends AlertingPlugin {
+  /** PagerDuty Events API v2 integration key every alert is sent under. */
   routingKey;
   sender;
   constructor(routingKey, options = {}) {
@@ -439,9 +742,13 @@ var PagerDutyAlertPlugin = class extends AlertingPlugin {
 
 // src/plugins/email-alert-plugin.ts
 var EmailAlertPlugin = class extends AlertingPlugin {
+  /** SMTP server hostname. */
   smtpHost;
+  /** SMTP server port. */
   smtpPort;
+  /** Envelope `From` address for every alert. */
   fromAddr;
+  /** Envelope `To` addresses for every alert. */
   toAddrs;
   username;
   password;
@@ -507,10 +814,12 @@ var EmailAlertPlugin = class extends AlertingPlugin {
 
 // src/transports/transport.ts
 var Transport = class {
+  /** Turns a `LogRecord` into the string this transport actually writes. Defaults to `JSONFormatter`. */
   formatter;
   constructor(formatter = new JSONFormatter()) {
     this.formatter = formatter;
   }
+  /** Formats `record` via `this.formatter`. Called once per record before `write()`. */
   format(record) {
     return this.formatter.format(record);
   }
@@ -518,9 +827,15 @@ var Transport = class {
   close() {
   }
 };
+function hasFlush(transport) {
+  return typeof transport.flush === "function";
+}
 var CollectingTransport = class extends Transport {
+  /** Every formatted string passed to `write()`, in call order. */
   formatted = [];
+  /** Every raw `LogRecord` passed to `write()`, in call order. */
   records = [];
+  /** Set once `close()` has been called. */
   closed = false;
   write(formatted, record) {
     this.formatted.push(formatted);
@@ -533,7 +848,9 @@ var CollectingTransport = class extends Transport {
 
 // src/transports/batching-transport.ts
 var BatchingTransport = class extends Transport {
+  /** Buffer is flushed once it holds this many items. */
   maxRecords;
+  /** Buffer is flushed once its estimated byte size reaches this many bytes. */
   maxBytes;
   buffer = [];
   bufferBytes = 0;
@@ -550,6 +867,7 @@ var BatchingTransport = class extends Transport {
   sizeOf(item) {
     return JSON.stringify(item).length;
   }
+  /** Buffers the record, flushing the batch once `maxRecords`/`maxBytes` is reached. */
   write(formatted, record) {
     const item = this.toItem(formatted, record);
     this.buffer.push(item);
@@ -584,7 +902,9 @@ function metaString(meta, key) {
   return typeof value === "string" ? value : null;
 }
 var BaseSQLTransport = class extends BatchingTransport {
+  /** Table records are inserted into. */
   tableName;
+  /** Whether `createTableSQL()` runs before the first insert. Dev/test convenience only. */
   ensureSchema;
   schemaEnsured = false;
   constructor(options = {}) {
@@ -1057,6 +1377,7 @@ var RedisTransport = class extends BatchingTransport {
 
 // src/transports/queue/base-queue-transport.ts
 var BaseQueueTransport = class extends BatchingTransport {
+  /** Destination name on the backend — a Kafka topic, a RabbitMQ queue name, an SQS queue URL, or a GCP Pub/Sub topic. */
   topic;
   constructor(options) {
     super(options);
@@ -1255,8 +1576,11 @@ var PubSubTransport = class extends BaseQueueTransport {
 
 // src/transports/cloud/cloudwatch-transport.ts
 var CloudWatchTransport = class extends BatchingTransport {
+  /** CloudWatch Logs log group written into. */
   logGroupName;
+  /** CloudWatch Logs log stream, within `logGroupName`, written into. */
   logStreamName;
+  /** AWS region passed to the real SDK client; `undefined` when `client` is injected or the SDK's own credential-chain resolution is used. */
   region;
   injectedClient;
   client;
@@ -1324,7 +1648,9 @@ function gcpSeverity(levelValue) {
   }
 }
 var CloudLoggingTransport = class extends BatchingTransport {
+  /** GCP log name (the last segment of the log resource path). */
   logName;
+  /** GCP project ID passed to the real SDK client; `undefined` when `client` is injected or Application Default Credentials' project is used. */
   projectId;
   injectedClient;
   client;
@@ -1389,6 +1715,7 @@ function appInsightsSeverity(levelValue) {
   }
 }
 var AppInsightsTransport = class extends BatchingTransport {
+  /** Azure Application Insights connection string passed to the real SDK client; `undefined` when `client` is injected. */
   connectionString;
   injectedClient;
   client;
@@ -1448,8 +1775,11 @@ async function fetchDatadogSender(url, apiKey, batch) {
   }
 }
 var DatadogTransport = class extends BatchingTransport {
+  /** Logs intake endpoint derived from `site`. */
   url;
+  /** Datadog API key sent in the `DD-API-KEY` header. */
   apiKey;
+  /** Datadog site (region) this transport sends to. */
   site;
   sender;
   constructor(options) {
@@ -1477,7 +1807,9 @@ async function fetchElasticsearchSender(url, headers, body) {
   }
 }
 var ElasticsearchTransport = class extends BatchingTransport {
+  /** `_bulk` endpoint derived from the `node` option. */
   url;
+  /** Index written into. */
   index;
   apiKey;
   sender;
@@ -1528,7 +1860,9 @@ function resumeTimestamp(retryAfter, now) {
   return Number.isNaN(dateMs) ? now + 6e4 : dateMs;
 }
 var NewRelicTransport = class extends BatchingTransport {
+  /** Ingest endpoint derived from `region`. */
   url;
+  /** New Relic account region this transport sends to. */
   region;
   licenseKey;
   sender;
@@ -1595,6 +1929,7 @@ function defaultColorize() {
   return env?.NO_COLOR === void 0;
 }
 var ConsoleTransport = class extends Transport {
+  /** Whether each line is wrapped in an ANSI color escape for its level. */
   colorize;
   out;
   constructor(options = {}) {
@@ -1602,6 +1937,7 @@ var ConsoleTransport = class extends Transport {
     this.colorize = options.colorize ?? defaultColorize();
     this.out = options.console ?? console;
   }
+  /** Writes `formatted` via `console.log`, or `console.error` for ERROR/FATAL records. */
   write(formatted, record) {
     const level = parseLevel(record.level);
     const line = this.colorize ? this.applyColor(formatted, level) : formatted;
@@ -1615,9 +1951,62 @@ var ConsoleTransport = class extends Transport {
     return `${COLORS[level]}${formatted}${RESET}`;
   }
 };
+
+// src/transports/beacon-transport.ts
+function defaultBeaconSender(url, batch) {
+  const body = batch.join("\n");
+  const nav = typeof navigator === "undefined" ? void 0 : navigator;
+  if (nav && typeof nav.sendBeacon === "function") {
+    nav.sendBeacon(url, body);
+    return;
+  }
+  void fetch(url, { method: "POST", body, keepalive: true }).catch((error) => {
+    console.error("BeaconTransport: failed to send log batch", error);
+  });
+}
+var BeaconTransport = class extends Transport {
+  /** Endpoint each batch is sent to. */
+  url;
+  /** Buffer is flushed once it holds this many lines. */
+  batchSize;
+  sender;
+  batch = [];
+  constructor(url, options = {}) {
+    super(options.formatter);
+    this.url = url;
+    this.batchSize = options.batchSize ?? 20;
+    this.sender = options.sender ?? defaultBeaconSender;
+  }
+  /** Buffers the formatted line, flushing the batch once `batchSize` is reached. */
+  write(formatted) {
+    this.batch.push(formatted);
+    if (this.batch.length >= this.batchSize) {
+      this.flush();
+    }
+  }
+  /** Send the current batch now, even if it hasn't reached `batchSize`. */
+  flush() {
+    if (this.batch.length === 0) {
+      return;
+    }
+    const batch = this.batch;
+    this.batch = [];
+    try {
+      this.sender(this.url, batch);
+    } catch (error) {
+      console.error("BeaconTransport: failed to send log batch", error);
+    }
+  }
+  close() {
+    this.flush();
+  }
+};
 var FileTransport = class extends Transport {
+  /** Path of the file records are appended to. */
   path;
+  /** File is rotated once it reaches this many bytes. `0` disables rotation. */
   maxBytes;
+  /** How many rotated backups (`.1`, `.2`, ...) are kept. */
   backupCount;
   fd;
   constructor(path, options = {}) {
@@ -1628,6 +2017,7 @@ var FileTransport = class extends Transport {
     mkdirSync(dirname(path), { recursive: true });
     this.fd = openSync(this.path, "a");
   }
+  /** Appends one formatted line to the file, rotating first if `maxBytes` has been exceeded. */
   write(formatted) {
     writeSync(this.fd, formatted + "\n");
     if (this.maxBytes > 0 && fstatSync(this.fd).size >= this.maxBytes) {
@@ -1674,7 +2064,9 @@ async function fetchSender(url, batch) {
   }
 }
 var HTTPTransport = class extends Transport {
+  /** Endpoint each batch is POSTed to. */
   url;
+  /** Buffer is flushed once it holds this many lines. */
   batchSize;
   sender;
   batch = [];
@@ -1684,6 +2076,7 @@ var HTTPTransport = class extends Transport {
     this.batchSize = options.batchSize ?? 50;
     this.sender = options.sender ?? fetchSender;
   }
+  /** Buffers the formatted line, flushing the batch once `batchSize` is reached. */
   write(formatted) {
     this.batch.push(formatted);
     if (this.batch.length >= this.batchSize) {
@@ -1709,13 +2102,182 @@ var HTTPTransport = class extends Transport {
   }
 };
 
+// src/core/dispatch-queue.ts
+function isPromise(value) {
+  return typeof value === "object" && typeof value.then === "function";
+}
+function defaultScheduler(run) {
+  if (typeof setImmediate === "function") {
+    setImmediate(run);
+  } else {
+    queueMicrotask(run);
+  }
+}
+function defaultOnDrop(count, policy) {
+  console.warn(
+    `DispatchQueue: dropped ${String(count)} record(s) \u2014 queue exceeded its configured size under the "${policy}" backpressure policy`
+  );
+}
+var DispatchQueue = class {
+  /** Maximum number of pending tasks held at once, as configured via `DispatchQueueOptions`. */
+  maxSize;
+  /** Backpressure policy applied once `maxSize` is reached, as configured via `DispatchQueueOptions`. */
+  policy;
+  onDrop;
+  warnIntervalMs;
+  tasks = [];
+  draining = false;
+  scheduled = false;
+  idleWaiters = [];
+  droppedSinceWarning = 0;
+  lastWarnAt = 0;
+  constructor(options = {}) {
+    this.maxSize = options.maxSize ?? 1e4;
+    this.policy = options.policy ?? "dropOldest";
+    this.onDrop = options.onDrop ?? defaultOnDrop;
+    this.warnIntervalMs = options.warnIntervalMs ?? 5e3;
+  }
+  /** Number of tasks currently waiting to run. Bounded by `maxSize`. */
+  get size() {
+    return this.tasks.length;
+  }
+  /**
+   * Queue `task` to run outside the current call stack, applying the
+   * configured backpressure policy if the queue is already full. Under
+   * `"block"`, `task` may run synchronously before this call returns.
+   */
+  enqueue(task) {
+    if (this.tasks.length < this.maxSize) {
+      this.tasks.push(task);
+      this.schedule();
+      return;
+    }
+    switch (this.policy) {
+      case "dropNewest":
+        this.recordDrop();
+        return;
+      case "block":
+        this.runInline(task);
+        return;
+      case "dropOldest":
+      default:
+        this.tasks.shift();
+        this.recordDrop();
+        this.tasks.push(task);
+        this.schedule();
+        return;
+    }
+  }
+  /** Resolves once every task queued so far has run. Safe to call when idle. */
+  async flush() {
+    if (this.tasks.length === 0 && !this.draining) {
+      return;
+    }
+    await new Promise((resolve) => {
+      this.idleWaiters.push(resolve);
+      this.schedule();
+    });
+  }
+  recordDrop() {
+    this.droppedSinceWarning += 1;
+    const now = Date.now();
+    if (now - this.lastWarnAt >= this.warnIntervalMs) {
+      const count = this.droppedSinceWarning;
+      this.droppedSinceWarning = 0;
+      this.lastWarnAt = now;
+      try {
+        this.onDrop(count, this.policy);
+      } catch {
+      }
+    }
+  }
+  runInline(task) {
+    try {
+      const result = task();
+      if (isPromise(result)) {
+        result.catch((error) => {
+          console.error("DispatchQueue: a blocked task failed", error);
+        });
+      }
+    } catch (error) {
+      console.error("DispatchQueue: a blocked task failed", error);
+    }
+  }
+  schedule() {
+    if (this.scheduled) {
+      return;
+    }
+    this.scheduled = true;
+    defaultScheduler(() => {
+      this.scheduled = false;
+      void this.drainAll();
+    });
+  }
+  async drainAll() {
+    if (this.draining) {
+      return;
+    }
+    this.draining = true;
+    try {
+      while (this.tasks.length > 0) {
+        const task = this.tasks.shift();
+        if (!task) {
+          continue;
+        }
+        try {
+          await task();
+        } catch (error) {
+          console.error("DispatchQueue: a queued task failed", error);
+        }
+      }
+    } finally {
+      this.draining = false;
+      const waiters = this.idleWaiters;
+      this.idleWaiters = [];
+      for (const resolve of waiters) {
+        resolve();
+      }
+    }
+  }
+};
+var spanIdStore = new AsyncLocalStorage();
+function currentSpanId() {
+  return spanIdStore.getStore();
+}
+function newSpanId() {
+  return randomBytes(8).toString("hex");
+}
+function runInSpan(spanId, fn) {
+  return spanIdStore.run(spanId, fn);
+}
+
 // src/core/logger.ts
+function formatSpanError(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
+function withStackFromErr(meta) {
+  const err = meta.err;
+  if (!(err instanceof Error)) {
+    return meta;
+  }
+  const next = { ...meta };
+  delete next.err;
+  next.stack = err.stack ?? `${err.name}: ${err.message}`;
+  return next;
+}
 var Logger = class _Logger {
+  /** This logger's name, as passed to the constructor (or derived via `.child()`). Appears on every record as `logger`. */
   name;
+  /** Every transport a written record is sent to. */
   transports;
+  /** Every plugin registered via `.use()`, in registration order. */
   plugins;
   currentLevel;
   baseMeta;
+  dispatchQueue;
   constructor(name, options = {}) {
     this.name = name;
     this.currentLevel = parseLevel(options.level ?? 20 /* INFO */);
@@ -1725,10 +2287,13 @@ var Logger = class _Logger {
       this.use(plugin);
     }
     this.baseMeta = options.meta ? { ...options.meta } : {};
+    this.dispatchQueue = new DispatchQueue(options.queue);
   }
+  /** This logger's current minimum level — records below it are filtered before any plugin runs. */
   get level() {
     return this.currentLevel;
   }
+  /** Changes the minimum level records must meet to reach a transport. Accepts a `Level`, its numeric weight, or its name. */
   setLevel(level) {
     this.currentLevel = parseLevel(level);
   }
@@ -1742,20 +2307,41 @@ var Logger = class _Logger {
     this.plugins.push(typeof plugin === "function" ? new FunctionPlugin(plugin) : plugin);
     return this;
   }
-  /** Close every attached transport. Call on shutdown to flush buffered writes. */
-  close() {
+  /** Number of dispatched records not yet written to their transports. Bounded by the `queue` option. */
+  get queueSize() {
+    return this.dispatchQueue.size;
+  }
+  /**
+   * Waits for every record dispatched so far to reach its transports'
+   * `write()` (and any plugin `afterLog` hooks). Note this does *not* force
+   * a batching transport (SQL, a queue, `HTTPTransport`, ...) to send a
+   * batch still under its own `maxRecords`/`maxBytes` threshold early — it
+   * only guarantees the record has been handed to that transport, the same
+   * contract `write()` always had. Before a process may pause or exit
+   * (a serverless freeze, a shutdown signal), prefer `withLambda`/
+   * `installShutdownHandlers`, which additionally force every batching
+   * transport to send its current buffer regardless of threshold.
+   */
+  async flush() {
+    await this.dispatchQueue.flush();
+  }
+  /** Flush every pending record, then close every attached transport. Call once, on shutdown. */
+  async close() {
+    await this.flush();
     for (const transport of this.transports) {
       transport.close();
     }
   }
-  /** A logger scoped under this one, inheriting its level, transports, and plugins. */
+  /** A logger scoped under this one, inheriting its level, transports, plugins, and dispatch queue. */
   child(name, meta = {}) {
-    return new _Logger(`${this.name}.${name}`, {
+    const child = new _Logger(`${this.name}.${name}`, {
       level: this.currentLevel,
       transports: this.transports,
       plugins: this.plugins,
       meta: { ...this.baseMeta, ...meta }
     });
+    child.dispatchQueue = this.dispatchQueue;
+    return child;
   }
   notifyError(plugin, error, record) {
     try {
@@ -1771,8 +2357,12 @@ var Logger = class _Logger {
       level,
       logger: this.name,
       message,
-      meta: { ...this.baseMeta, ...meta }
+      meta: { ...this.baseMeta, ...currentContext(), ...withStackFromErr(meta) }
     });
+    const parentSpanId = currentSpanId();
+    if (parentSpanId !== void 0) {
+      record.meta.parentSpanId ??= parentSpanId;
+    }
     for (const plugin of this.plugins) {
       let result;
       try {
@@ -1786,8 +2376,18 @@ var Logger = class _Logger {
       }
       record = result;
     }
+    this.dispatchQueue.enqueue(() => {
+      this.writeAndNotify(record);
+    });
+    return record;
+  }
+  writeAndNotify(record) {
     for (const transport of this.transports) {
-      transport.write(transport.format(record), record);
+      try {
+        transport.write(transport.format(record), record);
+      } catch (error) {
+        console.error(`${transport.constructor.name}: failed to write a log record`, error);
+      }
     }
     for (const plugin of this.plugins) {
       try {
@@ -1796,31 +2396,158 @@ var Logger = class _Logger {
         this.notifyError(plugin, error, record);
       }
     }
-    return record;
   }
+  /** Logs at `TRACE` — the lowest level, for fine-grained diagnostic detail. Returns the record, or `null` if filtered/dropped. */
   trace(message, meta = {}) {
     return this.dispatch(5 /* TRACE */, message, meta);
   }
+  /** Logs at `DEBUG`. Returns the record, or `null` if filtered/dropped. */
   debug(message, meta = {}) {
     return this.dispatch(10 /* DEBUG */, message, meta);
   }
+  /** Logs at `INFO`. Returns the record, or `null` if filtered/dropped. */
   info(message, meta = {}) {
     return this.dispatch(20 /* INFO */, message, meta);
   }
+  /** Logs at `WARN`. Returns the record, or `null` if filtered/dropped. */
   warn(message, meta = {}) {
     return this.dispatch(30 /* WARN */, message, meta);
   }
+  /** Logs at `ERROR`. Returns the record, or `null` if filtered/dropped. */
   error(message, meta = {}) {
     return this.dispatch(40 /* ERROR */, message, meta);
   }
+  /** Logs at `FATAL` — the highest level, for errors that precede an unrecoverable failure. Returns the record, or `null` if filtered/dropped. */
   fatal(message, meta = {}) {
     return this.dispatch(50 /* FATAL */, message, meta);
   }
+  /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+  thought(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "thought", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+  action(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "action", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+  observation(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "observation", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+  decision(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "decision", ...meta });
+  }
+  /**
+   * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+   * settling (success or throw) emits one record for the span itself
+   * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+   * inside `fn` — through any method, and through any further `await` —
+   * is automatically stamped with `meta.parentSpanId` pointing at this
+   * span, so nested/sub-agent calls reconstruct their exact nesting when
+   * sorted by `spanId`/`parentSpanId`.
+   *
+   * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+   * throws; the error itself propagates unchanged to the caller.
+   *
+   * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+   * `options` to adopt an id handed in from elsewhere (e.g. a framework
+   * adapter translating an id it already received).
+   */
+  async span(name, fn, options = {}) {
+    const { spanId: explicitSpanId, parentSpanId: explicitParentSpanId, ...meta } = options;
+    const spanId = explicitSpanId ?? newSpanId();
+    const start = performance.now();
+    try {
+      const result = await runInSpan(spanId, () => fn());
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta);
+      return result;
+    } catch (error) {
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta, error);
+      throw error;
+    }
+  }
+  finishSpan(name, spanId, explicitParentSpanId, durationMs, meta, error) {
+    const fullMeta = {
+      spanId,
+      durationMs: Math.round(durationMs * 1e3) / 1e3,
+      ...meta
+    };
+    if (explicitParentSpanId !== void 0) {
+      fullMeta.parentSpanId = explicitParentSpanId;
+    }
+    fullMeta.kind ??= "span";
+    if (error !== void 0) {
+      fullMeta.error = formatSpanError(error);
+    }
+    this.dispatch(error !== void 0 ? 40 /* ERROR */ : 20 /* INFO */, name, fullMeta);
+  }
 };
 
+// src/core/serverless.ts
+async function flushEverything(logger) {
+  await logger.flush();
+  for (const transport of logger.transports) {
+    if (!hasFlush(transport)) {
+      continue;
+    }
+    try {
+      await transport.flush();
+    } catch (error) {
+      console.error(`${transport.constructor.name}: failed to flush`, error);
+    }
+  }
+}
+function withFlush(logger, fn) {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } finally {
+      await flushEverything(logger);
+    }
+  };
+}
+var withLambda = withFlush;
+var withCloudFunction = withFlush;
+var withAzureFunction = withFlush;
+
+// src/core/shutdown.ts
+function installShutdownHandlers(logger, options = {}) {
+  const signals = options.signals ?? ["SIGTERM", "SIGINT"];
+  let closed = false;
+  const shutdown = (exitAfter) => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    logger.close().catch((error) => {
+      console.error("installShutdownHandlers: logger.close() failed during shutdown", error);
+    }).finally(() => {
+      if (exitAfter) {
+        process.exit(0);
+      }
+    });
+  };
+  const onBeforeExit = () => {
+    shutdown(false);
+  };
+  const onSignal = () => {
+    shutdown(true);
+  };
+  process.once("beforeExit", onBeforeExit);
+  for (const signal of signals) {
+    process.once(signal, onSignal);
+  }
+  return () => {
+    process.removeListener("beforeExit", onBeforeExit);
+    for (const signal of signals) {
+      process.removeListener(signal, onSignal);
+    }
+  };
+}
+
 // src/index.ts
 var VERSION = "0.3.0";
 
-export { AlertingPlugin, AppInsightsTransport, BaseQueueTransport, BaseSQLTransport, BatchingTransport, CloudLoggingTransport, CloudWatchTransport, CollectingTransport, ConsoleTransport, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, DatadogTransport, DynamoDBTransport, ElasticsearchTransport, EmailAlertPlugin, FileTransport, FunctionPlugin, GENESIS_HASH, HTTPTransport, JSONFormatter, KafkaTransport, Level, Logger, MongoDBTransport, MySQLTransport, NewRelicTransport, PIIRedactPlugin, PagerDutyAlertPlugin, PostgresTransport, PubSubTransport, RabbitMQTransport, RedactPlugin, RedisTransport, SQLiteTransport, SQSTransport, SamplingPlugin, SlackAlertPlugin, TamperEvidentPlugin, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, AppInsightsTransport, BaseQueueTransport, BaseSQLTransport, BatchingTransport, BeaconTransport, CloudLoggingTransport, CloudWatchTransport, CollectingTransport, ConsoleTransport, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_PINO_LEVEL_MAP, DEFAULT_REDACTED_KEYS, DatadogTransport, DispatchQueue, DynamoDBTransport, ElasticsearchTransport, EmailAlertPlugin, FileTransport, FunctionPlugin, GENESIS_HASH, HTTPTransport, JSONFormatter, KafkaTransport, Level, LogQuillPinoDestination, Logger, MongoDBTransport, MySQLTransport, NewRelicTransport, OtelSpanProcessor, PIIRedactPlugin, PagerDutyAlertPlugin, PostgresTransport, PubSubTransport, RabbitMQTransport, RateLimitPlugin, RedactPlugin, RedisTransport, RunPlugin, SQLiteTransport, SQSTransport, SamplingPlugin, SlackAlertPlugin, TamperEvidentPlugin, TraceContextPlugin, Transport, VERSION, bindContext, createRecord, currentContext, defaultResolveActiveOtelTraceId, generateTraceId, getTraceparent, hasFlush, installShutdownHandlers, levelName, parseLevel, parseTraceHeader, setTraceparent, utcTimestamp, withAzureFunction, withCloudFunction, withFlush, withLambda };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map