autotel 4.1.0 → 4.2.0

package/src/instrumentation.test.ts

@@ -1,108 +0,0 @@
-import { describe, it, expect, afterEach } from 'vitest';
-import {
-  initInstrumentation,
-  shutdownInstrumentation,
-} from './instrumentation';
-import type { NodeSDK } from '@opentelemetry/sdk-node';
-
-describe('initInstrumentation', () => {
-  let sdk: NodeSDK | undefined;
-
-  afterEach(async () => {
-    if (sdk) {
-      try {
-        await shutdownInstrumentation(sdk);
-      } catch {
-        // Ignore shutdown errors in tests
-      }
-      sdk = undefined;
-    }
-  });
-
-  it('should initialize with minimal config', async () => {
-    sdk = await initInstrumentation({
-      serviceName: 'test-service',
-    });
-
-    expect(sdk).toBeDefined();
-  });
-
-  it('should initialize with full config', async () => {
-    sdk = await initInstrumentation({
-      serviceName: 'test-service',
-      serviceVersion: '2.0.0',
-      deploymentEnvironment: 'test',
-      otlpEndpoint: 'http://localhost:4318',
-    });
-
-    expect(sdk).toBeDefined();
-  });
-
-  it('should support detectResources option', async () => {
-    sdk = await initInstrumentation({
-      serviceName: 'test-service',
-      detectResources: true,
-    });
-
-    expect(sdk).toBeDefined();
-  });
-
-  it('should return NodeSDK instance', async () => {
-    sdk = await initInstrumentation({
-      serviceName: 'test-service',
-    });
-
-    expect(sdk).toBeDefined();
-    expect(typeof sdk.start).toBe('function');
-    expect(typeof sdk.shutdown).toBe('function');
-  });
-});
-
-describe('shutdownInstrumentation', () => {
-  it('should shutdown without error', async () => {
-    const sdk = await initInstrumentation({
-      serviceName: 'test-shutdown',
-    });
-
-    await expect(shutdownInstrumentation(sdk)).resolves.not.toThrow();
-  });
-
-  it('should handle shutdown with no SDK gracefully', async () => {
-    // Should warn but not throw
-    await expect(shutdownInstrumentation()).resolves.not.toThrow();
-  });
-
-  it('should handle multiple shutdowns gracefully', async () => {
-    const sdk = await initInstrumentation({
-      serviceName: 'test-multiple-shutdown',
-    });
-
-    await shutdownInstrumentation(sdk);
-
-    // Second shutdown should not throw
-    await expect(shutdownInstrumentation(sdk)).resolves.not.toThrow();
-  });
-});
-
-describe('SIGTERM handler', () => {
-  it('should not add new handlers on subsequent inits', async () => {
-    const sdk1 = await initInstrumentation({
-      serviceName: 'test-1',
-    });
-
-    const countAfterFirst = process.listenerCount('SIGTERM');
-
-    const sdk2 = await initInstrumentation({
-      serviceName: 'test-2',
-    });
-
-    const countAfterSecond = process.listenerCount('SIGTERM');
-
-    // Should not add a new handler on second init
-    expect(countAfterSecond).toBe(countAfterFirst);
-
-    // Cleanup
-    await shutdownInstrumentation(sdk1);
-    await shutdownInstrumentation(sdk2);
-  });
-});

package/src/instrumentation.ts

@@ -1,319 +0,0 @@
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
-import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { TailSamplingSpanProcessor } from './tail-sampling-processor';
-import { getLogger } from './init';
-import {
-  resourceFromAttributes,
-  detectResources,
-  processDetector,
-  hostDetector,
-  type Resource,
-  type ResourceDetector,
-} from '@opentelemetry/resources';
-import {
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-} from '@opentelemetry/semantic-conventions/incubating';
-import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
-import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
-import { requireModule } from './node-require';
-
-/**
- * Parse OTLP headers string into object format
- * @param headersString - Headers as "key1=value1,key2=value2" or "Authorization=Basic ..."
- * @returns Headers object for OTLP exporters
- */
-function parseOtlpHeaders(headersString?: string): Record<string, string> {
-  if (!headersString) return {};
-
-  const headers: Record<string, string> = {};
-  const pairs = headersString.split(',');
-
-  for (const pair of pairs) {
-    const [key, ...valueParts] = pair.split('=');
-    if (key && valueParts.length > 0) {
-      headers[key.trim()] = valueParts.join('=').trim();
-    }
-  }
-
-  return headers;
-}
-
-/**
- * Parse resource attributes string into object format
- * @param attributesString - Attributes as "key1=value1,key2=value2"
- * @returns Resource attributes object
- */
-function parseResourceAttributes(
-  attributesString?: string,
-): Record<string, string> {
-  if (!attributesString) return {};
-
-  const attributes: Record<string, string> = {};
-  const pairs = attributesString.split(',');
-
-  for (const pair of pairs) {
-    const [key, ...valueParts] = pair.split('=');
-    if (key && valueParts.length > 0) {
-      attributes[key.trim()] = valueParts.join('=').trim();
-    }
-  }
-
-  return attributes;
-}
-
-export interface InstrumentationConfig {
-  serviceName: string;
-  serviceVersion?: string;
-  deploymentEnvironment?: string;
-  otlpEndpoint?: string;
-  /** Headers for authentication (e.g., Grafana Cloud, Honeycomb) */
-  headers?: string;
-  /** Resource attributes as comma-separated key=value pairs */
-  resourceAttributes?: string;
-  /** Enable async resource detection for process/host info (default: false) */
-  detectResources?: boolean;
-  /**
-   * Use selective instrumentation instead of full auto-instrumentation
-   * **Default: true** (performance-first)
-   *
-   * When true, auto-instrumentation is disabled. You can manually add
-   * specific instrumentations via the `instrumentations` field.
-   * This reduces overhead from ~81% to near-zero based on Platformatic benchmarks.
-   *
-   * Set to false to enable full auto-instrumentation (not recommended for production).
-   *
-   * @see https://blogger.platformatic.dev/the-hidden-cost-of-context
-   */
-  selectiveInstrumentation?: boolean;
-
-  /**
-   * Custom instrumentations to use (only when selectiveInstrumentation is true)
-   * @example
-   * ```typescript
-   * import { HttpInstrumentation } from '@opentelemetry/instrumentation-http'
-   *
-   * initInstrumentation({
-   *   serviceName: 'api',
-   *   selectiveInstrumentation: true,
-   *   instrumentations: [new HttpInstrumentation()]
-   * })
-   * ```
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  instrumentations?: any[];
-}
-
-/**
- * Initialize OpenTelemetry instrumentation with OTLP exporters
- *
- * This sets up:
- * - Traces (OTLP HTTP)
- * - Metrics (OTLP HTTP)
- * - Logs (OTLP HTTP)
- * - Auto-instrumentation for common Node.js libraries
- *
- * @example
- * // Call this at the very start of your application
- * import { initInstrumentation } from '@your-org/otel-decorators'
- *
- * initInstrumentation({
- *   serviceName: 'my-service' }
- *   serviceVersion: '1.0.0',
- *   deploymentEnvironment: 'production',
- *   otlpEndpoint: 'http://localhost:4318'
- * })
- *
- * // Or with async resource detection (top-level await required)
- * await initInstrumentation({
- *   serviceName: 'my-service' }
- *   detectResources: true
- * })
- */
-// Enables graceful shutdown and prevents SDK leaks on hot-reload
-let currentSDK: NodeSDK | null = null;
-let shutdownHandlerRegistered = false;
-
-/**
- * Shutdown the OpenTelemetry SDK gracefully
- * Call this before process exit or during hot-reloads
- */
-export async function shutdownInstrumentation(sdk?: NodeSDK): Promise<void> {
-  const sdkToShutdown = sdk || currentSDK;
-  if (!sdkToShutdown) {
-    getLogger().warn({}, 'No SDK to shutdown');
-    return;
-  }
-
-  try {
-    await sdkToShutdown.shutdown();
-    getLogger().info({}, 'OpenTelemetry terminated successfully');
-    if (sdkToShutdown === currentSDK) {
-      currentSDK = null;
-    }
-  } catch (error) {
-    getLogger().error(
-      {
-        err: error instanceof Error ? error : undefined,
-      },
-      'Error terminating OpenTelemetry',
-    );
-    throw error;
-  }
-}
-
-export async function initInstrumentation(
-  config: InstrumentationConfig,
-): Promise<NodeSDK> {
-  // Prevents resource leaks on hot-reload or multiple init calls
-  if (currentSDK) {
-    getLogger().info(
-      {},
-      'Shutting down existing OpenTelemetry SDK before reinitializing...',
-    );
-    await shutdownInstrumentation(currentSDK);
-  }
-
-  // Parse headers and resource attributes
-  const otlpHeaders = parseOtlpHeaders(config.headers);
-  const customResourceAttributes = parseResourceAttributes(
-    config.resourceAttributes,
-  );
-
-  let resource: Resource;
-
-  // Dynamically load optional resource detectors
-  const detectors: ResourceDetector[] = [processDetector, hostDetector];
-  try {
-    const awsDetectors = await import('@opentelemetry/resource-detector-aws');
-    detectors.push(
-      awsDetectors.awsEc2Detector,
-      awsDetectors.awsEcsDetector,
-      awsDetectors.awsEksDetector,
-    );
-  } catch {
-    // ignore
-  }
-  try {
-    const gcpDetectors = await import('@opentelemetry/resource-detector-gcp');
-    detectors.push(gcpDetectors.gcpDetector);
-  } catch {
-    // ignore
-  }
-  try {
-    const containerDetectors =
-      await import('@opentelemetry/resource-detector-container');
-    detectors.push(containerDetectors.containerDetector);
-  } catch {
-    // ignore
-  }
-
-  if (config.detectResources) {
-    const detectedResource = await detectResources({
-      detectors,
-    });
-
-    resource = detectedResource.merge(
-      resourceFromAttributes({
-        [ATTR_SERVICE_NAME]: config.serviceName,
-        [ATTR_SERVICE_VERSION]: config.serviceVersion || '1.0.0',
-        'deployment.environment': config.deploymentEnvironment || 'development',
-        ...customResourceAttributes, // Merge custom resource attributes
-      }),
-    );
-  } else {
-    resource = resourceFromAttributes({
-      [ATTR_SERVICE_NAME]: config.serviceName,
-      [ATTR_SERVICE_VERSION]: config.serviceVersion || '1.0.0',
-      'deployment.environment': config.deploymentEnvironment || 'development',
-      ...customResourceAttributes, // Merge custom resource attributes
-    });
-  }
-
-  // Default to selective (near-zero overhead) vs full auto (~81% overhead)
-  // Lazy-load to avoid importing ~40+ packages at module evaluation time
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let instrumentations: any[] = config.instrumentations || [];
-  if (config.selectiveInstrumentation === false) {
-    const mod = requireModule<{
-      getNodeAutoInstrumentations: () => unknown[];
-    }>('@opentelemetry/auto-instrumentations-node');
-    instrumentations = [mod.getNodeAutoInstrumentations()];
-  }
-
-  const traceExporter = new OTLPTraceExporter({
-    url: `${config.otlpEndpoint || 'http://localhost:4318'}/v1/traces`,
-    headers: otlpHeaders,
-  });
-
-  // Enables tail sampling via autotel.sampling.tail.keep attribute
-  const spanProcessor = new TailSamplingSpanProcessor(
-    new BatchSpanProcessor(traceExporter),
-  );
-
-  const sdk = new NodeSDK({
-    resource,
-    spanProcessor, // Use our wrapped processor instead of traceExporter directly
-    metricReader: new PeriodicExportingMetricReader({
-      exporter: new OTLPMetricExporter({
-        url: `${config.otlpEndpoint || 'http://localhost:4318'}/v1/metrics`,
-        headers: otlpHeaders,
-      }),
-    }),
-    logRecordProcessors: [
-      new BatchLogRecordProcessor(
-        new OTLPLogExporter({
-          url: `${config.otlpEndpoint || 'http://localhost:4318'}/v1/logs`,
-          headers: otlpHeaders,
-        }),
-      ),
-    ],
-    instrumentations,
-  });
-
-  try {
-    await sdk.start();
-    getLogger().info({}, 'OpenTelemetry instrumentation started successfully');
-  } catch (error) {
-    getLogger().error(
-      {
-        err: error instanceof Error ? error : undefined,
-      },
-      'Failed to start OpenTelemetry SDK',
-    );
-    throw error;
-  }
-
-  // Track current SDK for shutdown handler
-  currentSDK = sdk;
-
-  if (!shutdownHandlerRegistered) {
-    shutdownHandlerRegistered = true;
-
-    const shutdownHandler = () => {
-      shutdownInstrumentation()
-        .then(() => {
-          // eslint-disable-next-line unicorn/no-process-exit
-          process.exit(0);
-        })
-        .catch((error) => {
-          getLogger().error(
-            {
-              err: error instanceof Error ? error : undefined,
-            },
-            'Shutdown error',
-          );
-          // eslint-disable-next-line unicorn/no-process-exit
-          process.exit(1);
-        });
-    };
-
-    process.on('SIGTERM', shutdownHandler);
-    process.on('SIGINT', shutdownHandler);
-  }
-
-  return sdk;
-}

package/src/logger.test.ts

@@ -1,125 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { LoggedOperation, type Logger } from './logger';
-
-describe('Logger interface', () => {
-  it('should work with custom logger implementations (Pino signature)', () => {
-    const mockLogger: Logger = {
-      info: vi.fn(),
-      warn: vi.fn(),
-      error: vi.fn(),
-      debug: vi.fn(),
-    };
-
-    // Pino-compatible signature: (extra, message?)
-    mockLogger.info({ key: 'value' }, 'Test message');
-    expect(mockLogger.info).toHaveBeenCalledWith(
-      { key: 'value' },
-      'Test message',
-    );
-  });
-
-  it('should support error method with err in extra object', () => {
-    const mockLogger: Logger = {
-      info: vi.fn(),
-      warn: vi.fn(),
-      error: vi.fn(),
-      debug: vi.fn(),
-    };
-
-    const error = new Error('Test error');
-    // Pino-compatible signature: error goes in extra.err
-    mockLogger.error({ err: error, context: 'test' }, 'Error occurred');
-    expect(mockLogger.error).toHaveBeenCalledWith(
-      { err: error, context: 'test' },
-      'Error occurred',
-    );
-  });
-});
-
-describe('@LoggedOperation decorator', () => {
-  it('should support simple string syntax', async () => {
-    class TestService {
-      constructor(public deps: { log: Logger }) {}
-
-      @LoggedOperation('test.operation')
-      async testMethod() {
-        return 'result';
-      }
-    }
-
-    const mockLog = {
-      info: vi.fn(),
-      warn: vi.fn(),
-      error: vi.fn(),
-      debug: vi.fn(),
-    } as unknown as Logger;
-
-    const service = new TestService({ log: mockLog });
-    const result = await service.testMethod();
-
-    expect(result).toBe('result');
-    // Pino-native style: (extra, message)
-    expect(mockLog.info).toHaveBeenCalledWith(
-      expect.objectContaining({ operation: 'test.operation' }),
-      'Operation started',
-    );
-    expect(mockLog.info).toHaveBeenCalledWith(
-      expect.objectContaining({ operation: 'test.operation' }),
-      'Operation completed',
-    );
-  });
-
-  it('should support advanced object syntax', async () => {
-    class TestService {
-      constructor(public deps: { log: Logger }) {}
-
-      @LoggedOperation({ operationName: 'test.operation' })
-      async testMethod() {
-        return 'result';
-      }
-    }
-
-    const mockLog = {
-      info: vi.fn(),
-      warn: vi.fn(),
-      error: vi.fn(),
-      debug: vi.fn(),
-    } as unknown as Logger;
-
-    const service = new TestService({ log: mockLog });
-    const result = await service.testMethod();
-
-    expect(result).toBe('result');
-    expect(mockLog.info).toHaveBeenCalled();
-  });
-
-  it('should record errors', async () => {
-    class TestService {
-      constructor(public deps: { log: Logger }) {}
-
-      @LoggedOperation('test.failing')
-      async failingMethod() {
-        throw new Error('Test error');
-      }
-    }
-
-    const mockLog = {
-      info: vi.fn(),
-      warn: vi.fn(),
-      error: vi.fn(),
-      debug: vi.fn(),
-    } as unknown as Logger;
-
-    const service = new TestService({ log: mockLog });
-
-    await expect(service.failingMethod()).rejects.toThrow('Test error');
-    // Pino-native style: (extra, message)
-    expect(mockLog.error).toHaveBeenCalledWith(
-      expect.objectContaining({
-        operation: 'test.failing',
-        err: expect.any(Error),
-      }),
-      'Operation failed',
-    );
-  });
-});