autotel 2.1.0

package/src/instrumentation.test.ts

@@ -0,0 +1,108 @@
+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

@@ -0,0 +1,308 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-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';
+
+/**
+ * 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;
+  /** OTLP headers for authentication (e.g., Grafana Cloud) */
+  otlpHeaders?: 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(
+      'Error terminating OpenTelemetry',
+      error instanceof Error ? error : undefined,
+    );
+    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 OTLP headers and resource attributes
+  const otlpHeaders = parseOtlpHeaders(config.otlpHeaders);
+  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)
+  const instrumentations =
+    config.selectiveInstrumentation === false
+      ? [getNodeAutoInstrumentations()]
+      : config.instrumentations || [];
+
+  const traceExporter = new OTLPTraceExporter({
+    url: `${config.otlpEndpoint || 'http://localhost:4318'}/v1/traces`,
+    headers: otlpHeaders,
+  });
+
+  // Enables tail sampling via 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(
+      'Failed to start OpenTelemetry SDK',
+      error instanceof Error ? error : undefined,
+    );
+    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(
+            'Shutdown error',
+            error instanceof Error ? error : undefined,
+          );
+          // 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

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi } from 'vitest';
+import { LoggedOperation, type Logger } from './logger';
+
+describe('Logger interface', () => {
+  it('should work with custom logger implementations', () => {
+    const mockLogger: Logger = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    };
+
+    mockLogger.info('Test message', { key: 'value' });
+    expect(mockLogger.info).toHaveBeenCalledWith('Test message', {
+      key: 'value',
+    });
+  });
+
+  it('should support error method with optional error parameter', () => {
+    const mockLogger: Logger = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    };
+
+    const error = new Error('Test error');
+    mockLogger.error('Error occurred', error, { context: 'test' });
+    expect(mockLogger.error).toHaveBeenCalledWith('Error occurred', error, {
+      context: 'test',
+    });
+  });
+});
+
+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');
+    expect(mockLog.info).toHaveBeenCalledWith(
+      'Operation started',
+      expect.objectContaining({ operation: 'test.operation' }),
+    );
+    expect(mockLog.info).toHaveBeenCalledWith(
+      'Operation completed',
+      expect.objectContaining({ operation: 'test.operation' }),
+    );
+  });
+
+  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');
+    expect(mockLog.error).toHaveBeenCalledWith(
+      'Operation failed',
+      expect.any(Error),
+      expect.objectContaining({ operation: 'test.failing' }),
+    );
+  });
+});