autotel 2.22.0 → 2.23.0

package/src/request-logger.ts

@@ -0,0 +1,140 @@
+import { trace as otelTrace } from '@opentelemetry/api';
+import type { TraceContext } from './trace-context';
+import { createTraceContext } from './trace-context';
+import { recordStructuredError } from './structured-error';
+import { flattenToAttributes } from './flatten-attributes';
+
+export interface RequestLogger {
+  set(fields: Record<string, unknown>): void;
+  info(message: string, fields?: Record<string, unknown>): void;
+  warn(message: string, fields?: Record<string, unknown>): void;
+  error(error: Error | string, fields?: Record<string, unknown>): void;
+  getContext(): Record<string, unknown>;
+  emitNow(overrides?: Record<string, unknown>): RequestLogSnapshot;
+}
+
+export interface RequestLogSnapshot {
+  timestamp: string;
+  traceId: string;
+  spanId: string;
+  correlationId: string;
+  context: Record<string, unknown>;
+}
+
+export interface RequestLoggerOptions {
+  /** Callback invoked by emitNow() for manual fan-out. */
+  onEmit?: (snapshot: RequestLogSnapshot) => void | Promise<void>;
+}
+
+function resolveContext(ctx?: TraceContext): TraceContext {
+  if (ctx) return ctx;
+
+  const span = otelTrace.getActiveSpan();
+  if (!span) {
+    throw new Error(
+      '[autotel] getRequestLogger() requires an active span. Wrap your handler with trace().',
+    );
+  }
+  return createTraceContext(span);
+}
+
+export function getRequestLogger(
+  ctx?: TraceContext,
+  options?: RequestLoggerOptions,
+): RequestLogger {
+  const activeContext = resolveContext(ctx);
+  let contextState: Record<string, unknown> = {};
+
+  const addLogEvent = (
+    level: 'info' | 'warn' | 'error',
+    message: string,
+    fields?: Record<string, unknown>,
+  ) => {
+    const attrs = fields ? flattenToAttributes(fields) : undefined;
+    activeContext.addEvent(`log.${level}`, {
+      message,
+      ...attrs,
+    });
+  };
+
+  return {
+    set(fields: Record<string, unknown>) {
+      contextState = {
+        ...contextState,
+        ...fields,
+      };
+      activeContext.setAttributes(flattenToAttributes(fields));
+    },
+
+    info(message: string, fields?: Record<string, unknown>) {
+      addLogEvent('info', message, fields);
+      if (fields) {
+        contextState = {
+          ...contextState,
+          ...fields,
+        };
+        activeContext.setAttributes(flattenToAttributes(fields));
+      }
+    },
+
+    warn(message: string, fields?: Record<string, unknown>) {
+      addLogEvent('warn', message, fields);
+      activeContext.setAttribute('autotel.log.level', 'warn');
+      if (fields) {
+        contextState = {
+          ...contextState,
+          ...fields,
+        };
+        activeContext.setAttributes(flattenToAttributes(fields));
+      }
+    },
+
+    error(error: Error | string, fields?: Record<string, unknown>) {
+      const err = typeof error === 'string' ? new Error(error) : error;
+      recordStructuredError(activeContext, err);
+      addLogEvent('error', err.message, fields);
+
+      if (fields) {
+        contextState = {
+          ...contextState,
+          ...fields,
+        };
+        activeContext.setAttributes(flattenToAttributes(fields));
+      }
+      activeContext.setAttribute('autotel.log.level', 'error');
+    },
+
+    getContext() {
+      return { ...contextState };
+    },
+
+    emitNow(overrides?: Record<string, unknown>): RequestLogSnapshot {
+      const mergedContext = {
+        ...contextState,
+        ...(overrides ?? {}),
+      };
+      const flattened = flattenToAttributes(mergedContext);
+      activeContext.setAttributes(flattened);
+
+      const snapshot: RequestLogSnapshot = {
+        timestamp: new Date().toISOString(),
+        traceId: activeContext.traceId,
+        spanId: activeContext.spanId,
+        correlationId: activeContext.correlationId,
+        context: mergedContext,
+      };
+
+      activeContext.addEvent('log.emit.manual', {
+        ...flattened,
+      });
+
+      if (options?.onEmit) {
+        Promise.resolve(options.onEmit(snapshot)).catch((error) => {
+          console.warn('[autotel] request logger onEmit failed:', error);
+        });
+      }
+
+      return snapshot;
+    },
+  };
+}

package/src/structured-error.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createStructuredError,
+  getStructuredErrorAttributes,
+  recordStructuredError,
+} from './structured-error';
+import type { TraceContext } from './trace-context';
+
+describe('structured-error helpers', () => {
+  it('creates an error with structured diagnostic fields', () => {
+    const err = createStructuredError({
+      message: 'Payment failed',
+      why: 'Card declined by issuer',
+      fix: 'Use a different card',
+      link: 'https://docs.example.com/errors/card-declined',
+      code: 'PAYMENT_DECLINED',
+      status: 402,
+      details: { retryable: false, provider: 'stripe' },
+    });
+
+    expect(err.message).toBe('Payment failed');
+    expect(err.why).toBe('Card declined by issuer');
+    expect(err.fix).toBe('Use a different card');
+    expect(err.link).toBe('https://docs.example.com/errors/card-declined');
+    expect(err.code).toBe('PAYMENT_DECLINED');
+    expect(err.status).toBe(402);
+    expect(err.details).toEqual({ retryable: false, provider: 'stripe' });
+  });
+
+  it('extracts canonical attributes for span logging', () => {
+    const err = createStructuredError({
+      message: 'Export failed',
+      why: 'Template not found',
+      fix: 'Upload template and retry',
+      details: { export: { format: 'pdf' } },
+    });
+
+    const attrs = getStructuredErrorAttributes(err);
+    expect(attrs).toMatchObject({
+      'error.type': 'StructuredError',
+      'error.message': 'Export failed',
+      'error.why': 'Template not found',
+      'error.fix': 'Upload template and retry',
+      'error.details.export.format': 'pdf',
+    });
+  });
+
+  it('records structured error onto trace context', () => {
+    const ctx = {
+      recordException: vi.fn(),
+      setStatus: vi.fn(),
+      setAttributes: vi.fn(),
+    } as unknown as TraceContext;
+
+    const err = createStructuredError({
+      message: 'Checkout failed',
+      why: 'Inventory mismatch',
+      fix: 'Re-sync inventory and retry',
+    });
+
+    recordStructuredError(ctx, err);
+
+    expect(ctx.recordException).toHaveBeenCalledWith(err);
+    expect(ctx.setStatus).toHaveBeenCalledWith({
+      code: 2,
+      message: 'Checkout failed',
+    });
+    expect(ctx.setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'error.message': 'Checkout failed',
+        'error.why': 'Inventory mismatch',
+        'error.fix': 'Re-sync inventory and retry',
+      }),
+    );
+  });
+});

package/src/structured-error.ts

@@ -0,0 +1,86 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import type { AttributeValue, TraceContext } from './trace-context';
+import { flattenToAttributes } from './flatten-attributes';
+
+export interface StructuredErrorInput {
+  message: string;
+  why?: string;
+  fix?: string;
+  link?: string;
+  code?: string | number;
+  status?: number;
+  cause?: unknown;
+  details?: Record<string, unknown>;
+  name?: string;
+}
+
+export interface StructuredError extends Error {
+  why?: string;
+  fix?: string;
+  link?: string;
+  code?: string | number;
+  status?: number;
+  details?: Record<string, unknown>;
+}
+
+export function createStructuredError(
+  input: StructuredErrorInput,
+): StructuredError {
+  const error = new Error(input.message, {
+    cause: input.cause,
+  }) as StructuredError;
+
+  error.name = input.name ?? 'StructuredError';
+  if (input.why !== undefined) error.why = input.why;
+  if (input.fix !== undefined) error.fix = input.fix;
+  if (input.link !== undefined) error.link = input.link;
+  if (input.code !== undefined) error.code = input.code;
+  if (input.status !== undefined) error.status = input.status;
+  if (input.details !== undefined) error.details = input.details;
+
+  return error;
+}
+
+export function getStructuredErrorAttributes(
+  error: Error,
+): Record<string, AttributeValue> {
+  const structured = error as StructuredError;
+  const attributes: Record<string, AttributeValue> = {
+    'error.type': error.name || 'Error',
+    'error.message': error.message,
+  };
+
+  if (error.stack) attributes['error.stack'] = error.stack;
+  if (structured.why) attributes['error.why'] = structured.why;
+  if (structured.fix) attributes['error.fix'] = structured.fix;
+  if (structured.link) attributes['error.link'] = structured.link;
+  if (structured.code !== undefined) {
+    attributes['error.code'] =
+      typeof structured.code === 'string'
+        ? structured.code
+        : String(structured.code);
+  }
+  if (structured.status !== undefined) {
+    attributes['error.status'] = structured.status;
+  }
+  if (structured.details) {
+    Object.assign(
+      attributes,
+      flattenToAttributes(structured.details, 'error.details'),
+    );
+  }
+
+  return attributes;
+}
+
+export function recordStructuredError(
+  ctx: Pick<TraceContext, 'recordException' | 'setAttributes' | 'setStatus'>,
+  error: Error,
+): void {
+  ctx.recordException(error);
+  ctx.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error.message,
+  });
+  ctx.setAttributes(getStructuredErrorAttributes(error));
+}

package/dist/chunk-2RQDNGV3.js

@@ -1,126 +0,0 @@
-import { logs, SeverityNumber } from '@opentelemetry/api-logs';
-
-// src/processors/canonical-log-line-processor.ts
-var CanonicalLogLineProcessor = class {
-  logger;
-  rootSpansOnly;
-  minLevel;
-  messageFormat;
-  includeResourceAttributes;
-  attributeRedactor;
-  getOTelLogger = null;
-  constructor(options = {}) {
-    this.logger = options.logger;
-    this.rootSpansOnly = options.rootSpansOnly ?? false;
-    this.minLevel = options.minLevel ?? "info";
-    this.messageFormat = options.messageFormat ?? ((span) => `[${span.name}] Request completed`);
-    this.includeResourceAttributes = options.includeResourceAttributes ?? true;
-    this.attributeRedactor = options.attributeRedactor;
-    if (!this.logger) {
-      this.getOTelLogger = () => logs.getLogger("autotel.canonical-log-line");
-    }
-  }
-  onStart() {
-  }
-  onEnd(span) {
-    if (this.rootSpansOnly && span.parentSpanContext?.spanId && !span.parentSpanContext.isRemote) {
-      return;
-    }
-    const level = this.getLogLevel(span);
-    if (!this.shouldLog(level)) {
-      return;
-    }
-    const canonicalLogLine = this.buildCanonicalLogLine(span);
-    if (this.logger) {
-      this.emitViaLogger(level, span, canonicalLogLine);
-    } else if (this.getOTelLogger) {
-      const otelLogger = this.getOTelLogger();
-      this.emitViaOTel(level, span, canonicalLogLine, otelLogger);
-    }
-  }
-  buildCanonicalLogLine(span) {
-    const durationMs = span.duration[0] * 1e3 + span.duration[1] / 1e6;
-    const timestamp = new Date(
-      span.startTime[0] * 1e3 + span.startTime[1] / 1e6
-    ).toISOString();
-    const canonicalLogLine = {};
-    const attributes = this.redactAttributes(span.attributes);
-    Object.assign(canonicalLogLine, attributes);
-    if (this.includeResourceAttributes) {
-      const resourceAttrs = this.redactAttributes(
-        span.resource.attributes
-      );
-      Object.assign(canonicalLogLine, resourceAttrs);
-    }
-    canonicalLogLine.operation = span.name;
-    canonicalLogLine.traceId = span.spanContext().traceId;
-    canonicalLogLine.spanId = span.spanContext().spanId;
-    canonicalLogLine.correlationId = span.spanContext().traceId.slice(0, 16);
-    canonicalLogLine.duration_ms = Math.round(durationMs * 100) / 100;
-    canonicalLogLine.status_code = span.status.code;
-    canonicalLogLine.status_message = span.status.message || void 0;
-    canonicalLogLine.timestamp = timestamp;
-    return canonicalLogLine;
-  }
-  /**
-   * Apply attribute redaction if a redactor is configured
-   */
-  redactAttributes(attributes) {
-    if (!this.attributeRedactor) {
-      return { ...attributes };
-    }
-    const redacted = {};
-    for (const [key, value] of Object.entries(attributes)) {
-      if (value !== void 0) {
-        redacted[key] = this.attributeRedactor(key, value);
-      }
-    }
-    return redacted;
-  }
-  emitViaLogger(level, span, canonicalLogLine) {
-    const message = this.messageFormat(span);
-    this.logger[level](canonicalLogLine, message);
-  }
-  emitViaOTel(level, span, canonicalLogLine, otelLogger) {
-    const message = this.messageFormat(span);
-    const otelAttributes = {};
-    for (const [key, value] of Object.entries(canonicalLogLine)) {
-      if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-        otelAttributes[key] = value;
-      } else if (value !== null && value !== void 0) {
-        otelAttributes[key] = String(value);
-      }
-    }
-    otelLogger.emit({
-      severityNumber: this.getSeverityNumber(level),
-      severityText: level.toUpperCase(),
-      body: message,
-      attributes: otelAttributes
-    });
-  }
-  getLogLevel(span) {
-    if (span.status.code === 2) return "error";
-    return "info";
-  }
-  shouldLog(level) {
-    const levels = ["debug", "info", "warn", "error"];
-    return levels.indexOf(level) >= levels.indexOf(this.minLevel);
-  }
-  getSeverityNumber(level) {
-    const mapping = {
-      debug: SeverityNumber.DEBUG,
-      info: SeverityNumber.INFO,
-      warn: SeverityNumber.WARN,
-      error: SeverityNumber.ERROR
-    };
-    return mapping[level] ?? SeverityNumber.INFO;
-  }
-  async forceFlush() {
-  }
-  async shutdown() {
-  }
-};
-
-export { CanonicalLogLineProcessor };
-//# sourceMappingURL=chunk-2RQDNGV3.js.map
-//# sourceMappingURL=chunk-2RQDNGV3.js.map

package/dist/chunk-2RQDNGV3.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/processors/canonical-log-line-processor.ts"],"names":[],"mappings":"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","file":"chunk-2RQDNGV3.js","sourcesContent":["/**\n * Canonical Log Line Processor\n *\n * Automatically emits spans as canonical log lines (wide events) when they end.\n * Implements canonical log line\" pattern: one comprehensive\n * event per request with all context.\n *\n * When a span ends, this processor creates a log record with ALL span attributes,\n * making the span itself the canonical log line that can be queried like structured data.\n *\n * @example\n * ```typescript\n * import { init } from 'autotel';\n *\n * init({\n *   service: 'my-app',\n *   canonicalLogLines: {\n *     enabled: true,\n *     rootSpansOnly: true, // One canonical log line per request\n *   },\n * });\n * ```\n */\n\nimport type {\n  SpanProcessor,\n  ReadableSpan,\n} from '@opentelemetry/sdk-trace-base';\nimport type { Attributes, AttributeValue } from '@opentelemetry/api';\nimport { logs, SeverityNumber } from '@opentelemetry/api-logs';\nimport type { Logger } from '../logger';\n\n/**\n * Function to redact sensitive attribute values\n */\nexport type AttributeRedactorFn = (\n  key: string,\n  value: AttributeValue,\n) => AttributeValue;\n\nexport interface CanonicalLogLineOptions {\n  /** Logger to use for emitting canonical log lines (defaults to OTel Logs API) */\n  logger?: Logger;\n  /** Only emit canonical log lines for root spans (default: false) */\n  rootSpansOnly?: boolean;\n  /** Minimum log level for canonical log lines (default: 'info') */\n  minLevel?: 'debug' | 'info' | 'warn' | 'error';\n  /** Custom message format (default: uses span name) */\n  messageFormat?: (span: ReadableSpan) => string;\n  /** Whether to include resource attributes (default: true) */\n  includeResourceAttributes?: boolean;\n  /**\n   * Attribute redactor function to apply before logging.\n   * This ensures sensitive data is redacted in canonical log lines,\n   * matching the behavior of attributeRedactor in init().\n   */\n  attributeRedactor?: AttributeRedactorFn;\n}\n\n/**\n * Span processor that automatically emits spans as canonical log lines\n *\n * When a span ends, this processor creates a log record with ALL span attributes.\n * This implements the \"canonical log line\" pattern: one comprehensive event\n * per request with all context, queryable as structured data.\n *\n * **Key Benefits:**\n * - One log line per request with all context (wide event)\n * - High-cardinality, high-dimensionality data for powerful queries\n * - Automatic - no manual logging needed\n * - Works with any logger or OTel Logs API\n *\n * @example Basic usage\n * ```typescript\n * import { init } from 'autotel';\n *\n * init({\n *   service: 'checkout-api',\n *   canonicalLogLines: {\n *     enabled: true,\n *     rootSpansOnly: true, // One canonical log line per request\n *   },\n * });\n * ```\n *\n * @example With custom logger\n * ```typescript\n * import pino from 'pino';\n * import { init } from 'autotel';\n *\n * const logger = pino();\n * init({\n *   service: 'my-app',\n *   logger,\n *   canonicalLogLines: {\n *     enabled: true,\n *     logger, // Use Pino for canonical log lines\n *     rootSpansOnly: true,\n *   },\n * });\n * ```\n *\n * @example Custom message format\n * ```typescript\n * init({\n *   service: 'my-app',\n *   canonicalLogLines: {\n *     enabled: true,\n *     messageFormat: (span) => {\n *       const status = span.status.code === 2 ? 'ERROR' : 'SUCCESS';\n *       return `${span.name} [${status}]`;\n *     },\n *   },\n * });\n * ```\n */\nexport class CanonicalLogLineProcessor implements SpanProcessor {\n  private logger?: Logger;\n  private rootSpansOnly: boolean;\n  private minLevel: 'debug' | 'info' | 'warn' | 'error';\n  private messageFormat: (span: ReadableSpan) => string;\n  private includeResourceAttributes: boolean;\n  private attributeRedactor?: AttributeRedactorFn;\n  private getOTelLogger: (() => ReturnType<typeof logs.getLogger>) | null =\n    null;\n\n  constructor(options: CanonicalLogLineOptions = {}) {\n    this.logger = options.logger;\n    this.rootSpansOnly = options.rootSpansOnly ?? false;\n    this.minLevel = options.minLevel ?? 'info';\n    this.messageFormat =\n      options.messageFormat ?? ((span) => `[${span.name}] Request completed`);\n    this.includeResourceAttributes = options.includeResourceAttributes ?? true;\n    this.attributeRedactor = options.attributeRedactor;\n\n    // Lazy-load OTel logger if no custom logger provided\n    // We can't initialize it here because logs API might not be ready\n    if (!this.logger) {\n      this.getOTelLogger = () => logs.getLogger('autotel.canonical-log-line');\n    }\n  }\n\n  onStart(): void {\n    // No-op - we only care about span end\n  }\n\n  onEnd(span: ReadableSpan): void {\n    // Skip if rootSpansOnly and this span has a LOCAL parent (same service)\n    // We still emit for spans with REMOTE parents (from distributed tracing)\n    // because those are the entry points (\"roots\") for THIS service.\n    // Check if parent is remote (from another service via traceparent/b3 headers)\n    // If isRemote is true, this span is a service entry point and should emit\n    // If isRemote is false/undefined, this is a local child span and should be skipped\n    if (\n      this.rootSpansOnly &&\n      span.parentSpanContext?.spanId &&\n      !span.parentSpanContext.isRemote\n    ) {\n      return;\n    }\n\n    // Determine log level from span status\n    const level = this.getLogLevel(span);\n    if (!this.shouldLog(level)) {\n      return;\n    }\n\n    // Build canonical log line with ALL span attributes\n    const canonicalLogLine = this.buildCanonicalLogLine(span);\n\n    // Emit via logger or OTel Logs API\n    if (this.logger) {\n      this.emitViaLogger(level, span, canonicalLogLine);\n    } else if (this.getOTelLogger) {\n      const otelLogger = this.getOTelLogger();\n      this.emitViaOTel(level, span, canonicalLogLine, otelLogger);\n    }\n  }\n\n  private buildCanonicalLogLine(span: ReadableSpan): Record<string, unknown> {\n    // Convert duration from [seconds, nanoseconds] to milliseconds\n    // duration[0] is seconds, duration[1] is nanoseconds (fractional part)\n    const durationMs = span.duration[0] * 1000 + span.duration[1] / 1_000_000;\n\n    // Convert start time from [seconds, nanoseconds] to ISO string\n    // startTime[0] is seconds, startTime[1] is nanoseconds (fractional part)\n    const timestamp = new Date(\n      span.startTime[0] * 1000 + span.startTime[1] / 1_000_000,\n    ).toISOString();\n\n    // Start with span attributes (potentially redacted)\n    // We add these FIRST so core metadata fields below can't be overwritten\n    const canonicalLogLine: Record<string, unknown> = {};\n\n    // Apply redaction to span attributes if redactor is configured\n    const attributes = this.redactAttributes(span.attributes);\n    Object.assign(canonicalLogLine, attributes);\n\n    // Include resource attributes (service-level context), also redacted\n    if (this.includeResourceAttributes) {\n      const resourceAttrs = this.redactAttributes(\n        span.resource.attributes as Attributes,\n      );\n      Object.assign(canonicalLogLine, resourceAttrs);\n    }\n\n    // Set core metadata fields LAST to prevent span attributes from overwriting them\n    // (e.g., if a span has an attribute named \"traceId\" or \"timestamp\")\n    canonicalLogLine.operation = span.name;\n    canonicalLogLine.traceId = span.spanContext().traceId;\n    canonicalLogLine.spanId = span.spanContext().spanId;\n    canonicalLogLine.correlationId = span.spanContext().traceId.slice(0, 16);\n    canonicalLogLine.duration_ms = Math.round(durationMs * 100) / 100;\n    canonicalLogLine.status_code = span.status.code;\n    canonicalLogLine.status_message = span.status.message || undefined;\n    canonicalLogLine.timestamp = timestamp;\n\n    return canonicalLogLine;\n  }\n\n  /**\n   * Apply attribute redaction if a redactor is configured\n   */\n  private redactAttributes(attributes: Attributes): Record<string, unknown> {\n    if (!this.attributeRedactor) {\n      // No redaction configured, return as-is\n      return { ...attributes };\n    }\n\n    const redacted: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(attributes)) {\n      if (value !== undefined) {\n        redacted[key] = this.attributeRedactor(key, value);\n      }\n    }\n    return redacted;\n  }\n\n  private emitViaLogger(\n    level: 'debug' | 'info' | 'warn' | 'error',\n    span: ReadableSpan,\n    canonicalLogLine: Record<string, unknown>,\n  ): void {\n    const message = this.messageFormat(span);\n    // Pino-compatible signature: (extra, message)\n    this.logger![level](canonicalLogLine, message);\n  }\n\n  private emitViaOTel(\n    level: 'debug' | 'info' | 'warn' | 'error',\n    span: ReadableSpan,\n    canonicalLogLine: Record<string, unknown>,\n    otelLogger: ReturnType<typeof logs.getLogger>,\n  ): void {\n    const message = this.messageFormat(span);\n    // Convert unknown values to strings for OTel Logs API compatibility\n    const otelAttributes: Record<string, string | number | boolean> = {};\n    for (const [key, value] of Object.entries(canonicalLogLine)) {\n      if (\n        typeof value === 'string' ||\n        typeof value === 'number' ||\n        typeof value === 'boolean'\n      ) {\n        otelAttributes[key] = value;\n      } else if (value !== null && value !== undefined) {\n        otelAttributes[key] = String(value);\n      }\n    }\n    otelLogger.emit({\n      severityNumber: this.getSeverityNumber(level),\n      severityText: level.toUpperCase(),\n      body: message,\n      attributes: otelAttributes,\n    });\n  }\n\n  private getLogLevel(span: ReadableSpan): 'debug' | 'info' | 'warn' | 'error' {\n    // ERROR status code is 2\n    if (span.status.code === 2) return 'error';\n\n    // Could check for slow spans, etc. in the future\n    // For now, default to info\n    return 'info';\n  }\n\n  private shouldLog(level: string): boolean {\n    const levels = ['debug', 'info', 'warn', 'error'];\n    return levels.indexOf(level) >= levels.indexOf(this.minLevel);\n  }\n\n  private getSeverityNumber(level: string): SeverityNumber {\n    const mapping: Record<string, SeverityNumber> = {\n      debug: SeverityNumber.DEBUG,\n      info: SeverityNumber.INFO,\n      warn: SeverityNumber.WARN,\n      error: SeverityNumber.ERROR,\n    };\n    return mapping[level] ?? SeverityNumber.INFO;\n  }\n\n  async forceFlush(): Promise<void> {\n    // No-op - logging is fire-and-forget\n  }\n\n  async shutdown(): Promise<void> {\n    // No-op - logging is fire-and-forget\n  }\n}\n"]}