autotel-backends 2.12.33 → 2.12.34

package/src/google-cloud.ts

@@ -1,259 +0,0 @@
-/**
- * Google Cloud preset for autotel
- *
- * Sends traces (and optionally metrics) to Google Cloud Observability via the
- * Telemetry (OTLP) API. Uses Application Default Credentials (ADC) for auth.
- *
- * @example Direct export to GCP (with google-auth-library)
- * ```typescript
- * import { init } from 'autotel';
- * import { createGoogleCloudConfig } from 'autotel-backends/google-cloud';
- *
- * init(createGoogleCloudConfig({
- *   projectId: process.env.GOOGLE_CLOUD_PROJECT!,
- *   service: 'my-app',
- * }));
- * ```
- *
- * @example Via OpenTelemetry Collector (no auth in app)
- * ```typescript
- * init(createGoogleCloudConfig({
- *   projectId: process.env.GOOGLE_CLOUD_PROJECT!,
- *   service: 'my-app',
- *   useCollector: true,
- *   collectorEndpoint: 'http://localhost:4318',
- * }));
- * ```
- */
-
-import { createRequire } from 'node:module';
-import type { AutotelConfig } from 'autotel';
-
-/** Minimal SpanExporter-compatible interface (avoids @opentelemetry/sdk-trace-base peer at build time). */
-interface SpanExporterLike {
-  export(
-    spans: unknown[],
-    resultCallback: (result: { code: number; error?: Error }) => void,
-  ): void | Promise<void>;
-  forceFlush?(): Promise<void>;
-  shutdown?(): Promise<void>;
-}
-
-/** Default Telemetry API base URL (OTLP). */
-const DEFAULT_ENDPOINT = 'https://telemetry.googleapis.com';
-
-/**
- * Configuration options for Google Cloud preset
- */
-export interface GoogleCloudPresetConfig {
-  /**
-   * Google Cloud project ID (required for direct export).
-   * Used for quota and resource attribution. Set GOOGLE_CLOUD_PROJECT or
-   * GOOGLE_APPLICATION_CREDENTIALS for ADC.
-   *
-   * @default process.env.GOOGLE_CLOUD_PROJECT
-   */
-  projectId: string;
-
-  /**
-   * Service name (required).
-   * Appears as service.name in Cloud Trace and Monitoring.
-   */
-  service: string;
-
-  /**
-   * Deployment environment (e.g., 'production', 'staging').
-   *
-   * @default process.env.NODE_ENV || 'development'
-   */
-  environment?: string;
-
-  /**
-   * Service version for deployment tracking.
-   *
-   * @default process.env.GCP_VERSION || process.env.VERSION
-   */
-  version?: string;
-
-  /**
-   * Use an OpenTelemetry Collector instead of exporting directly to GCP.
-   * When true, the app sends OTLP to collectorEndpoint; the Collector
-   * handles authentication to the Telemetry API. No google-auth-library needed.
-   *
-   * @default false
-   */
-  useCollector?: boolean;
-
-  /**
-   * Collector OTLP endpoint (when useCollector is true).
-   *
-   * @default 'http://localhost:4318'
-   */
-  collectorEndpoint?: string;
-
-  /**
-   * Telemetry API base URL (when useCollector is false).
-   * Only override for testing or special endpoints.
-   *
-   * @default 'https://telemetry.googleapis.com'
-   */
-  endpoint?: string;
-}
-
-/**
- * Create an autotel configuration for Google Cloud Observability (Telemetry API).
- *
- * - With useCollector: false (default), exports directly to the Telemetry API
- *   using Application Default Credentials. Requires optional peer dependency
- *   google-auth-library for auth. Install: pnpm add google-auth-library
- *
- * - With useCollector: true, sends OTLP to a local Collector; the Collector
- *   forwards to GCP with ADC. No google-auth-library needed in the app.
- *
- * @param config - Google Cloud preset options
- * @returns AutotelConfig ready to pass to init()
- */
-export function createGoogleCloudConfig(
-  config: GoogleCloudPresetConfig,
-): AutotelConfig {
-  const {
-    projectId,
-    service,
-    environment,
-    version,
-    useCollector = false,
-    collectorEndpoint = 'http://localhost:4318',
-    endpoint = DEFAULT_ENDPOINT,
-  } = config;
-
-  if (!projectId) {
-    throw new Error(
-      'Google Cloud projectId is required. Set it or use process.env.GOOGLE_CLOUD_PROJECT.',
-    );
-  }
-
-  const baseConfig: AutotelConfig = {
-    service,
-    environment,
-    version,
-  };
-
-  if (useCollector) {
-    return {
-      ...baseConfig,
-      endpoint: collectorEndpoint,
-      // x-goog-user-project for quota when Collector forwards to GCP
-      headers: { 'x-goog-user-project': projectId },
-    };
-  }
-
-  // Direct export: need ADC via google-auth-library
-  try {
-    const userRequire = createRequire(process.cwd() + '/package.json');
-    const { GoogleAuth } = userRequire('google-auth-library');
-    const { OTLPTraceExporter } = userRequire(
-      '@opentelemetry/exporter-trace-otlp-http',
-    );
-
-    const tracesUrl = `${endpoint}/v1/traces`;
-    const auth = new GoogleAuth({
-      scopes: ['https://www.googleapis.com/auth/cloud-platform'],
-    });
-
-    const gcpTraceExporter = createGcpAuthTraceExporter(
-      tracesUrl,
-      projectId,
-      auth,
-      OTLPTraceExporter,
-    );
-
-    return {
-      ...baseConfig,
-      // Structurally compatible with SpanExporter from @opentelemetry/sdk-trace-base
-      spanExporters: [
-        gcpTraceExporter as NonNullable<AutotelConfig['spanExporters']>[number],
-      ],
-    };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (
-      message.includes('google-auth-library') ||
-      message.includes('Cannot find module')
-    ) {
-      throw new Error(
-        'Direct export to Google Cloud requires google-auth-library. ' +
-          'Install it: pnpm add google-auth-library. ' +
-          'Or use useCollector: true and run an OpenTelemetry Collector with GCP auth.',
-        { cause: error },
-      );
-    }
-    throw error;
-  }
-}
-
-/** Minimal auth client: getClient() returns a client with getAccessToken(). */
-interface GoogleAuthLike {
-  getClient(): Promise<{ getAccessToken(): Promise<{ token: string | null }> }>;
-}
-
-type OTLPTraceExporterCtor = new (config: {
-  url: string;
-  headers?: Record<string, string>;
-}) => SpanExporterLike;
-
-function createGcpAuthTraceExporter(
-  url: string,
-  projectId: string,
-  auth: GoogleAuthLike,
-  OTLPTraceExporterCtor: OTLPTraceExporterCtor,
-): SpanExporterLike {
-  return new GcpAuthSpanExporter(url, projectId, auth, OTLPTraceExporterCtor);
-}
-
-class GcpAuthSpanExporter implements SpanExporterLike {
-  constructor(
-    private readonly url: string,
-    private readonly projectId: string,
-    private readonly auth: GoogleAuthLike,
-    private readonly OTLPTraceExporterCtor: OTLPTraceExporterCtor,
-  ) {}
-
-  async export(
-    spans: unknown[],
-    resultCallback: (result: { code: number; error?: Error }) => void,
-  ): Promise<void> {
-    try {
-      const client = await this.auth.getClient();
-      const tokenResponse = await client.getAccessToken();
-      const token = tokenResponse.token;
-      if (!token) {
-        resultCallback({
-          code: 1,
-          error: new Error('No access token from ADC'),
-        });
-        return;
-      }
-      const exporter = new this.OTLPTraceExporterCtor({
-        url: this.url,
-        headers: {
-          Authorization: `Bearer ${token}`,
-          'x-goog-user-project': this.projectId,
-        },
-      });
-      exporter.export(spans, resultCallback);
-    } catch (error) {
-      resultCallback({
-        code: 1,
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-    }
-  }
-
-  forceFlush(): Promise<void> {
-    return Promise.resolve();
-  }
-
-  shutdown(): Promise<void> {
-    return Promise.resolve();
-  }
-}

package/src/grafana.ts

@@ -1,177 +0,0 @@
-/**
- * Grafana Cloud preset for autotel
- *
- * Provides a simplified configuration helper for sending traces, metrics,
- * and logs to Grafana Cloud via the OTLP gateway.
- *
- * Get your endpoint and headers from:
- * Grafana Cloud Portal → your stack → Connections → OpenTelemetry → Configure
- *
- * @example
- * ```typescript
- * import { init } from 'autotel';
- * import { createGrafanaConfig } from 'autotel-backends/grafana';
- *
- * init(createGrafanaConfig({
- *   endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
- *   headers: process.env.OTEL_EXPORTER_OTLP_HEADERS,
- *   service: 'my-app',
- *   enableLogs: true,
- * }));
- * ```
- */
-
-import { createRequire } from 'node:module';
-import type { AutotelConfig } from 'autotel';
-import type { LogRecordProcessor } from '@opentelemetry/sdk-logs';
-
-// See packages/autotel/src/node-require.ts for why the __filename fallback
-// is necessary alongside import.meta.url.
-declare const __filename: string | undefined;
-
-/**
- * Configuration options for Grafana Cloud preset
- */
-export interface GrafanaPresetConfig {
-  /**
-   * OTLP gateway endpoint (required).
-   * From Grafana Cloud: Stack → Connections → OpenTelemetry → Configure.
-   * Example: https://otlp-gateway-prod-gb-south-1.grafana.net/otlp
-   */
-  endpoint: string;
-
-  /**
-   * OTLP authentication headers.
-   * From the same Configure tile; usually Basic auth.
-   * Example: "Authorization=Basic%20BASE64_INSTANCE_ID_AND_TOKEN"
-   * or object: { Authorization: 'Basic ...' }
-   */
-  headers?: string | Record<string, string>;
-
-  /**
-   * Service name (required).
-   * Appears in Tempo, Mimir, and Loki as service_name.
-   */
-  service: string;
-
-  /**
-   * Deployment environment (e.g. 'production', 'staging').
-   *
-   * @default process.env.NODE_ENV || 'development'
-   */
-  environment?: string;
-
-  /**
-   * Service version for deployment tracking.
-   *
-   * @default process.env.OTEL_SERVICE_VERSION
-   */
-  version?: string;
-
-  /**
-   * Enable log export to Grafana Cloud (Loki) via OTLP.
-   * When true, configures logRecordProcessors so OTel Logs API records are exported.
-   *
-   * @default true
-   */
-  enableLogs?: boolean;
-
-  /**
-   * Custom log record processors (advanced).
-   * Overrides the default OTLP log processor when enableLogs is true.
-   */
-  logRecordProcessors?: LogRecordProcessor[];
-}
-
-function normalizeHeaders(
-  headers: string | Record<string, string> | undefined,
-): Record<string, string> | undefined {
-  if (!headers) return undefined;
-  if (typeof headers === 'object') return headers;
-  const out: Record<string, string> = {};
-  for (const pair of headers.split(',')) {
-    const [key, ...valueParts] = pair.split('=');
-    if (key && valueParts.length > 0) {
-      let value = valueParts.join('=').trim();
-      value = value.replaceAll('%20', ' ');
-      out[key.trim()] = value;
-    }
-  }
-  return Object.keys(out).length > 0 ? out : undefined;
-}
-
-/**
- * Create an autotel configuration for Grafana Cloud OTLP.
- *
- * Sends traces (Tempo), metrics (Mimir), and optionally logs (Loki) to the
- * Grafana Cloud OTLP gateway. Endpoint and headers come from the stack's
- * Connections → OpenTelemetry → Configure tile.
- *
- * @param config - Grafana Cloud configuration options
- * @returns AutotelConfig ready to pass to init()
- */
-export function createGrafanaConfig(
-  config: GrafanaPresetConfig,
-): AutotelConfig {
-  const {
-    endpoint,
-    headers: headersInput,
-    service,
-    environment,
-    version,
-    enableLogs = true,
-    logRecordProcessors,
-  } = config;
-
-  if (!endpoint) {
-    throw new Error(
-      'Grafana Cloud endpoint is required. Get it from: Grafana Cloud → your stack → Connections → OpenTelemetry → Configure',
-    );
-  }
-
-  const headers = normalizeHeaders(headersInput);
-  const base = endpoint.replace(/\/v1\/(traces|metrics|logs)$/, '');
-  const logsUrl = `${base}${base.endsWith('/') ? '' : '/'}v1/logs`;
-
-  const result: AutotelConfig = {
-    service,
-    environment,
-    version,
-    endpoint,
-    headers,
-    metrics: true,
-  };
-
-  if (enableLogs) {
-    if (logRecordProcessors) {
-      result.logRecordProcessors = logRecordProcessors;
-    } else {
-      try {
-        const pkgRequire = createRequire(
-          typeof __filename === 'string' ? __filename : import.meta.url,
-        );
-        const { BatchLogRecordProcessor } = pkgRequire(
-          '@opentelemetry/sdk-logs',
-        );
-        const { OTLPLogExporter } = pkgRequire(
-          '@opentelemetry/exporter-logs-otlp-http',
-        );
-        result.logRecordProcessors = [
-          new BatchLogRecordProcessor(
-            new OTLPLogExporter({
-              url: logsUrl,
-              headers,
-            }),
-          ),
-        ];
-      } catch {
-        throw new Error(
-          'Log export requires @opentelemetry/sdk-logs and @opentelemetry/exporter-logs-otlp-http. ' +
-            'Install them or set enableLogs: false.',
-        );
-      }
-    }
-  }
-
-  return result;
-}

package/src/honeycomb.test.ts

@@ -1,243 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { createHoneycombConfig } from './honeycomb';
-
-describe('createHoneycombConfig()', () => {
-  describe('validation', () => {
-    it('should throw if apiKey is missing', () => {
-      expect(() => {
-        createHoneycombConfig({
-          // @ts-expect-error - testing missing apiKey
-          service: 'test-service',
-        });
-      }).toThrow('Honeycomb API key is required');
-    });
-
-    it('should throw if apiKey is empty string', () => {
-      expect(() => {
-        createHoneycombConfig({
-          apiKey: '',
-          service: 'test-service',
-        });
-      }).toThrow('Honeycomb API key is required');
-    });
-  });
-
-  describe('basic configuration', () => {
-    it('should return minimal config with apiKey and service', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-api-key',
-        service: 'my-service',
-      });
-
-      expect(config).toMatchObject({
-        service: 'my-service',
-        protocol: 'grpc',
-        endpoint: 'api.honeycomb.io:443',
-        headers: {
-          'x-honeycomb-team': 'test-api-key',
-        },
-      });
-    });
-
-    it('should use gRPC protocol by default', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-api-key',
-        service: 'my-service',
-      });
-
-      expect(config.protocol).toBe('grpc');
-    });
-
-    it('should use default Honeycomb endpoint', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-api-key',
-        service: 'my-service',
-      });
-
-      expect(config.endpoint).toBe('api.honeycomb.io:443');
-    });
-  });
-
-  describe('headers', () => {
-    it('should set x-honeycomb-team header with API key', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'my-secret-key',
-        service: 'test-service',
-      });
-
-      expect(config.headers).toMatchObject({
-        'x-honeycomb-team': 'my-secret-key',
-      });
-    });
-
-    it('should add x-honeycomb-dataset header when dataset is specified', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        dataset: 'production',
-      });
-
-      expect(config.headers).toMatchObject({
-        'x-honeycomb-team': 'test-key',
-        'x-honeycomb-dataset': 'production',
-      });
-    });
-
-    it('should add x-honeycomb-samplerate header when sampleRate is specified', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        sampleRate: 10,
-      });
-
-      expect(config.headers).toMatchObject({
-        'x-honeycomb-team': 'test-key',
-        'x-honeycomb-samplerate': '10',
-      });
-    });
-
-    it('should include all headers when dataset and sampleRate are specified', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        dataset: 'my-dataset',
-        sampleRate: 100,
-      });
-
-      expect(config.headers).toMatchObject({
-        'x-honeycomb-team': 'test-key',
-        'x-honeycomb-dataset': 'my-dataset',
-        'x-honeycomb-samplerate': '100',
-      });
-    });
-
-    it('should convert sampleRate to string', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        sampleRate: 50,
-      });
-
-      expect(typeof config.headers?.['x-honeycomb-samplerate']).toBe('string');
-      expect(config.headers?.['x-honeycomb-samplerate']).toBe('50');
-    });
-  });
-
-  describe('environment and version', () => {
-    it('should include environment when specified', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        environment: 'production',
-      });
-
-      expect(config.environment).toBe('production');
-    });
-
-    it('should include version when specified', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        version: '2.1.0',
-      });
-
-      expect(config.version).toBe('2.1.0');
-    });
-
-    it('should include both environment and version', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        environment: 'staging',
-        version: '1.5.3',
-      });
-
-      expect(config.environment).toBe('staging');
-      expect(config.version).toBe('1.5.3');
-    });
-  });
-
-  describe('custom endpoint', () => {
-    it('should allow custom endpoint', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        endpoint: 'custom.honeycomb.io:8443',
-      });
-
-      expect(config.endpoint).toBe('custom.honeycomb.io:8443');
-    });
-
-    it('should allow EU endpoint', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'test-service',
-        endpoint: 'api.eu1.honeycomb.io:443',
-      });
-
-      expect(config.endpoint).toBe('api.eu1.honeycomb.io:443');
-    });
-  });
-
-  describe('complete configuration', () => {
-    it('should handle all options together', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'complete-test-key',
-        service: 'complete-service',
-        dataset: 'complete-dataset',
-        environment: 'production',
-        version: '3.2.1',
-        endpoint: 'custom.endpoint.io:9000',
-        sampleRate: 25,
-      });
-
-      expect(config).toEqual({
-        service: 'complete-service',
-        environment: 'production',
-        version: '3.2.1',
-        protocol: 'grpc',
-        endpoint: 'custom.endpoint.io:9000',
-        headers: {
-          'x-honeycomb-team': 'complete-test-key',
-          'x-honeycomb-dataset': 'complete-dataset',
-          'x-honeycomb-samplerate': '25',
-        },
-      });
-    });
-  });
-
-  describe('real-world scenarios', () => {
-    it('should configure for classic Honeycomb account with dataset', () => {
-      const config = createHoneycombConfig({
-        apiKey: process.env.HONEYCOMB_API_KEY || 'test-key',
-        service: 'my-app',
-        dataset: 'production',
-        environment: 'production',
-      });
-
-      expect(config.headers).toHaveProperty('x-honeycomb-dataset');
-      expect(config.protocol).toBe('grpc');
-    });
-
-    it('should configure for modern Honeycomb account without dataset', () => {
-      const config = createHoneycombConfig({
-        apiKey: process.env.HONEYCOMB_API_KEY || 'test-key',
-        service: 'my-app',
-        environment: 'production',
-      });
-
-      expect(config.headers).not.toHaveProperty('x-honeycomb-dataset');
-      expect(config.protocol).toBe('grpc');
-    });
-
-    it('should configure with head-based sampling', () => {
-      const config = createHoneycombConfig({
-        apiKey: 'test-key',
-        service: 'high-volume-app',
-        sampleRate: 100, // Sample 1% of traces
-      });
-
-      expect(config.headers).toHaveProperty('x-honeycomb-samplerate', '100');
-    });
-  });
-});