autotel 2.25.4 → 2.26.0

package/dist/workflow.js

@@ -1,10 +1,10 @@
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-WYP6OOCT.js';
-import './chunk-OPTGXEVN.js';
+export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-RXFZKLRQ.js';
+import './chunk-4PTCDOZY.js';
 import './chunk-B3ZHLLMP.js';
 import './chunk-WD4RP6IV.js';
 import './chunk-S4OFEXLA.js';
 import './chunk-BBBWDIYQ.js';
-import './chunk-MNBAXRVG.js';
+import './chunk-EXOXDI5A.js';
 import './chunk-RUD7KS4R.js';
 import './chunk-XDKK53OL.js';
 import './chunk-WGWSHJ2N.js';

package/dist/yaml-config.d.cts

@@ -1,4 +1,4 @@
-import { A as AutotelConfig } from './init-CIzpC5kZ.cjs';
+import { A as AutotelConfig } from './init-QSj7X6zU.cjs';
 import { SamplingPreset } from './sampling.cjs';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/sdk-node';

package/dist/yaml-config.d.ts

@@ -1,4 +1,4 @@
-import { A as AutotelConfig } from './init-C_PiC_Su.js';
+import { A as AutotelConfig } from './init-FiR_glVc.js';
 import { SamplingPreset } from './sampling.js';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/sdk-node';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "2.25.4",
+  "version": "2.26.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -249,31 +249,31 @@
   "author": "Jag Reehal<jag@jagreehal.com> (https://jagreehal.com)",
   "license": "MIT",
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/api-logs": "^0.213.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.213.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
-    "@opentelemetry/instrumentation": "^0.213.0",
-    "@opentelemetry/resources": "^2.6.0",
-    "@opentelemetry/sdk-logs": "^0.213.0",
-    "@opentelemetry/sdk-metrics": "^2.6.0",
-    "@opentelemetry/sdk-node": "^0.213.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.214.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/instrumentation": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-logs": "^0.214.0",
+    "@opentelemetry/sdk-metrics": "^2.6.1",
+    "@opentelemetry/sdk-node": "^0.214.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
-    "@tanstack/intent": "^0.0.23",
-    "import-in-the-middle": "^3.0.0"
+    "import-in-the-middle": "^3.0.1",
+    "@tanstack/intent": "^0.0.29"
   },
   "peerDependencies": {
-    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
-    "@opentelemetry/exporter-logs-otlp-grpc": "^0.213.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.213.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.213.0",
-    "@opentelemetry/resource-detector-aws": "^2.13.0",
-    "@opentelemetry/resource-detector-container": "^0.8.4",
-    "@opentelemetry/resource-detector-gcp": "^0.48.0",
-    "@opentelemetry/sdk-trace-node": "^2.6.0",
-    "@traceloop/node-server-sdk": "^0.22.8",
+    "@opentelemetry/auto-instrumentations-node": "^0.72.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.214.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.214.0",
+    "@opentelemetry/resource-detector-aws": "^2.14.0",
+    "@opentelemetry/resource-detector-container": "^0.8.5",
+    "@opentelemetry/resource-detector-gcp": "^0.49.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "@traceloop/node-server-sdk": "^0.24.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "yaml": "^2.8.3"
@@ -319,35 +319,35 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@edge-runtime/vm": "^5.0.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
-    "@opentelemetry/context-async-hooks": "^2.6.0",
-    "@opentelemetry/exporter-logs-otlp-grpc": "^0.213.0",
-    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.213.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.213.0",
-    "@opentelemetry/resource-detector-aws": "^2.13.0",
-    "@opentelemetry/resource-detector-container": "^0.8.4",
-    "@opentelemetry/resource-detector-gcp": "^0.48.0",
-    "@opentelemetry/sdk-trace-node": "^2.6.0",
-    "@swc/core": "^1.15.21",
+    "@opentelemetry/auto-instrumentations-node": "^0.72.0",
+    "@opentelemetry/context-async-hooks": "^2.6.1",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.214.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.214.0",
+    "@opentelemetry/resource-detector-aws": "^2.14.0",
+    "@opentelemetry/resource-detector-container": "^0.8.5",
+    "@opentelemetry/resource-detector-gcp": "^0.49.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "@swc/core": "^1.15.24",
     "@total-typescript/ts-reset": "^0.6.1",
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/eslint-config-prettier": "^6.11.3",
-    "@types/node": "^25.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.1",
-    "@typescript-eslint/parser": "^8.57.1",
+    "@types/node": "^25.5.2",
+    "@typescript-eslint/eslint-plugin": "^8.58.1",
+    "@typescript-eslint/parser": "^8.58.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-unicorn": "^63.0.0",
+    "eslint-plugin-unicorn": "^64.0.0",
     "pino": "^10.3.1",
     "prettier": "^3.8.1",
     "rimraf": "^6.1.3",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
     "unplugin-swc": "^1.5.9",
     "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^4.1.0",
-    "vitest-mock-extended": "^3.1.0",
+    "vitest": "^4.1.3",
+    "vitest-mock-extended": "^4.0.0",
     "winston": "^3.19.0",
     "yaml": "^2.8.3"
   },

package/src/devtools.ts

@@ -0,0 +1,60 @@
+export interface AutotelDevtoolsConfig {
+  enabled?: boolean;
+  endpoint?: string;
+  embedded?: boolean;
+  host?: string;
+  port?: number;
+  verbose?: boolean;
+}
+
+export interface ResolvedAutotelDevtoolsConfig {
+  enabled: boolean;
+  endpoint?: string;
+  embedded: boolean;
+  host: string;
+  port: number;
+  verbose: boolean;
+}
+
+const defaultHost = '127.0.0.1';
+const defaultPort = 4318;
+
+export function resolveDevtoolsConfig(
+  config: boolean | AutotelDevtoolsConfig | undefined,
+): ResolvedAutotelDevtoolsConfig {
+  if (!config) {
+    return {
+      enabled: false,
+      endpoint: undefined,
+      embedded: false,
+      host: defaultHost,
+      port: defaultPort,
+      verbose: false,
+    };
+  }
+
+  if (config === true) {
+    return {
+      enabled: true,
+      endpoint: `http://${defaultHost}:${defaultPort}`,
+      embedded: false,
+      host: defaultHost,
+      port: defaultPort,
+      verbose: false,
+    };
+  }
+
+  const enabled = config.enabled ?? true;
+  const host = config.host ?? defaultHost;
+  const port = config.port ?? defaultPort;
+  const endpoint = config.endpoint ?? `http://${host}:${port}`;
+
+  return {
+    enabled,
+    endpoint: enabled ? endpoint : undefined,
+    embedded: enabled && (config.embedded ?? false),
+    host,
+    port,
+    verbose: config.verbose ?? false,
+  };
+}

package/src/hook.mjs

@@ -4,10 +4,10 @@
  * This file re-exports the OpenTelemetry ESM loader hook so users don't need
  * to install @opentelemetry/instrumentation as a direct dependency.
  *
- * Usage (Node 18+):
+ * Usage (Node 22+):
  *   NODE_OPTIONS="--experimental-loader=autotel/hook.mjs --import ./instrumentation.ts" tsx src/index.ts
  *
- * For Node 20.6+, prefer using autotel/register instead which uses the newer
+ * For supported Node versions, prefer using autotel/register instead which uses the newer
  * module.register() API and doesn't require NODE_OPTIONS.
  *
  * @see https://github.com/open-telemetry/opentelemetry-js/blob/main/doc/esm-support.md

package/src/init.customization.test.ts

@@ -115,6 +115,9 @@ async function loadInitWithMocks() {
     getConfig: mod.getConfig,
     getDefaultSampler: mod.getDefaultSampler,
     resolveLogsFlag: mod.resolveLogsFlag,
+    setOptionalRequireForTesting: mod._setOptionalRequireForTesting,
+    resetOptionalRequireForTesting: mod._resetOptionalRequireForTesting,
+    getEmbeddedDevtoolsCloseForTesting: mod._getEmbeddedDevtoolsCloseForTesting,
     sdkInstances,
     traceExporterOptions,
     metricExporterOptions,
@@ -135,6 +138,84 @@ describe('init() customization', () => {
     delete process.env.NODE_ENV;
   });
 
+  it('auto-configures local devtools endpoint and logs when devtools is enabled', async () => {
+    const {
+      init,
+      sdkInstances,
+      traceExporterOptions,
+      metricExporterOptions,
+      logExporterOptions,
+    } = await loadInitWithMocks();
+
+    init({ service: 'devtools-app', devtools: true });
+
+    expect(traceExporterOptions[0]).toMatchObject({
+      url: 'http://127.0.0.1:4318/v1/traces',
+    });
+    expect(metricExporterOptions[0]).toMatchObject({
+      url: 'http://127.0.0.1:4318/v1/metrics',
+    });
+    expect(logExporterOptions[0]).toMatchObject({
+      url: 'http://127.0.0.1:4318/v1/logs',
+    });
+
+    const options = sdkInstances.at(-1)?.options as Record<string, unknown>;
+    expect(options.logRecordProcessors).toBeDefined();
+  });
+
+  it('starts embedded autotel-devtools when requested and installed', async () => {
+    const {
+      init,
+      setOptionalRequireForTesting,
+      getEmbeddedDevtoolsCloseForTesting,
+      traceExporterOptions,
+      logExporterOptions,
+    } = await loadInitWithMocks();
+
+    const close = vi.fn();
+
+    setOptionalRequireForTesting((id: string) => {
+      if (id === 'autotel-devtools') {
+        return {
+          createDevtools: () => ({
+            port: 9876,
+            close,
+          }),
+        } as any;
+      }
+      return undefined;
+    });
+
+    init({
+      service: 'embedded-devtools-app',
+      devtools: { embedded: true, host: '127.0.0.1', port: 0 },
+    });
+
+    expect(traceExporterOptions[0]).toMatchObject({
+      url: 'http://127.0.0.1:9876/v1/traces',
+    });
+    expect(logExporterOptions[0]).toMatchObject({
+      url: 'http://127.0.0.1:9876/v1/logs',
+    });
+    expect(getEmbeddedDevtoolsCloseForTesting()).toBe(close);
+  });
+
+  it('falls back cleanly when embedded devtools is requested but unavailable', async () => {
+    const { init, setOptionalRequireForTesting, traceExporterOptions } =
+      await loadInitWithMocks();
+
+    setOptionalRequireForTesting(() => undefined);
+
+    init({
+      service: 'embedded-devtools-fallback-app',
+      devtools: { embedded: true },
+    });
+
+    expect(traceExporterOptions[0]).toMatchObject({
+      url: 'http://127.0.0.1:4318/v1/traces',
+    });
+  });
+
   it(
     'passes custom instrumentations to the NodeSDK',
     { timeout: 10_000 },

package/src/init.ts

@@ -73,6 +73,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 +298,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[];
 
@@ -1138,6 +1154,7 @@ 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;
 
 /**
  * Resolve metrics flag with env var override support
@@ -1297,6 +1314,11 @@ export function init(cfg: AutotelConfig): void {
     headers: cfg.headers ?? yamlConfig.headers ?? envConfig.headers,
   } as AutotelConfig;
 
+  const devtoolsConfig = resolveDevtoolsConfig(mergedConfig.devtools);
+  if (devtoolsConfig.enabled && mergedConfig.logs === undefined) {
+    mergedConfig.logs = true;
+  }
+
   // Set logger (use provided or default to silent - no spam)
   logger = mergedConfig.logger || silentLogger;
 
@@ -1314,7 +1336,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 +1344,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 +2064,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/shutdown.test.ts

@@ -4,7 +4,12 @@
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { flush, shutdown } from './shutdown';
-import { init } from './init';
+import {
+  init,
+  _getEmbeddedDevtoolsCloseForTesting,
+  _resetOptionalRequireForTesting,
+  _setOptionalRequireForTesting,
+} from './init';
 import { track, getEventQueue } from './track';
 import { EventSubscriber } from './event-subscriber';
 
@@ -37,6 +42,7 @@ describe('shutdown module', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mockAdapter = new MockAdapter();
+    _resetOptionalRequireForTesting();
   });
 
   afterEach(async () => {
@@ -45,6 +51,7 @@ describe('shutdown module', () => {
     if (queue) {
       await queue.flush();
     }
+    _resetOptionalRequireForTesting();
   });
 
   describe('flush()', () => {
@@ -288,6 +295,33 @@ describe('shutdown module', () => {
       // Should not throw even if adapter shutdown fails
       await expect(shutdown()).resolves.toBeUndefined();
     });
+
+    it('should close embedded devtools during shutdown', async () => {
+      const close = vi.fn().mockResolvedValue(undefined);
+      _setOptionalRequireForTesting((id: string) => {
+        if (id === 'autotel-devtools') {
+          return {
+            createDevtools: () => ({
+              port: 4318,
+              close,
+            }),
+          } as any;
+        }
+        return undefined;
+      });
+
+      init({
+        service: 'test-service',
+        devtools: { embedded: true },
+      });
+
+      expect(_getEmbeddedDevtoolsCloseForTesting()).not.toBeNull();
+
+      await shutdown();
+
+      expect(close).toHaveBeenCalledOnce();
+      expect(_getEmbeddedDevtoolsCloseForTesting()).toBeNull();
+    });
   });
 
   describe('Integration', () => {

package/src/shutdown.ts

@@ -2,7 +2,7 @@
  * Graceful shutdown with flush and cleanup
  */
 
-import { getSdk, getLogger } from './init';
+import { getSdk, getLogger, _closeEmbeddedDevtools } from './init';
 import { getEventQueue, resetEventQueue } from './track';
 import { resetEvents } from './event';
 import { resetMetrics } from './metric';
@@ -179,6 +179,8 @@ export async function shutdown(): Promise<void> {
       logger.error({ err }, '[autotel] SDK shutdown failed');
     }
   } finally {
+    await _closeEmbeddedDevtools();
+
     // Clean up singleton Maps and queues to prevent memory leaks
     // This runs even if SDK shutdown fails
     const eventsQueue = getEventQueue();

package/src/test-span-collector.ts

@@ -36,8 +36,11 @@ type SerializableValue =
 /**
  * Portable serialized span for embedding in test metadata.
  * `startTimeMs` is derived from OTel HrTime — epoch-based wall-clock ms in the current SDK.
+ *
+ * Defined as a `type` (not `interface`) so it is assignable to
+ * `Record<string, unknown>` in TypeScript 6+ strict mode.
  */
-export interface SerializedSpan {
+export type SerializedSpan = {
   spanId: string;
   parentSpanId?: string;
   name: string;
@@ -46,7 +49,7 @@ export interface SerializedSpan {
   status: 'ok' | 'error' | 'unset';
   statusMessage?: string;
   attributes?: Record<string, SerializableValue>;
-}
+};
 
 export class TestSpanCollector implements SpanExporter {
   private traces = new Map<string, ReadableSpan[]>();