autotel 2.25.5 → 2.26.1

package/src/init.ts

@@ -60,6 +60,7 @@ import {
 } from './span-name-normalizer';
 import {
   AttributeRedactingProcessor,
+  normalizeAttributeRedactorConfig,
   type AttributeRedactorConfig,
   type AttributeRedactorPreset,
 } from './attribute-redacting-processor';
@@ -73,6 +74,7 @@ import {
   type CanonicalLogLineOptions,
 } from './processors/canonical-log-line-processor';
 import type { EventsConfig } from './events-config';
+import { resolveDevtoolsConfig, type AutotelDevtoolsConfig } from './devtools';
 
 /**
  * Silent logger (no-op) - used as default when user doesn't provide one.
@@ -297,6 +299,21 @@ export interface AutotelConfig {
   /** Service name (required) */
   service: string;
 
+  /**
+   * Local developer UX for autotel-devtools.
+   *
+   * - `true`: send traces, metrics, and logs to `http://127.0.0.1:4318`
+   * - `{ embedded: true }`: attempt to start `autotel-devtools` automatically
+   *
+   * When enabled:
+   * - `endpoint` defaults to the local devtools URL
+   * - `logs` default to `true` unless explicitly set
+   *
+   * This keeps production config unchanged while making local debugging
+   * effectively zero-config.
+   */
+  devtools?: boolean | AutotelDevtoolsConfig;
+
   /** Event subscribers - bring your own (PostHog, Mixpanel, etc.) */
   subscribers?: EventSubscriber[];
 
@@ -1126,10 +1143,28 @@ export interface AutotelConfig {
      */
     pretty?: boolean;
   };
+
+  /**
+   * Suppress console output while keeping OTel exporters running.
+   * Useful for platforms like GCP Cloud Run / AWS Lambda where stdout
+   * is managed externally by the platform's log collector.
+   *
+   * @default false
+   */
+  silent?: boolean;
+
+  /**
+   * Minimum log level for internal autotel diagnostic messages.
+   * Messages below this level are dropped before processing.
+   *
+   * @default 'info'
+   */
+  minLevel?: 'debug' | 'info' | 'warn' | 'error';
 }
 
 // Internal state
 let initialized = false;
+let locked = false;
 let config: AutotelConfig | null = null;
 let sdk: NodeSDK | null = null;
 let warnedOnce = false;
@@ -1138,6 +1173,86 @@ let validationConfig: Partial<ValidationConfig> | null = null;
 let eventsConfig: EventsConfig | null = null;
 let _stringRedactor: StringRedactor | null = null;
 let _optionalRequire: typeof safeRequire = safeRequire;
+let _devtoolsClose: (() => Promise<void> | void) | null = null;
+
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const;
+type LogLevelKey = keyof typeof LOG_LEVELS;
+
+/**
+ * Lock the logger to prevent further `init()` calls.
+ * Use this when framework plugins set up instrumentation and you want
+ * to prevent accidental re-initialization from user code.
+ */
+export function lockLogger(): void {
+  locked = true;
+}
+
+/**
+ * Check if the logger has been locked.
+ */
+export function isLoggerLocked(): boolean {
+  return locked;
+}
+
+function createSilentLogger(): Logger {
+  return {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  };
+}
+
+function wrapLogger(
+  base: Logger,
+  silent: boolean,
+  minLevel: LogLevelKey,
+): Logger {
+  if (silent) return createSilentLogger();
+  const threshold = LOG_LEVELS[minLevel];
+  const wrap = (fn: Logger['info'], level: LogLevelKey): Logger['info'] => {
+    if (LOG_LEVELS[level] < threshold) {
+      return (() => {}) as Logger['info'];
+    }
+    return ((...args: Parameters<Logger['info']>) =>
+      fn(...args)) as Logger['info'];
+  };
+  return {
+    debug: wrap(base.debug, 'debug'),
+    info: wrap(base.info, 'info'),
+    warn: wrap(base.warn, 'warn'),
+    error: wrap(base.error, 'error'),
+  };
+}
+
+function detectEnvironmentAttributes(): Record<string, string> {
+  const attrs: Record<string, string> = {};
+
+  const commitSha =
+    process.env.COMMIT_SHA ||
+    process.env.GITHUB_SHA ||
+    process.env.VERCEL_GIT_COMMIT_SHA ||
+    process.env.CF_PAGES_COMMIT_SHA ||
+    process.env.AWS_CODEPIPELINE_EXECUTION_ID;
+  if (commitSha) attrs['service.commit.sha'] = commitSha;
+
+  const region =
+    process.env.VERCEL_REGION ||
+    process.env.AWS_REGION ||
+    process.env.AWS_DEFAULT_REGION ||
+    process.env.FLY_REGION ||
+    process.env.CF_REGION ||
+    process.env.GOOGLE_CLOUD_REGION;
+  if (region) attrs['service.region'] = region;
+
+  const version =
+    process.env.APP_VERSION ||
+    process.env.HEROKU_RELEASE_VERSION ||
+    process.env.VERCEL_GIT_COMMIT_REF;
+  if (version) attrs['service.deploy.version'] = version;
+
+  return attrs;
+}
 
 /**
  * Resolve metrics flag with env var override support
@@ -1278,6 +1393,10 @@ function normalizeOtlpHeaders(
  */
 
 export function init(cfg: AutotelConfig): void {
+  if (locked) {
+    return;
+  }
+
   // Resolve configs in priority order: explicit > yaml > env > defaults
   const envConfig = resolveConfigFromEnv();
   const yamlConfig = loadYamlConfig() ?? {};
@@ -1291,14 +1410,32 @@ export function init(cfg: AutotelConfig): void {
     resourceAttributes: {
       ...envConfig.resourceAttributes,
       ...yamlConfig.resourceAttributes,
+      ...detectEnvironmentAttributes(),
       ...cfg.resourceAttributes,
     },
     // Handle headers merge (can be string or object)
     headers: cfg.headers ?? yamlConfig.headers ?? envConfig.headers,
   } as AutotelConfig;
 
-  // Set logger (use provided or default to silent - no spam)
-  logger = mergedConfig.logger || silentLogger;
+  if (mergedConfig.attributeRedactor !== undefined) {
+    const normalizedRedactor = normalizeAttributeRedactorConfig(
+      mergedConfig.attributeRedactor,
+    );
+    if (!normalizedRedactor) {
+      throw new Error('Invalid attributeRedactor config');
+    }
+    mergedConfig.attributeRedactor = normalizedRedactor;
+  }
+
+  const devtoolsConfig = resolveDevtoolsConfig(mergedConfig.devtools);
+  if (devtoolsConfig.enabled && mergedConfig.logs === undefined) {
+    mergedConfig.logs = true;
+  }
+
+  const silent = mergedConfig.silent ?? false;
+  const minLevel = mergedConfig.minLevel ?? 'info';
+  const baseLogger = mergedConfig.logger || silentLogger;
+  logger = wrapLogger(baseLogger, silent, minLevel);
 
   // Warn if re-initializing (same behavior in all environments)
   if (initialized) {
@@ -1314,7 +1451,7 @@ export function init(cfg: AutotelConfig): void {
 
   // Initialize OpenTelemetry
   // Only use endpoint if explicitly configured (no default fallback)
-  const endpoint = mergedConfig.endpoint;
+  let endpoint = mergedConfig.endpoint ?? devtoolsConfig.endpoint;
   const otlpHeaders = normalizeOtlpHeaders(mergedConfig.headers);
   const version = mergedConfig.version || detectVersion();
   const environment =
@@ -1322,6 +1459,35 @@ export function init(cfg: AutotelConfig): void {
   const metricsEnabled = resolveMetricsFlag(mergedConfig.metrics);
   const logsEnabled = resolveLogsFlag(mergedConfig.logs);
 
+  if (devtoolsConfig.enabled && devtoolsConfig.embedded) {
+    const devtoolsModule = _optionalRequire<{
+      createDevtools?: (options?: {
+        port?: number;
+        host?: string;
+        verbose?: boolean;
+      }) => { port: number; close: () => Promise<void> | void };
+    }>('autotel-devtools');
+
+    if (devtoolsModule?.createDevtools) {
+      const devtoolsInstance = devtoolsModule.createDevtools({
+        port: devtoolsConfig.port,
+        host: devtoolsConfig.host,
+        verbose: devtoolsConfig.verbose,
+      });
+      _devtoolsClose = devtoolsInstance.close;
+      endpoint = `http://${devtoolsConfig.host}:${devtoolsInstance.port}`;
+      logger.info(
+        {},
+        `[autotel] autotel-devtools embedded server started at ${endpoint}`,
+      );
+    } else {
+      logger.warn(
+        {},
+        '[autotel] devtools.embedded requested but autotel-devtools is not installed. Falling back to endpoint-only mode.',
+      );
+    }
+  }
+
   // Detect hostname for proper Datadog correlation and Service Catalog discovery
   const hostname = detectHostname();
 
@@ -2013,6 +2179,25 @@ export function _resetOptionalRequireForTesting(): void {
   _optionalRequire = safeRequire;
 }
 
+/**
+ * @internal Close embedded devtools if running.
+ */
+export async function _closeEmbeddedDevtools(): Promise<void> {
+  if (_devtoolsClose) {
+    await _devtoolsClose();
+    _devtoolsClose = null;
+  }
+}
+
+/**
+ * @internal Get embedded devtools close handle.
+ */
+export function _getEmbeddedDevtoolsCloseForTesting():
+  | (() => Promise<void> | void)
+  | null {
+  return _devtoolsClose;
+}
+
 /**
  * Get SDK instance (for shutdown)
  */

package/src/request-logger.test.ts

@@ -1,4 +1,5 @@
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { trace as otelTrace } from '@opentelemetry/api';
 import { getRequestLogger, runWithRequestContext } from './request-logger';
 import type { TraceContext } from './trace-context';
 
@@ -23,6 +24,238 @@ function createMockContext(): TraceContext {
   } as unknown as TraceContext;
 }
 
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('post-emit warnings', () => {
+  let ctx: TraceContext;
+  let log: ReturnType<typeof getRequestLogger>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    ctx = createMockContext();
+    log = getRequestLogger(ctx);
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it('warns when set() is called after emitNow()', () => {
+    log.emitNow();
+    log.set({ dropped: 'value' });
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[autotel] log.set() called after the wide event was emitted',
+      ),
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Keys dropped: dropped'),
+    );
+  });
+
+  it('warns when info() is called after emitNow()', () => {
+    log.emitNow();
+    log.info('after emit', { extra: 'data' });
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[autotel] log.info() called after the wide event was emitted',
+      ),
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Keys dropped: message, extra'),
+    );
+  });
+
+  it('warns when warn() is called after emitNow()', () => {
+    log.emitNow();
+    log.warn('after emit', { extra: 'data' });
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[autotel] log.warn() called after the wide event was emitted',
+      ),
+    );
+  });
+
+  it('warns when error() is called after emitNow()', () => {
+    log.emitNow();
+    log.error(new Error('after emit'), { step: 'cleanup' });
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[autotel] log.error() called after the wide event was emitted',
+      ),
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Keys dropped: step, error'),
+    );
+  });
+
+  it('warns on duplicate emitNow()', () => {
+    const first = log.emitNow();
+    const second = log.emitNow();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[autotel] log.emitNow() called after the wide event was emitted',
+      ),
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Ignoring duplicate emit'),
+    );
+    expect(second).toBe(first);
+  });
+
+  it('does not warn when calls are made before emitNow()', () => {
+    log.set({ user: { id: 'u1' } });
+    log.info('step', { stage: 'payment' });
+    log.warn('slow');
+    log.error(new Error('fail'));
+    log.emitNow();
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('array concatenation in set()', () => {
+  let ctx: TraceContext;
+  let log: ReturnType<typeof getRequestLogger>;
+
+  beforeEach(() => {
+    ctx = createMockContext();
+    log = getRequestLogger(ctx);
+  });
+
+  it('concatenates arrays when both values are arrays', () => {
+    log.set({ tags: ['initial', 'setup'] });
+    log.set({ tags: ['payment', 'complete'] });
+
+    expect(log.getContext()).toEqual({
+      tags: ['initial', 'setup', 'payment', 'complete'],
+    });
+  });
+
+  it('replaces array with non-array value', () => {
+    log.set({ tags: ['a', 'b'] });
+    log.set({ tags: 'single' });
+
+    expect(log.getContext()).toEqual({
+      tags: 'single',
+    });
+  });
+
+  it('replaces non-array with array', () => {
+    log.set({ tags: 'single' });
+    log.set({ tags: ['a', 'b'] });
+
+    expect(log.getContext()).toEqual({
+      tags: ['a', 'b'],
+    });
+  });
+
+  it('deep merges objects while concatenating nested arrays', () => {
+    log.set({
+      user: { id: 'u1', roles: ['admin'] },
+    });
+    log.set({
+      user: { name: 'Alice', roles: ['editor'] },
+    });
+
+    expect(log.getContext()).toEqual({
+      user: {
+        id: 'u1',
+        name: 'Alice',
+        roles: ['admin', 'editor'],
+      },
+    });
+  });
+});
+
+describe('log.fork()', () => {
+  let ctx: TraceContext;
+  let log: ReturnType<typeof getRequestLogger>;
+
+  beforeEach(() => {
+    ctx = createMockContext();
+    log = getRequestLogger(ctx);
+  });
+
+  it('throws when parent has no correlationId', () => {
+    const noCorrCtx = createMockContext();
+    (noCorrCtx as Record<string, unknown>).correlationId = '';
+    const noCorrLog = getRequestLogger(noCorrCtx);
+
+    expect(() => noCorrLog.fork('test', () => {})).toThrow(
+      '[autotel] log.fork() requires the parent logger to have a correlationId',
+    );
+  });
+
+  it('fork method exists on the logger interface', () => {
+    expect(typeof log.fork).toBe('function');
+  });
+
+  it('uses an isolated child span context for forked work', async () => {
+    const childSpan = {
+      spanContext: () => ({
+        traceId: 'a'.repeat(32),
+        spanId: 'b'.repeat(16),
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      addEvent: vi.fn(),
+      addLink: vi.fn(),
+      addLinks: vi.fn(),
+      updateName: vi.fn(),
+      isRecording: vi.fn(() => true),
+      end: vi.fn(),
+    };
+
+    const tracer = {
+      startActiveSpan: (
+        _name: string,
+        cb: (span: typeof childSpan) => void,
+      ) => {
+        cb(childSpan);
+      },
+    };
+
+    const tracerSpy = vi
+      .spyOn(otelTrace, 'getTracer')
+      .mockReturnValue(
+        tracer as unknown as ReturnType<typeof otelTrace.getTracer>,
+      );
+
+    log.fork('background-work', async () => {
+      const childLog = getRequestLogger();
+      childLog.info('running child task', { phase: 'upload' });
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(tracerSpy).toHaveBeenCalledWith('autotel.request-logger');
+    expect(childSpan.setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        operation: 'background-work',
+        _parentCorrelationId: 'corr-id',
+      }),
+    );
+    expect(childSpan.addEvent).toHaveBeenCalledWith(
+      'log.emit.manual',
+      expect.any(Object),
+    );
+    expect(ctx.setAttributes).not.toHaveBeenCalled();
+    expect(childSpan.end).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('getRequestLogger', () => {
   it('sets flattened fields onto active span context', () => {
     const ctx = createMockContext();
@@ -134,4 +367,36 @@ describe('getRequestLogger', () => {
       });
     });
   });
+
+  it('resolves context from the active OTel span when no args and no ALS context', () => {
+    const activeSpan = {
+      spanContext: () => ({
+        traceId: 'c'.repeat(32),
+        spanId: 'd'.repeat(16),
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      addEvent: vi.fn(),
+      addLink: vi.fn(),
+      addLinks: vi.fn(),
+      updateName: vi.fn(),
+      isRecording: vi.fn(() => true),
+    };
+
+    const spanSpy = vi
+      .spyOn(otelTrace, 'getActiveSpan')
+      .mockReturnValue(
+        activeSpan as unknown as ReturnType<typeof otelTrace.getActiveSpan>,
+      );
+
+    const log = getRequestLogger();
+    log.set({ order: { id: 'o-1' } });
+
+    expect(spanSpy).toHaveBeenCalled();
+    expect(activeSpan.setAttributes).toHaveBeenCalledWith({
+      'order.id': 'o-1',
+    });
+  });
 });