autotel 2.1.0

package/src/decorators.ts

@@ -0,0 +1,188 @@
+/**
+ * TypeScript 5+ Decorators for autotel
+ *
+ * Provides @Trace decorator for class-based code.
+ *
+ * **Requires TypeScript 5.0+**
+ *
+ * @example Method decorator
+ * ```typescript
+ * import { Trace } from 'autotel/decorators'
+ *
+ * class OrderService {
+ *   @Trace('order.create', { withMetrics: true })
+ *   async createOrder(data: OrderData) {
+ *     return await db.orders.create(data)
+ *   }
+ *
+ *   @Trace() // Uses method name as span name
+ *   async processPayment(orderId: string) {
+ *     return await stripe.charge(orderId)
+ *   }
+ * }
+ * ```
+ */
+
+import type { TracingOptions, TraceContext } from './functional';
+import { getConfig } from './config';
+import { SpanStatusCode } from '@opentelemetry/api';
+import { createTraceContext } from './trace-context';
+
+/**
+ * Options for @Trace method decorator
+ */
+export interface TraceDecoratorOptions extends Omit<TracingOptions, 'name'> {
+  /**
+   * Custom span name. If not provided, uses the method name.
+   */
+  name?: string;
+}
+
+/**
+ * @Trace - Method decorator for fine-grained tracing
+ *
+ * Wraps a class method with automatic tracing. Supports both patterns:
+ * - Simple: method doesn't use ctx
+ * - Advanced: method accesses ctx via this.ctx
+ *
+ * @example Simple usage (no ctx)
+ * ```typescript
+ * class OrderService {
+ *   @Trace()
+ *   async createOrder(data: OrderData) {
+ *     return await db.orders.create(data)
+ *   }
+ * }
+ * ```
+ *
+ * @example With custom name and options
+ * ```typescript
+ * class PaymentService {
+ *   @Trace('payment.charge', { withMetrics: true })
+ *   async chargeCard(amount: number) {
+ *     return await stripe.charges.create({ amount })
+ *   }
+ * }
+ * ```
+ *
+ * @example Accessing ctx
+ * ```typescript
+ * interface WithTraceContext {
+ *   ctx?: TraceContext
+ * }
+ *
+ * class UserService {
+ *   @Trace()
+ *   async createUser(data: UserData) {
+ *     // Access ctx via this.ctx (available during execution)
+ *     const ctx = (this as unknown as WithTraceContext).ctx
+ *     if (ctx) {
+ *       ctx.setAttribute('user.id', data.id)
+ *     }
+ *     return await db.users.create(data)
+ *   }
+ * }
+ * ```
+ */
+export function Trace(
+  options?: TraceDecoratorOptions,
+): <T extends (...args: unknown[]) => Promise<unknown>>(
+  originalMethod: T,
+  context: ClassMethodDecoratorContext,
+) => T;
+export function Trace(
+  name?: string,
+  options?: TraceDecoratorOptions,
+): <T extends (...args: unknown[]) => Promise<unknown>>(
+  originalMethod: T,
+  context: ClassMethodDecoratorContext,
+) => T;
+export function Trace(
+  nameOrOptions?: string | TraceDecoratorOptions,
+  maybeOptions?: TraceDecoratorOptions,
+): <T extends (...args: unknown[]) => Promise<unknown>>(
+  originalMethod: T,
+  context: ClassMethodDecoratorContext,
+) => T {
+  // Parse arguments
+  const name =
+    typeof nameOrOptions === 'string' ? nameOrOptions : nameOrOptions?.name;
+  // Options are used in the returned decorator function, not here
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const _options: TraceDecoratorOptions =
+    typeof nameOrOptions === 'string'
+      ? maybeOptions || {}
+      : nameOrOptions || {};
+
+  // TypeScript 5+ decorator signature
+  return function <T extends (...args: unknown[]) => Promise<unknown>>(
+    originalMethod: T,
+    context: ClassMethodDecoratorContext,
+  ): T {
+    const methodName = String(context.name);
+
+    // Skip if not an async function
+    // Check multiple ways to detect async functions (for different transpilation environments)
+    // TypeScript decorators run at class definition time, so we need robust detection
+    const methodStr = originalMethod?.toString() || '';
+    const isAsync =
+      originalMethod &&
+      (originalMethod.constructor?.name === 'AsyncFunction' ||
+        methodStr.trim().startsWith('async ') ||
+        (methodStr.includes('[native code]') && methodStr.includes('async')) ||
+        // Fallback: if function has async in its string representation
+        /async\s+/.test(methodStr));
+
+    if (!isAsync) {
+      // Not an async function, return as-is
+      return originalMethod;
+    }
+
+    const spanName = name || methodName;
+
+    return async function <This>(
+      this: This,
+      ...args: unknown[]
+    ): Promise<unknown> {
+      const config = getConfig();
+      const tracer = config.tracer;
+
+      return tracer.startActiveSpan(spanName, async (span) => {
+        try {
+          // Make ctx available via this.ctx for methods that need it
+          const ctx: TraceContext = createTraceContext(span);
+
+          const originalCtx = (this as { ctx?: TraceContext }).ctx;
+          try {
+            (this as { ctx?: TraceContext }).ctx = ctx;
+            const result = await originalMethod.apply(this, args as []);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+          } finally {
+            // Restore original ctx
+            if (originalCtx === undefined) {
+              delete (this as { ctx?: TraceContext }).ctx;
+            } else {
+              (this as { ctx?: TraceContext }).ctx = originalCtx;
+            }
+          }
+        } catch (error) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error instanceof Error ? error.message : 'Unknown error',
+          });
+          span.recordException(
+            error instanceof Error ? error : new Error(String(error)),
+          );
+          throw error;
+        } finally {
+          span.end();
+        }
+      });
+    } as T;
+  };
+}
+
+// Re-export types for convenience
+
+export { type TraceContext, type TracingOptions } from './functional';

package/src/env-config.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  resolveOtelEnv,
+  parseResourceAttributes,
+  parseOtlpHeaders,
+  envToConfig,
+  resolveConfigFromEnv,
+} from './env-config';
+
+describe('env-config', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // Reset environment before each test
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    // Restore original environment
+    process.env = originalEnv;
+  });
+
+  describe('resolveOtelEnv', () => {
+    it('should resolve standard OTEL env vars', () => {
+      process.env.OTEL_SERVICE_NAME = 'test-service';
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://localhost:4318';
+      process.env.OTEL_EXPORTER_OTLP_PROTOCOL = 'http';
+
+      const env = resolveOtelEnv();
+
+      expect(env.OTEL_SERVICE_NAME).toBe('test-service');
+      expect(env.OTEL_EXPORTER_OTLP_ENDPOINT).toBe('http://localhost:4318');
+      expect(env.OTEL_EXPORTER_OTLP_PROTOCOL).toBe('http');
+    });
+
+    it('should return undefined for unset env vars', () => {
+      const env = resolveOtelEnv();
+
+      expect(env.OTEL_SERVICE_NAME).toBeUndefined();
+      expect(env.OTEL_EXPORTER_OTLP_ENDPOINT).toBeUndefined();
+    });
+
+    it('should validate protocol enum', () => {
+      process.env.OTEL_EXPORTER_OTLP_PROTOCOL = 'grpc';
+      const env = resolveOtelEnv();
+      expect(env.OTEL_EXPORTER_OTLP_PROTOCOL).toBe('grpc');
+    });
+  });
+
+  describe('parseResourceAttributes', () => {
+    it('should parse comma-separated key=value pairs', () => {
+      const input = 'service.version=1.0.0,deployment.environment=production';
+      const result = parseResourceAttributes(input);
+
+      expect(result).toEqual({
+        'service.version': '1.0.0',
+        'deployment.environment': 'production',
+      });
+    });
+
+    it('should handle single attribute', () => {
+      const result = parseResourceAttributes('team=backend');
+      expect(result).toEqual({ team: 'backend' });
+    });
+
+    it('should handle empty string', () => {
+      expect(parseResourceAttributes('')).toEqual({});
+      expect(parseResourceAttributes('   ')).toEqual({});
+    });
+
+    it('should handle undefined', () => {
+      expect(parseResourceAttributes()).toEqual({});
+    });
+
+    it('should skip invalid pairs without =', () => {
+      const result = parseResourceAttributes('valid=value,invalid,another=ok');
+      expect(result).toEqual({
+        valid: 'value',
+        another: 'ok',
+      });
+    });
+
+    it('should handle whitespace around keys and values', () => {
+      const result = parseResourceAttributes(' key1 = value1 , key2 = value2 ');
+      expect(result).toEqual({
+        key1: 'value1',
+        key2: 'value2',
+      });
+    });
+
+    it('should skip empty pairs', () => {
+      const result = parseResourceAttributes('key1=value1,,key2=value2');
+      expect(result).toEqual({
+        key1: 'value1',
+        key2: 'value2',
+      });
+    });
+
+    it('should handle values with = in them (takes first = as delimiter)', () => {
+      const result = parseResourceAttributes('key=value=with=equals');
+      expect(result).toEqual({
+        key: 'value=with=equals',
+      });
+    });
+  });
+
+  describe('parseOtlpHeaders', () => {
+    it('should parse comma-separated header pairs', () => {
+      const input = 'api-key=secret123,x-custom-header=value';
+      const result = parseOtlpHeaders(input);
+
+      expect(result).toEqual({
+        'api-key': 'secret123',
+        'x-custom-header': 'value',
+      });
+    });
+
+    it('should handle single header', () => {
+      const result = parseOtlpHeaders('authorization=Bearer token');
+      expect(result).toEqual({ authorization: 'Bearer token' });
+    });
+
+    it('should handle empty string', () => {
+      expect(parseOtlpHeaders('')).toEqual({});
+      expect(parseOtlpHeaders('   ')).toEqual({});
+    });
+
+    it('should handle undefined', () => {
+      expect(parseOtlpHeaders()).toEqual({});
+    });
+
+    it('should skip invalid pairs', () => {
+      const result = parseOtlpHeaders('valid=value,invalid,another=ok');
+      expect(result).toEqual({
+        valid: 'value',
+        another: 'ok',
+      });
+    });
+
+    it('should handle whitespace', () => {
+      const result = parseOtlpHeaders(' key1 = value1 , key2 = value2 ');
+      expect(result).toEqual({
+        key1: 'value1',
+        key2: 'value2',
+      });
+    });
+  });
+
+  describe('envToConfig', () => {
+    it('should map OTEL_SERVICE_NAME to service', () => {
+      const config = envToConfig({
+        OTEL_SERVICE_NAME: 'test-service',
+      });
+
+      expect(config.service).toBe('test-service');
+    });
+
+    it('should map OTEL_EXPORTER_OTLP_ENDPOINT to endpoint', () => {
+      const config = envToConfig({
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'http://localhost:4318',
+      });
+
+      expect(config.endpoint).toBe('http://localhost:4318');
+    });
+
+    it('should map OTEL_EXPORTER_OTLP_PROTOCOL to protocol', () => {
+      const config = envToConfig({
+        OTEL_EXPORTER_OTLP_PROTOCOL: 'grpc',
+      });
+
+      expect(config.protocol).toBe('grpc');
+    });
+
+    it('should parse OTEL_EXPORTER_OTLP_HEADERS', () => {
+      const config = envToConfig({
+        OTEL_EXPORTER_OTLP_HEADERS: 'api-key=secret,x-custom=value',
+      });
+
+      expect(config.otlpHeaders).toEqual({
+        'api-key': 'secret',
+        'x-custom': 'value',
+      });
+    });
+
+    it('should parse OTEL_RESOURCE_ATTRIBUTES', () => {
+      const config = envToConfig({
+        OTEL_RESOURCE_ATTRIBUTES:
+          'service.version=1.0.0,deployment.environment=prod',
+      });
+
+      expect(config.resourceAttributes).toEqual({
+        'service.version': '1.0.0',
+        'deployment.environment': 'prod',
+      });
+    });
+
+    it('should return empty config for no env vars', () => {
+      const config = envToConfig({});
+      expect(config).toEqual({});
+    });
+  });
+
+  describe('resolveConfigFromEnv', () => {
+    it('should return config from env vars', () => {
+      process.env.OTEL_SERVICE_NAME = 'test-service';
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://localhost:4318';
+
+      const config = resolveConfigFromEnv();
+
+      expect(config.service).toBe('test-service');
+      expect(config.endpoint).toBe('http://localhost:4318');
+    });
+
+    it('should work with no env vars set', () => {
+      const config = resolveConfigFromEnv();
+      expect(config).toEqual({});
+    });
+
+    it('should parse complex real-world scenario', () => {
+      process.env.OTEL_SERVICE_NAME = 'my-api';
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT = 'https://api.honeycomb.io';
+      process.env.OTEL_EXPORTER_OTLP_HEADERS =
+        'x-honeycomb-team=abc123,x-honeycomb-dataset=production';
+      process.env.OTEL_RESOURCE_ATTRIBUTES =
+        'service.version=1.2.3,deployment.environment=production,team=backend';
+      process.env.OTEL_EXPORTER_OTLP_PROTOCOL = 'http';
+
+      const config = resolveConfigFromEnv();
+
+      expect(config).toEqual({
+        service: 'my-api',
+        endpoint: 'https://api.honeycomb.io',
+        protocol: 'http',
+        otlpHeaders: {
+          'x-honeycomb-team': 'abc123',
+          'x-honeycomb-dataset': 'production',
+        },
+        resourceAttributes: {
+          'service.version': '1.2.3',
+          'deployment.environment': 'production',
+          team: 'backend',
+        },
+      });
+    });
+  });
+});

package/src/env-config.ts

@@ -0,0 +1,158 @@
+import { resolve } from 'node-env-resolver';
+import { string, url, optional } from 'node-env-resolver/validators';
+
+/**
+ * Standard OpenTelemetry environment variables
+ */
+export interface OtelEnvVars {
+  OTEL_SERVICE_NAME?: string;
+  OTEL_EXPORTER_OTLP_ENDPOINT?: string;
+  OTEL_EXPORTER_OTLP_HEADERS?: string;
+  OTEL_RESOURCE_ATTRIBUTES?: string;
+  OTEL_EXPORTER_OTLP_PROTOCOL?: 'http' | 'grpc';
+}
+
+/**
+ * Parsed resource attributes as key-value pairs
+ */
+export interface ResourceAttributes {
+  [key: string]: string;
+}
+
+/**
+ * Parsed OTLP headers as key-value pairs
+ */
+export interface OtlpHeaders {
+  [key: string]: string;
+}
+
+/**
+ * Environment-resolved configuration (subset of AutotelConfig)
+ * Defined locally to avoid circular dependency with init.ts
+ */
+export interface EnvConfig {
+  service?: string;
+  endpoint?: string;
+  protocol?: 'http' | 'grpc';
+  otlpHeaders?: Record<string, string>;
+  resourceAttributes?: Record<string, string>;
+}
+
+/**
+ * Resolve OpenTelemetry environment variables using node-env-resolver
+ */
+export function resolveOtelEnv(): OtelEnvVars {
+  return resolve({
+    OTEL_SERVICE_NAME: string({ optional: true }),
+    OTEL_EXPORTER_OTLP_ENDPOINT: url({ optional: true }),
+    OTEL_EXPORTER_OTLP_HEADERS: string({ optional: true }),
+    OTEL_RESOURCE_ATTRIBUTES: string({ optional: true }),
+    OTEL_EXPORTER_OTLP_PROTOCOL: optional(['http', 'grpc'] as const),
+  });
+}
+
+/**
+ * Parse OTEL_RESOURCE_ATTRIBUTES from comma-separated key=value pairs
+ * Example: "service.version=1.0.0,deployment.environment=production"
+ */
+export function parseResourceAttributes(
+  input: string | undefined,
+): ResourceAttributes {
+  if (!input || input.trim() === '') {
+    return {};
+  }
+
+  const attributes: ResourceAttributes = {};
+  const pairs = input.split(',');
+
+  for (const pair of pairs) {
+    const trimmedPair = pair.trim();
+    if (!trimmedPair) continue;
+
+    const equalIndex = trimmedPair.indexOf('=');
+    if (equalIndex === -1) {
+      // Invalid format, skip this pair
+      continue;
+    }
+
+    const key = trimmedPair.slice(0, equalIndex).trim();
+    const value = trimmedPair.slice(equalIndex + 1).trim();
+
+    if (key && value) {
+      attributes[key] = value;
+    }
+  }
+
+  return attributes;
+}
+
+/**
+ * Parse OTEL_EXPORTER_OTLP_HEADERS from comma-separated key=value pairs
+ * Example: "api-key=secret123,x-custom-header=value"
+ */
+export function parseOtlpHeaders(input: string | undefined): OtlpHeaders {
+  if (!input || input.trim() === '') {
+    return {};
+  }
+
+  const headers: OtlpHeaders = {};
+  const pairs = input.split(',');
+
+  for (const pair of pairs) {
+    const trimmedPair = pair.trim();
+    if (!trimmedPair) continue;
+
+    const equalIndex = trimmedPair.indexOf('=');
+    if (equalIndex === -1) {
+      // Invalid format, skip this pair
+      continue;
+    }
+
+    const key = trimmedPair.slice(0, equalIndex).trim();
+    const value = trimmedPair.slice(equalIndex + 1).trim();
+
+    if (key && value) {
+      headers[key] = value;
+    }
+  }
+
+  return headers;
+}
+
+/**
+ * Convert resolved environment variables to config
+ */
+export function envToConfig(env: OtelEnvVars): EnvConfig {
+  const config: EnvConfig = {};
+
+  if (env.OTEL_SERVICE_NAME) {
+    config.service = env.OTEL_SERVICE_NAME;
+  }
+
+  if (env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+    config.endpoint = env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  }
+
+  if (env.OTEL_EXPORTER_OTLP_PROTOCOL) {
+    config.protocol = env.OTEL_EXPORTER_OTLP_PROTOCOL;
+  }
+
+  if (env.OTEL_EXPORTER_OTLP_HEADERS) {
+    config.otlpHeaders = parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS);
+  }
+
+  const resourceAttrs = parseResourceAttributes(env.OTEL_RESOURCE_ATTRIBUTES);
+  if (Object.keys(resourceAttrs).length > 0) {
+    config.resourceAttributes = resourceAttrs;
+  }
+
+  return config;
+}
+
+/**
+ * Main function to resolve config from environment variables
+ */
+export function resolveConfigFromEnv(): EnvConfig {
+  const env = resolveOtelEnv();
+  return envToConfig(env);
+}