autotel 4.0.0 → 4.1.0

package/skills/review-otel-patterns/SKILL.md

@@ -74,7 +74,7 @@ export function register() {
   if (process.env.NEXT_RUNTIME === 'nodejs') {
     init({
       service: 'my-app',
-      exporter: { url: process.env.OTLP_ENDPOINT! },
+      endpoint: process.env.OTLP_ENDPOINT!,
       sampling: { rates: { server: 25, client: 5 } },
       attributeRedactor: 'default',
     });
@@ -201,7 +201,7 @@ export const handler = withLambda(async (event) => {
 ```typescript
 import { init, trace } from 'autotel';
 
-init({ service: 'my-worker', exporter: { url: process.env.OTLP_ENDPOINT! } });
+init({ service: 'my-worker', endpoint: process.env.OTLP_ENDPOINT! });
 
 const processJob = trace(async (job: Job) => {
   // span auto-named after the function
@@ -219,7 +219,8 @@ All options work with `init()`, framework adapters, and `wrapModule` / `defineWo
 | Option                                  | Type                                                            | Default           | Description                                                     |
 | --------------------------------------- | --------------------------------------------------------------- | ----------------- | --------------------------------------------------------------- |
 | `service` / `service.name`              | `string`                                                        | `'app'`           | Service name in `service.name` resource attribute               |
-| `exporter`                              | `{ url, headers?, protocol? }`                                  | —                 | OTLP HTTP/JSON or HTTP/protobuf endpoint                        |
+| `endpoint`                              | `string`                                                        | —                 | Single OTLP destination shorthand                               |
+| `destinations`                          | `Array<{ endpoint, headers?, protocol?, signals? }>`            | —                 | Declarative OTLP fan-out to multiple backends                   |
 | `spanProcessors`                        | `SpanProcessor[]`                                               | —                 | Use **instead of** `exporter` for full control                  |
 | `sampling.rates`                        | `{ server?: number, client?: number, internal?: number }`       | `100%`            | Head sampling per span kind (0–100%)                            |
 | `sampling.tail`                         | `TailSampleFn`                                                  | —                 | Keep traces matching predicate (e.g. errors, slow)              |
@@ -291,7 +292,7 @@ Switch backends with **no code changes** — autotel speaks OTLP HTTP/JSON and H
 | New Relic                        | `https://otlp.nr-data.net/v1/traces`                       | `{ 'api-key': '<key>' }`              |
 | Local Jaeger / Tempo / Collector | `http://localhost:4318/v1/traces`                          | —                                     |
 
-Use `init({ exporter: { url, headers } })`. Multiple destinations? Use `composeSpanProcessors([batchA, batchB])` (see Composition below).
+Use `init({ endpoint, headers })` for one backend. For multiple OTLP backends, prefer `init({ destinations: [...] })`. Drop to `composeSpanProcessors([batchA, batchB])` only when you need custom processor-level control.
 
 ---
 

package/src/init.customization.test.ts

@@ -325,6 +325,77 @@ describe('init() customization', () => {
     });
   });
 
+  it('supports declarative multi-destination OTLP fan-out', async () => {
+    const {
+      init,
+      traceExporterOptions,
+      metricExporterOptions,
+      logExporterOptions,
+      metricReaderOptions,
+    } = await loadInitWithMocks();
+
+    init({
+      service: 'fanout-app',
+      logs: true,
+      destinations: [
+        {
+          endpoint: 'https://otlp-gateway.grafana.net/otlp',
+          headers: { Authorization: 'Basic grafana' },
+        },
+        {
+          endpoint: 'https://api.honeycomb.io',
+          headers: { 'x-honeycomb-team': 'hny' },
+          signals: ['traces'],
+        },
+      ],
+    });
+
+    expect(traceExporterOptions).toHaveLength(2);
+    expect(traceExporterOptions[0]).toMatchObject({
+      url: 'https://otlp-gateway.grafana.net/otlp/v1/traces',
+      headers: { Authorization: 'Basic grafana' },
+    });
+    expect(traceExporterOptions[1]).toMatchObject({
+      url: 'https://api.honeycomb.io/v1/traces',
+      headers: { 'x-honeycomb-team': 'hny' },
+    });
+
+    expect(metricExporterOptions).toHaveLength(1);
+    expect(metricExporterOptions[0]).toMatchObject({
+      url: 'https://otlp-gateway.grafana.net/otlp/v1/metrics',
+    });
+    expect(metricReaderOptions).toHaveLength(1);
+
+    expect(logExporterOptions).toHaveLength(1);
+    expect(logExporterOptions[0]).toMatchObject({
+      url: 'https://otlp-gateway.grafana.net/otlp/v1/logs',
+    });
+  });
+
+  it('lets destinations inherit top-level protocol and headers', async () => {
+    const { init, traceExporterOptions, metricExporterOptions } =
+      await loadInitWithMocks();
+
+    init({
+      service: 'fanout-inherited',
+      protocol: 'http',
+      headers: 'Authorization=Bearer shared',
+      destinations: [
+        { endpoint: 'https://grafana.example.com/otlp' },
+        { endpoint: 'https://honeycomb.example.com' },
+      ],
+    });
+
+    expect(traceExporterOptions).toHaveLength(2);
+    expect(traceExporterOptions[0]).toMatchObject({
+      headers: { Authorization: 'Bearer shared' },
+    });
+    expect(traceExporterOptions[1]).toMatchObject({
+      headers: { Authorization: 'Bearer shared' },
+    });
+    expect(metricExporterOptions).toHaveLength(2);
+  });
+
   it('resolves sampling preset shorthand to a sampler instance', async () => {
     const { init, getDefaultSampler } = await loadInitWithMocks();
 

package/src/init.ts

@@ -126,6 +126,33 @@ type OTLPExporterConfig = {
   concurrencyLimit?: number;
 };
 
+export type OtlpSignal = 'traces' | 'metrics' | 'logs';
+
+export interface OtlpDestinationConfig {
+  /**
+   * Base OTLP endpoint for this destination.
+   * HTTP destinations may omit `/v1/{signal}`; autotel appends it automatically.
+   * gRPC destinations should point at the collector host:port.
+   */
+  endpoint: string;
+
+  /**
+   * Headers for this destination. Falls back to top-level `headers`.
+   */
+  headers?: Record<string, string> | string;
+
+  /**
+   * Protocol for this destination. Falls back to top-level `protocol`.
+   */
+  protocol?: 'http' | 'grpc';
+
+  /**
+   * Signals to send to this destination.
+   * Defaults to all signals supported by the current init() config.
+   */
+  signals?: OtlpSignal[];
+}
+
 // Lazy-load gRPC exporters (optional peer dependencies)
 let OTLPTraceExporterGRPC:
   | (new (config: OTLPExporterConfig) => SpanExporter)
@@ -415,11 +442,45 @@ export interface AutotelConfig {
 
   /**
    * OTLP endpoint for traces/metrics/logs
+   * Single-destination shorthand. For multi-backend OTLP fan-out, use
+   * `destinations` instead.
    * Only used if you don't provide custom exporters/processors
    * @default process.env.OTLP_ENDPOINT || 'http://localhost:4318'
    */
   endpoint?: string;
 
+  /**
+   * Declarative OTLP multi-destination config.
+   * Each destination can override endpoint, headers, protocol, and signals.
+   *
+   * This is the high-level alternative to wiring `spanExporters`,
+   * `spanProcessors`, `metricReaders`, and `logRecordProcessors` manually when
+   * you want to fan telemetry out to multiple OTLP backends.
+   *
+   * When provided, `destinations` takes precedence over the single `endpoint`
+   * shorthand for built-in OTLP exporters/readers/processors.
+   *
+   * @example Grafana + Honeycomb for traces, Grafana only for metrics/logs
+   * ```typescript
+   * init({
+   *   service: 'my-app',
+   *   logs: true,
+   *   destinations: [
+   *     {
+   *       endpoint: 'https://otlp-gateway-prod-eu-west-2.grafana.net/otlp',
+   *       headers: { Authorization: 'Basic ...' },
+   *     },
+   *     {
+   *       endpoint: 'https://api.honeycomb.io',
+   *       headers: { 'x-honeycomb-team': '...' },
+   *       signals: ['traces'],
+   *     },
+   *   ],
+   * })
+   * ```
+   */
+  destinations?: OtlpDestinationConfig[];
+
   /**
    * Custom span processors for traces (supports multiple processors)
    * Allows you to use any backend: Jaeger, Zipkin, Datadog, New Relic, etc.
@@ -1406,6 +1467,45 @@ function normalizeOtlpHeaders(
   return parsed;
 }
 
+type ResolvedOtlpDestination = {
+  endpoint: string;
+  protocol: 'http' | 'grpc';
+  headers?: Record<string, string>;
+  signals?: Set<OtlpSignal>;
+};
+
+function resolveOtlpDestinations(
+  config: AutotelConfig,
+  fallbackEndpoint?: string,
+): ResolvedOtlpDestination[] {
+  const rawDestinations =
+    config.destinations !== undefined
+      ? config.destinations
+      : fallbackEndpoint
+        ? [
+            {
+              endpoint: fallbackEndpoint,
+              headers: config.headers,
+              protocol: config.protocol,
+            },
+          ]
+        : [];
+
+  return rawDestinations.map((destination) => ({
+    endpoint: destination.endpoint,
+    protocol: resolveProtocol(destination.protocol ?? config.protocol),
+    headers: normalizeOtlpHeaders(destination.headers ?? config.headers),
+    signals: destination.signals ? new Set(destination.signals) : undefined,
+  }));
+}
+
+function destinationSupportsSignal(
+  destination: ResolvedOtlpDestination,
+  signal: OtlpSignal,
+): boolean {
+  return destination.signals ? destination.signals.has(signal) : true;
+}
+
 /**
  * Initialize autotel - Write Once, Observe Everywhere
  *
@@ -1533,7 +1633,6 @@ export function init(cfg: AutotelConfig): void {
   // Initialize OpenTelemetry
   // Only use endpoint if explicitly configured (no default fallback)
   let endpoint = mergedConfig.endpoint ?? devtoolsConfig.endpoint;
-  const otlpHeaders = normalizeOtlpHeaders(mergedConfig.headers);
   const version = mergedConfig.version || detectVersion();
   const environment =
     mergedConfig.environment || process.env.NODE_ENV || 'development';
@@ -1600,8 +1699,7 @@ export function init(cfg: AutotelConfig): void {
     );
   }
 
-  // Resolve OTLP protocol (http or grpc)
-  const protocol = resolveProtocol(mergedConfig.protocol);
+  const otlpDestinations = resolveOtlpDestinations(mergedConfig, endpoint);
 
   // Backward-compatible singular aliases. Plural forms take precedence when both are provided.
   const configuredSpanProcessors =
@@ -1643,16 +1741,23 @@ export function init(cfg: AutotelConfig): void {
         new TailSamplingSpanProcessor(new BatchSpanProcessor(exporter)),
       );
     }
-  } else if (endpoint) {
-    // Default: OTLP with tail sampling (only if endpoint is configured)
-    const traceExporter = createTraceExporter(protocol, {
-      url: formatEndpointUrl(endpoint, 'traces', protocol),
-      headers: otlpHeaders,
-    });
-
-    spanProcessors.push(
-      new TailSamplingSpanProcessor(new BatchSpanProcessor(traceExporter)),
-    );
+  } else {
+    for (const destination of otlpDestinations) {
+      if (!destinationSupportsSignal(destination, 'traces')) continue;
+
+      const traceExporter = createTraceExporter(destination.protocol, {
+        url: formatEndpointUrl(
+          destination.endpoint,
+          'traces',
+          destination.protocol,
+        ),
+        headers: destination.headers,
+      });
+
+      spanProcessors.push(
+        new TailSamplingSpanProcessor(new BatchSpanProcessor(traceExporter)),
+      );
+    }
   }
   // If no endpoint and no custom processors/exporters, array remains empty
   // SDK will still work but won't export traces
@@ -1760,18 +1865,25 @@ export function init(cfg: AutotelConfig): void {
   if (configuredMetricReaders && configuredMetricReaders.length > 0) {
     // User provided custom metric readers
     metricReaders.push(...configuredMetricReaders);
-  } else if (metricsEnabled && endpoint) {
-    // Default: OTLP metrics exporter (only if endpoint is configured)
-    const metricExporter = createMetricExporter(protocol, {
-      url: formatEndpointUrl(endpoint, 'metrics', protocol),
-      headers: otlpHeaders,
-    });
-
-    metricReaders.push(
-      new PeriodicExportingMetricReader({
-        exporter: metricExporter,
-      }),
-    );
+  } else if (metricsEnabled) {
+    for (const destination of otlpDestinations) {
+      if (!destinationSupportsSignal(destination, 'metrics')) continue;
+
+      const metricExporter = createMetricExporter(destination.protocol, {
+        url: formatEndpointUrl(
+          destination.endpoint,
+          'metrics',
+          destination.protocol,
+        ),
+        headers: destination.headers,
+      });
+
+      metricReaders.push(
+        new PeriodicExportingMetricReader({
+          exporter: metricExporter,
+        }),
+      );
+    }
   }
 
   let logRecordProcessors: LogRecordProcessor[] | undefined;
@@ -1782,24 +1894,39 @@ export function init(cfg: AutotelConfig): void {
     logRecordProcessors = [...configuredLogRecordProcessors];
   }
 
-  // Auto-configure OTLP log exporter when logs are enabled and endpoint is set
-  if (logsEnabled && endpoint) {
-    const logExporter = createLogExporter(protocol, {
-      url: formatEndpointUrl(endpoint, 'logs', protocol),
-      headers: otlpHeaders,
-    });
+  // Auto-configure OTLP log exporters when logs are enabled.
+  if (logsEnabled) {
+    for (const destination of otlpDestinations) {
+      if (!destinationSupportsSignal(destination, 'logs')) continue;
+
+      const logExporter = createLogExporter(destination.protocol, {
+        url: formatEndpointUrl(
+          destination.endpoint,
+          'logs',
+          destination.protocol,
+        ),
+        headers: destination.headers,
+      });
 
-    let processor: LogRecordProcessor = new BatchLogRecordProcessor(
-      logExporter,
-    );
-    if (_stringRedactor) {
-      processor = new RedactingLogRecordProcessor(processor, _stringRedactor);
+      let processor: LogRecordProcessor = new BatchLogRecordProcessor(
+        logExporter,
+      );
+      if (_stringRedactor) {
+        processor = new RedactingLogRecordProcessor(processor, _stringRedactor);
+      }
+      if (!logRecordProcessors) {
+        logRecordProcessors = [];
+      }
+      logRecordProcessors.push(processor);
     }
-    if (!logRecordProcessors) {
-      logRecordProcessors = [];
+
+    if (
+      otlpDestinations.some((destination) =>
+        destinationSupportsSignal(destination, 'logs'),
+      )
+    ) {
+      logger.info({}, '[autotel] OTLP log exporter configured');
     }
-    logRecordProcessors.push(processor);
-    logger.info({}, '[autotel] OTLP log exporter configured');
   }
 
   // PostHog OTLP logs integration

package/src/yaml-config.test.ts

@@ -70,6 +70,42 @@ exporter:
       });
     });
 
+    it('should parse exporter destinations configuration', () => {
+      const yaml = `
+exporter:
+  destinations:
+    - endpoint: https://otlp-gateway.grafana.net/otlp
+      headers:
+        Authorization: Basic grafana
+    - endpoint: https://api.honeycomb.io
+      protocol: grpc
+      headers:
+        x-honeycomb-team: secret-key
+      signals:
+        - traces
+`;
+      const filePath = path.join(testDir, 'exporter-destinations.yaml');
+      writeFileSync(filePath, yaml);
+
+      const config = loadYamlConfigFromFile(filePath);
+      expect(config.destinations).toEqual([
+        {
+          endpoint: 'https://otlp-gateway.grafana.net/otlp',
+          headers: {
+            Authorization: 'Basic grafana',
+          },
+        },
+        {
+          endpoint: 'https://api.honeycomb.io',
+          protocol: 'grpc',
+          headers: {
+            'x-honeycomb-team': 'secret-key',
+          },
+          signals: ['traces'],
+        },
+      ]);
+    });
+
     it('should parse resource attributes', () => {
       const yaml = `
 resource:

package/src/yaml-config.ts

@@ -23,7 +23,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import type { AutotelConfig } from './init';
+import type { AutotelConfig, OtlpSignal } from './init';
 import {
   AdaptiveSampler,
   AlwaysSampler,
@@ -61,6 +61,12 @@ export interface YamlConfig {
     endpoint?: string;
     protocol?: 'http' | 'grpc';
     headers?: Record<string, string>;
+    destinations?: Array<{
+      endpoint: string;
+      protocol?: 'http' | 'grpc';
+      headers?: Record<string, string>;
+      signals?: OtlpSignal[];
+    }>;
   };
   resource?: Record<string, string | number | boolean>;
   sampling?: {
@@ -179,6 +185,9 @@ function yamlToAutotelConfig(yaml: YamlConfig): Partial<AutotelConfig> {
   if (yaml.exporter?.endpoint) config.endpoint = yaml.exporter.endpoint;
   if (yaml.exporter?.protocol) config.protocol = yaml.exporter.protocol;
   if (yaml.exporter?.headers) config.headers = yaml.exporter.headers;
+  if (yaml.exporter?.destinations) {
+    config.destinations = yaml.exporter.destinations;
+  }
 
   // Resource attributes (flattened)
   if (yaml.resource) config.resourceAttributes = yaml.resource;