autotel-backends 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Jag Reehal 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,284 @@
+# Autotel Backends
+
+Vendor backend configurations for [Autotel](../autotel) - simplified setup helpers for popular observability platforms.
+
+## What are Backends?
+
+**Backends** are vendor-specific configuration helpers that simplify setting up Autotel with observability platforms like Honeycomb, Datadog, New Relic, etc.
+
+They handle:
+
+- Correct endpoint URLs for each vendor
+- Authentication headers and API key formats
+- Protocol selection (gRPC vs HTTP)
+- Region-specific configurations
+- Best practice defaults
+
+### Backends vs Plugins
+
+| Package              | Purpose                                               | Examples                    |
+| -------------------- | ----------------------------------------------------- | --------------------------- |
+| **autotel-backends** | Configure **where** telemetry goes (outputs)          | Honeycomb, Datadog, Grafana |
+| **autotel-plugins**  | Instrument **libraries** to create telemetry (inputs) | Drizzle ORM, custom SDKs    |
+
+**Think of it this way**: Plugins create the data, backends send it somewhere.
+
+## Installation
+
+```bash
+npm install autotel autotel-backends
+```
+
+## Quick Start
+
+### Honeycomb
+
+```typescript
+import { init } from 'autotel';
+import { createHoneycombConfig } from 'autotel-backends/honeycomb';
+
+init(
+  createHoneycombConfig({
+    apiKey: process.env.HONEYCOMB_API_KEY!,
+    service: 'my-app',
+  }),
+);
+```
+
+### Datadog
+
+```typescript
+import { init } from 'autotel';
+import { createDatadogConfig } from 'autotel-backends/datadog';
+
+// Direct cloud ingestion (serverless, edge)
+init(
+  createDatadogConfig({
+    apiKey: process.env.DATADOG_API_KEY!,
+    service: 'my-lambda',
+  }),
+);
+
+// Or use local Datadog Agent (Kubernetes, long-running services)
+init(
+  createDatadogConfig({
+    service: 'my-api',
+    useAgent: true,
+  }),
+);
+```
+
+## Available Backends
+
+### 🍯 Honeycomb
+
+[Honeycomb](https://honeycomb.io) provides powerful distributed tracing and observability.
+
+```typescript
+import { createHoneycombConfig } from 'autotel-backends/honeycomb';
+
+init(
+  createHoneycombConfig({
+    apiKey: process.env.HONEYCOMB_API_KEY!,
+    service: 'my-app',
+    environment: 'production',
+    version: '1.0.0',
+    dataset: 'my-dataset', // Optional: for classic accounts
+  }),
+);
+```
+
+**Features**:
+
+- Auto-configures gRPC protocol (Honeycomb's preferred)
+- Supports both classic datasets and modern service-based routing
+- Environment and version tagging
+- Head-based sampling configuration
+
+[View full Honeycomb configuration options →](./src/honeycomb.ts)
+
+### 🐕 Datadog
+
+[Datadog](https://datadoghq.com) provides comprehensive APM, infrastructure monitoring, and logs.
+
+```typescript
+import { createDatadogConfig } from 'autotel-backends/datadog';
+
+// Cloud ingestion (best for serverless/edge)
+init(
+  createDatadogConfig({
+    apiKey: process.env.DATADOG_API_KEY!,
+    site: 'datadoghq.com', // or 'datadoghq.eu', 'us3.datadoghq.com', etc.
+    service: 'my-lambda',
+    environment: 'production',
+    enableLogs: true, // Optional: also send logs
+  }),
+);
+
+// Agent-based (best for Kubernetes/VMs)
+init(
+  createDatadogConfig({
+    service: 'my-api',
+    useAgent: true,
+    agentHost: 'localhost', // or 'datadog-agent.default.svc.cluster.local'
+    agentPort: 4318,
+  }),
+);
+```
+
+**Features**:
+
+- Direct cloud ingestion OR local agent
+- Multi-region support (US1, US3, US5, EU, AP1, FedRAMP)
+- Unified service tagging (service, env, version)
+- Optional log export via OTLP
+- Kubernetes-friendly agent configuration
+
+[View full Datadog configuration options →](./src/datadog.ts)
+
+## Why Use Backend Configs?
+
+### Without backend configs (manual):
+
+```typescript
+import { init } from 'autotel';
+
+init({
+  service: 'my-app',
+  endpoint: 'https://api.honeycomb.io:443',
+  protocol: 'grpc',
+  otlpHeaders: {
+    'x-honeycomb-team': process.env.HONEYCOMB_API_KEY!,
+    'x-honeycomb-dataset': 'production',
+  },
+  environment: 'production',
+  version: '1.0.0',
+});
+```
+
+### With backend configs:
+
+```typescript
+import { init } from 'autotel';
+import { createHoneycombConfig } from 'autotel-backends/honeycomb';
+
+init(
+  createHoneycombConfig({
+    apiKey: process.env.HONEYCOMB_API_KEY!,
+    service: 'my-app',
+    environment: 'production',
+    version: '1.0.0',
+  }),
+);
+```
+
+**Benefits**:
+
+- Less code, fewer mistakes
+- Vendor best practices built-in
+- Validated configurations
+- Easy to switch vendors
+
+## Using Environment Variables
+
+All backends work great with environment variables:
+
+```typescript
+import { createHoneycombConfig } from 'autotel-backends/honeycomb';
+
+init(
+  createHoneycombConfig({
+    apiKey: process.env.HONEYCOMB_API_KEY!,
+    service: process.env.SERVICE_NAME || 'my-app',
+    environment: process.env.NODE_ENV,
+  }),
+);
+```
+
+Or use Autotel's built-in env var support:
+
+```bash
+# .env
+OTEL_SERVICE_NAME=my-app
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=YOUR_API_KEY
+```
+
+```typescript
+import { init } from 'autotel';
+
+// Reads from env vars automatically
+init({});
+```
+
+## Migration from autotel/presets
+
+If you were using `autotel/presets/*`, migration is simple:
+
+**Before** (v1.x):
+
+```typescript
+import { createHoneycombConfig } from 'autotel/presets/honeycomb';
+```
+
+**After** (v2.x):
+
+```bash
+npm install autotel-backends
+```
+
+```typescript
+import { createHoneycombConfig } from 'autotel-backends/honeycomb';
+```
+
+The configuration options are **identical** - only the import path changed.
+
+## Philosophy
+
+Autotel follows the principle: **"Write once, observe everywhere"**.
+
+Backend configurations are:
+
+- **Optional**: Use raw `init()` config if you prefer
+- **Vendor-agnostic at core**: Keeping these separate maintains the vendor-neutral philosophy
+- **Best practices**: Configurations follow vendor recommendations
+- **Tree-shakeable**: Import only what you need
+
+## TypeScript
+
+Full type safety with TypeScript:
+
+```typescript
+import type {
+  HoneycombPresetConfig,
+  DatadogPresetConfig,
+} from 'autotel-backends';
+
+const honeycombConfig: HoneycombPresetConfig = {
+  apiKey: process.env.HONEYCOMB_API_KEY!,
+  service: 'my-app',
+};
+
+const datadogConfig: DatadogPresetConfig = {
+  apiKey: process.env.DATADOG_API_KEY!,
+  service: 'my-app',
+  site: 'datadoghq.com',
+};
+```
+
+## Contributing
+
+Want to add a new backend configuration? Please [open an issue](https://github.com/jagreehal/autotel/issues) to discuss.
+
+Popular backends we'd love to support:
+
+- Grafana Cloud
+- New Relic
+- Lightstep
+- Elastic APM
+- AWS X-Ray
+- Google Cloud Trace
+
+## License
+
+MIT

package/dist/datadog.d.ts

@@ -0,0 +1,160 @@
+import { AutotelConfig } from 'autotel';
+import { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+
+/**
+ * Datadog preset for autotel
+ *
+ * Provides a simplified configuration helper for Datadog integration
+ * with best practices built-in.
+ *
+ * @example Direct cloud ingestion (serverless, edge)
+ * ```typescript
+ * import { init } from 'autotel';
+ * import { createDatadogConfig } from 'autotel-backends/datadog';
+ *
+ * init(createDatadogConfig({
+ *   apiKey: process.env.DATADOG_API_KEY!,
+ *   service: 'my-lambda',
+ *   enableLogs: true,
+ * }));
+ * ```
+ *
+ * @example Local Datadog Agent (long-running services, Kubernetes)
+ * ```typescript
+ * import { init } from 'autotel';
+ * import { createDatadogConfig } from 'autotel-backends/datadog';
+ *
+ * init(createDatadogConfig({
+ *   service: 'my-api',
+ *   useAgent: true,  // No API key needed - Agent handles it
+ * }));
+ * ```
+ */
+
+/**
+ * Datadog site regions
+ */
+type DatadogSite = 'datadoghq.com' | 'datadoghq.eu' | 'us3.datadoghq.com' | 'us5.datadoghq.com' | 'ap1.datadoghq.com' | 'ddog-gov.com';
+/**
+ * Configuration options for Datadog preset
+ */
+interface DatadogPresetConfig {
+    /**
+     * Datadog API key (required for direct cloud ingestion).
+     * Not needed if using local Datadog Agent (useAgent: true).
+     *
+     * Get your API key from:
+     * https://app.datadoghq.com/organization-settings/api-keys
+     */
+    apiKey?: string;
+    /**
+     * Datadog site/region.
+     * Determines which Datadog intake endpoint to use.
+     *
+     * @default 'datadoghq.com' (US1)
+     */
+    site?: DatadogSite;
+    /**
+     * Service name (required).
+     * Appears in Datadog APM, Service Catalog, and all telemetry.
+     */
+    service: string;
+    /**
+     * Deployment environment (e.g., 'production', 'staging', 'development').
+     * Used for environment filtering in Datadog.
+     *
+     * @default process.env.DD_ENV || process.env.NODE_ENV || 'development'
+     */
+    environment?: string;
+    /**
+     * Service version for deployment tracking.
+     * Enables Deployment Tracking in Datadog APM.
+     *
+     * @default process.env.DD_VERSION || auto-detected from package.json
+     */
+    version?: string;
+    /**
+     * Enable log export to Datadog via OTLP.
+     * Requires peer dependencies: @opentelemetry/sdk-logs, @opentelemetry/exporter-logs-otlp-http
+     *
+     * @default false
+     */
+    enableLogs?: boolean;
+    /**
+     * Use local Datadog Agent instead of direct cloud ingestion.
+     *
+     * Benefits:
+     * - Lower egress costs (Agent aggregates locally)
+     * - Advanced features: trace-log correlation, multi-line logs, data scrubbing
+     * - 500+ integrations for enrichment
+     * - Infrastructure metrics collection
+     *
+     * Requires: Datadog Agent 7.35+ with OTLP enabled
+     *
+     * @default false
+     */
+    useAgent?: boolean;
+    /**
+     * Datadog Agent hostname (when useAgent: true).
+     *
+     * @default 'localhost'
+     */
+    agentHost?: string;
+    /**
+     * Datadog Agent OTLP port (when useAgent: true).
+     *
+     * @default 4318 (OTLP HTTP)
+     */
+    agentPort?: number;
+    /**
+     * Custom log record processors (advanced).
+     * Overrides the default log processor if enableLogs is true.
+     */
+    logRecordProcessors?: LogRecordProcessor[];
+}
+/**
+ * Create an autotel configuration optimized for Datadog.
+ *
+ * This preset handles:
+ * - Proper OTLP endpoint configuration (Agent vs direct ingestion)
+ *   - Direct: https://otlp.{site} → SDK appends /v1/traces, /v1/metrics, /v1/logs
+ *   - Agent: http://localhost:4318 (default)
+ * - Datadog API key authentication headers (direct ingestion only)
+ * - Unified service tagging (service, env, version)
+ * - Resource attribute best practices
+ * - Optional log export configuration
+ *
+ * @param config - Datadog-specific configuration options
+ * @returns AutotelConfig ready to pass to init()
+ *
+ * @example Simple cloud ingestion
+ * ```typescript
+ * init(createDatadogConfig({
+ *   apiKey: process.env.DATADOG_API_KEY!,
+ *   service: 'my-app',
+ * }));
+ * ```
+ *
+ * @example With logs and custom environment
+ * ```typescript
+ * init(createDatadogConfig({
+ *   apiKey: process.env.DATADOG_API_KEY!,
+ *   service: 'my-app',
+ *   environment: 'production',
+ *   version: '2.1.0',
+ *   enableLogs: true,
+ * }));
+ * ```
+ *
+ * @example Using local Datadog Agent
+ * ```typescript
+ * init(createDatadogConfig({
+ *   service: 'my-api',
+ *   useAgent: true,
+ *   agentHost: 'datadog-agent.default.svc.cluster.local', // Kubernetes
+ * }));
+ * ```
+ */
+declare function createDatadogConfig(config: DatadogPresetConfig): AutotelConfig;
+
+export { type DatadogPresetConfig, type DatadogSite, createDatadogConfig };

package/dist/datadog.js

@@ -0,0 +1,77 @@
+import { createRequire } from 'module';
+
+// src/datadog.ts
+function createDatadogConfig(config) {
+  const {
+    apiKey,
+    site = "datadoghq.com",
+    service,
+    environment,
+    version,
+    enableLogs = false,
+    useAgent = false,
+    agentHost = "localhost",
+    agentPort = 4318,
+    logRecordProcessors
+  } = config;
+  if (!useAgent && !apiKey) {
+    throw new Error(
+      "Datadog API key is required for direct cloud ingestion. Either provide apiKey or set useAgent: true to use local Datadog Agent."
+    );
+  }
+  const baseConfig = {
+    service,
+    environment,
+    version
+  };
+  if (useAgent) {
+    const agentEndpoint = `http://${agentHost}:${agentPort}`;
+    return {
+      ...baseConfig,
+      endpoint: agentEndpoint
+      // No API key or headers needed - Agent handles authentication
+    };
+  }
+  const otlpEndpoint = `https://otlp.${site}`;
+  const authHeaders = `dd-api-key=${apiKey}`;
+  const cloudConfig = {
+    ...baseConfig,
+    endpoint: otlpEndpoint,
+    otlpHeaders: authHeaders
+  };
+  if (enableLogs) {
+    if (logRecordProcessors) {
+      cloudConfig.logRecordProcessors = logRecordProcessors;
+    } else {
+      try {
+        const userRequire = createRequire(process.cwd() + "/package.json");
+        const { BatchLogRecordProcessor } = userRequire(
+          "@opentelemetry/sdk-logs"
+        );
+        const { OTLPLogExporter } = userRequire(
+          "@opentelemetry/exporter-logs-otlp-http"
+        );
+        cloudConfig.logRecordProcessors = [
+          new BatchLogRecordProcessor(
+            new OTLPLogExporter({
+              // Logs use /v1/logs path (SDK appends this to endpoint)
+              url: `${otlpEndpoint}/v1/logs`,
+              headers: {
+                "dd-api-key": apiKey
+              }
+            })
+          )
+        ];
+      } catch {
+        throw new Error(
+          "Log export requires peer dependencies: @opentelemetry/sdk-logs and @opentelemetry/exporter-logs-otlp-http. Install them with: npm install @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http"
+        );
+      }
+    }
+  }
+  return cloudConfig;
+}
+
+export { createDatadogConfig };
+//# sourceMappingURL=datadog.js.map
+//# sourceMappingURL=datadog.js.map

package/dist/datadog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/datadog.ts"],"names":[],"mappings":";;;AA+KO,SAAS,oBACd,MAAA,EACe;AACf,EAAA,MAAM;AAAA,IACJ,MAAA;AAAA,IACA,IAAA,GAAO,eAAA;AAAA,IACP,OAAA;AAAA,IACA,WAAA;AAAA,IACA,OAAA;AAAA,IACA,UAAA,GAAa,KAAA;AAAA,IACb,QAAA,GAAW,KAAA;AAAA,IACX,SAAA,GAAY,WAAA;AAAA,IACZ,SAAA,GAAY,IAAA;AAAA,IACZ;AAAA,GACF,GAAI,MAAA;AAGJ,EAAA,IAAI,CAAC,QAAA,IAAY,CAAC,MAAA,EAAQ;AACxB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AAEA,EAAA,MAAM,UAAA,GAA4B;AAAA,IAChC,OAAA;AAAA,IACA,WAAA;AAAA,IACA;AAAA,GACF;AAGA,EAAA,IAAI,QAAA,EAAU;AACZ,IAAA,MAAM,aAAA,GAAgB,CAAA,OAAA,EAAU,SAAS,CAAA,CAAA,EAAI,SAAS,CAAA,CAAA;AAEtD,IAAA,OAAO;AAAA,MACL,GAAG,UAAA;AAAA,MACH,QAAA,EAAU;AAAA;AAAA,KAEZ;AAAA,EACF;AAIA,EAAA,MAAM,YAAA,GAAe,gBAAgB,IAAI,CAAA,CAAA;AACzC,EAAA,MAAM,WAAA,GAAc,cAAc,MAAM,CAAA,CAAA;AAExC,EAAA,MAAM,WAAA,GAA6B;AAAA,IACjC,GAAG,UAAA;AAAA,IACH,QAAA,EAAU,YAAA;AAAA,IACV,WAAA,EAAa;AAAA,GACf;AAGA,EAAA,IAAI,UAAA,EAAY;AACd,IAAA,IAAI,mBAAA,EAAqB;AAEvB,MAAA,WAAA,CAAY,mBAAA,GAAsB,mBAAA;AAAA,IACpC,CAAA,MAAO;AAEL,MAAA,IAAI;AAGF,QAAA,MAAM,WAAA,GAAc,aAAA,CAAc,OAAA,CAAQ,GAAA,KAAQ,eAAe,CAAA;AAEjE,QAAA,MAAM,EAAE,yBAAwB,GAAI,WAAA;AAAA,UAClC;AAAA,SACF;AACA,QAAA,MAAM,EAAE,iBAAgB,GAAI,WAAA;AAAA,UAC1B;AAAA,SACF;AAEA,QAAA,WAAA,CAAY,mBAAA,GAAsB;AAAA,UAChC,IAAI,uBAAA;AAAA,YACF,IAAI,eAAA,CAAgB;AAAA;AAAA,cAElB,GAAA,EAAK,GAAG,YAAY,CAAA,QAAA,CAAA;AAAA,cACpB,OAAA,EAAS;AAAA,gBACP,YAAA,EAAc;AAAA;AAChB,aACD;AAAA;AACH,SACF;AAAA,MACF,CAAA,CAAA,MAAQ;AACN,QAAA,MAAM,IAAI,KAAA;AAAA,UACR;AAAA,SAEF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,WAAA;AACT","file":"datadog.js","sourcesContent":["/**\n * Datadog preset for autotel\n *\n * Provides a simplified configuration helper for Datadog integration\n * with best practices built-in.\n *\n * @example Direct cloud ingestion (serverless, edge)\n * ```typescript\n * import { init } from 'autotel';\n * import { createDatadogConfig } from 'autotel-backends/datadog';\n *\n * init(createDatadogConfig({\n *   apiKey: process.env.DATADOG_API_KEY!,\n *   service: 'my-lambda',\n *   enableLogs: true,\n * }));\n * ```\n *\n * @example Local Datadog Agent (long-running services, Kubernetes)\n * ```typescript\n * import { init } from 'autotel';\n * import { createDatadogConfig } from 'autotel-backends/datadog';\n *\n * init(createDatadogConfig({\n *   service: 'my-api',\n *   useAgent: true,  // No API key needed - Agent handles it\n * }));\n * ```\n */\n\nimport { createRequire } from 'node:module';\nimport type { AutotelConfig } from 'autotel';\nimport type { LogRecordProcessor } from '@opentelemetry/sdk-logs';\n\n/**\n * Datadog site regions\n */\nexport type DatadogSite =\n  | 'datadoghq.com' // US1 (default)\n  | 'datadoghq.eu' // EU\n  | 'us3.datadoghq.com' // US3\n  | 'us5.datadoghq.com' // US5\n  | 'ap1.datadoghq.com' // AP1\n  | 'ddog-gov.com'; // US1-FED\n\n/**\n * Configuration options for Datadog preset\n */\nexport interface DatadogPresetConfig {\n  /**\n   * Datadog API key (required for direct cloud ingestion).\n   * Not needed if using local Datadog Agent (useAgent: true).\n   *\n   * Get your API key from:\n   * https://app.datadoghq.com/organization-settings/api-keys\n   */\n  apiKey?: string;\n\n  /**\n   * Datadog site/region.\n   * Determines which Datadog intake endpoint to use.\n   *\n   * @default 'datadoghq.com' (US1)\n   */\n  site?: DatadogSite;\n\n  /**\n   * Service name (required).\n   * Appears in Datadog APM, Service Catalog, and all telemetry.\n   */\n  service: string;\n\n  /**\n   * Deployment environment (e.g., 'production', 'staging', 'development').\n   * Used for environment filtering in Datadog.\n   *\n   * @default process.env.DD_ENV || process.env.NODE_ENV || 'development'\n   */\n  environment?: string;\n\n  /**\n   * Service version for deployment tracking.\n   * Enables Deployment Tracking in Datadog APM.\n   *\n   * @default process.env.DD_VERSION || auto-detected from package.json\n   */\n  version?: string;\n\n  /**\n   * Enable log export to Datadog via OTLP.\n   * Requires peer dependencies: @opentelemetry/sdk-logs, @opentelemetry/exporter-logs-otlp-http\n   *\n   * @default false\n   */\n  enableLogs?: boolean;\n\n  /**\n   * Use local Datadog Agent instead of direct cloud ingestion.\n   *\n   * Benefits:\n   * - Lower egress costs (Agent aggregates locally)\n   * - Advanced features: trace-log correlation, multi-line logs, data scrubbing\n   * - 500+ integrations for enrichment\n   * - Infrastructure metrics collection\n   *\n   * Requires: Datadog Agent 7.35+ with OTLP enabled\n   *\n   * @default false\n   */\n  useAgent?: boolean;\n\n  /**\n   * Datadog Agent hostname (when useAgent: true).\n   *\n   * @default 'localhost'\n   */\n  agentHost?: string;\n\n  /**\n   * Datadog Agent OTLP port (when useAgent: true).\n   *\n   * @default 4318 (OTLP HTTP)\n   */\n  agentPort?: number;\n\n  /**\n   * Custom log record processors (advanced).\n   * Overrides the default log processor if enableLogs is true.\n   */\n  logRecordProcessors?: LogRecordProcessor[];\n}\n\n/**\n * Create an autotel configuration optimized for Datadog.\n *\n * This preset handles:\n * - Proper OTLP endpoint configuration (Agent vs direct ingestion)\n *   - Direct: https://otlp.{site} → SDK appends /v1/traces, /v1/metrics, /v1/logs\n *   - Agent: http://localhost:4318 (default)\n * - Datadog API key authentication headers (direct ingestion only)\n * - Unified service tagging (service, env, version)\n * - Resource attribute best practices\n * - Optional log export configuration\n *\n * @param config - Datadog-specific configuration options\n * @returns AutotelConfig ready to pass to init()\n *\n * @example Simple cloud ingestion\n * ```typescript\n * init(createDatadogConfig({\n *   apiKey: process.env.DATADOG_API_KEY!,\n *   service: 'my-app',\n * }));\n * ```\n *\n * @example With logs and custom environment\n * ```typescript\n * init(createDatadogConfig({\n *   apiKey: process.env.DATADOG_API_KEY!,\n *   service: 'my-app',\n *   environment: 'production',\n *   version: '2.1.0',\n *   enableLogs: true,\n * }));\n * ```\n *\n * @example Using local Datadog Agent\n * ```typescript\n * init(createDatadogConfig({\n *   service: 'my-api',\n *   useAgent: true,\n *   agentHost: 'datadog-agent.default.svc.cluster.local', // Kubernetes\n * }));\n * ```\n */\nexport function createDatadogConfig(\n  config: DatadogPresetConfig,\n): AutotelConfig {\n  const {\n    apiKey,\n    site = 'datadoghq.com',\n    service,\n    environment,\n    version,\n    enableLogs = false,\n    useAgent = false,\n    agentHost = 'localhost',\n    agentPort = 4318,\n    logRecordProcessors,\n  } = config;\n\n  // Validation: API key required for direct ingestion\n  if (!useAgent && !apiKey) {\n    throw new Error(\n      'Datadog API key is required for direct cloud ingestion. ' +\n        'Either provide apiKey or set useAgent: true to use local Datadog Agent.',\n    );\n  }\n\n  const baseConfig: AutotelConfig = {\n    service,\n    environment,\n    version,\n  };\n\n  // Local Datadog Agent configuration\n  if (useAgent) {\n    const agentEndpoint = `http://${agentHost}:${agentPort}`;\n\n    return {\n      ...baseConfig,\n      endpoint: agentEndpoint,\n      // No API key or headers needed - Agent handles authentication\n    };\n  }\n\n  // Direct cloud ingestion configuration\n  // Datadog OTLP endpoint: base URL without path (SDK appends /v1/traces, /v1/metrics, /v1/logs)\n  const otlpEndpoint = `https://otlp.${site}`;\n  const authHeaders = `dd-api-key=${apiKey}`;\n\n  const cloudConfig: AutotelConfig = {\n    ...baseConfig,\n    endpoint: otlpEndpoint,\n    otlpHeaders: authHeaders,\n  };\n\n  // Add log export if enabled\n  if (enableLogs) {\n    if (logRecordProcessors) {\n      // Use custom processors if provided\n      cloudConfig.logRecordProcessors = logRecordProcessors;\n    } else {\n      // Create default OTLP log exporter\n      try {\n        // Lazy-load to preserve optional peer dependencies\n        // Use createRequire to resolve from user's project directory\n        const userRequire = createRequire(process.cwd() + '/package.json');\n\n        const { BatchLogRecordProcessor } = userRequire(\n          '@opentelemetry/sdk-logs',\n        );\n        const { OTLPLogExporter } = userRequire(\n          '@opentelemetry/exporter-logs-otlp-http',\n        );\n\n        cloudConfig.logRecordProcessors = [\n          new BatchLogRecordProcessor(\n            new OTLPLogExporter({\n              // Logs use /v1/logs path (SDK appends this to endpoint)\n              url: `${otlpEndpoint}/v1/logs`,\n              headers: {\n                'dd-api-key': apiKey,\n              },\n            }),\n          ),\n        ];\n      } catch {\n        throw new Error(\n          'Log export requires peer dependencies: @opentelemetry/sdk-logs and @opentelemetry/exporter-logs-otlp-http. ' +\n            'Install them with: npm install @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http',\n        );\n      }\n    }\n  }\n\n  return cloudConfig;\n}\n"]}

package/dist/honeycomb.d.ts

@@ -0,0 +1,136 @@
+import { AutotelConfig } from 'autotel';
+
+/**
+ * Honeycomb preset for autotel
+ *
+ * Provides a simplified configuration helper for Honeycomb integration
+ * with best practices built-in.
+ *
+ * @example Using Honeycomb with API key
+ * ```typescript
+ * import { init } from 'autotel';
+ * import { createHoneycombConfig } from 'autotel-backends/honeycomb';
+ *
+ * init(createHoneycombConfig({
+ *   apiKey: process.env.HONEYCOMB_API_KEY!,
+ *   service: 'my-app',
+ * }));
+ * ```
+ *
+ * @example With custom dataset
+ * ```typescript
+ * import { init } from 'autotel';
+ * import { createHoneycombConfig } from 'autotel-backends/honeycomb';
+ *
+ * init(createHoneycombConfig({
+ *   apiKey: process.env.HONEYCOMB_API_KEY!,
+ *   service: 'my-app',
+ *   dataset: 'production',
+ * }));
+ * ```
+ */
+
+/**
+ * Configuration options for Honeycomb preset
+ */
+interface HoneycombPresetConfig {
+    /**
+     * Honeycomb API key (required).
+     *
+     * Get your API key from:
+     * https://ui.honeycomb.io/account
+     *
+     * For classic environments, use an environment-specific key.
+     * For newer environments, use a team-level API key.
+     */
+    apiKey: string;
+    /**
+     * Service name (required).
+     * Appears as service.name in Honeycomb traces and determines dataset routing.
+     */
+    service: string;
+    /**
+     * Dataset name (optional).
+     * For classic Honeycomb accounts that use datasets.
+     * Modern environments route based on service.name instead.
+     *
+     * @default service name
+     */
+    dataset?: string;
+    /**
+     * Deployment environment (e.g., 'production', 'staging', 'development').
+     * Used for environment filtering in Honeycomb.
+     *
+     * @default process.env.NODE_ENV || 'development'
+     */
+    environment?: string;
+    /**
+     * Service version for deployment tracking.
+     *
+     * @default process.env.VERSION || auto-detected from package.json
+     */
+    version?: string;
+    /**
+     * Honeycomb API endpoint.
+     * Use this to configure for different regions or on-premises installations.
+     *
+     * @default 'api.honeycomb.io:443'
+     */
+    endpoint?: string;
+    /**
+     * Sample rate for traces (1 = 100%, 10 = 10%, 100 = 1%).
+     * Honeycomb's head-based sampling rate.
+     *
+     * Note: Autotel uses tail-based sampling by default.
+     * This setting applies additional head-based sampling if specified.
+     *
+     * @default undefined (no head-based sampling, relies on tail sampling)
+     */
+    sampleRate?: number;
+}
+/**
+ * Create an autotel configuration optimized for Honeycomb.
+ *
+ * This preset handles:
+ * - gRPC protocol configuration (Honeycomb's preferred protocol)
+ * - Proper endpoint and authentication headers
+ * - Dataset routing (for classic accounts)
+ * - Unified service tagging (service, env, version)
+ *
+ * Honeycomb uses gRPC by default for better performance and lower overhead.
+ * This preset automatically configures the gRPC protocol.
+ *
+ * @param config - Honeycomb-specific configuration options
+ * @returns AutotelConfig ready to pass to init()
+ *
+ * @example Simple configuration
+ * ```typescript
+ * init(createHoneycombConfig({
+ *   apiKey: process.env.HONEYCOMB_API_KEY!,
+ *   service: 'my-app',
+ * }));
+ * ```
+ *
+ * @example With custom dataset and environment
+ * ```typescript
+ * init(createHoneycombConfig({
+ *   apiKey: process.env.HONEYCOMB_API_KEY!,
+ *   service: 'my-app',
+ *   dataset: 'production',
+ *   environment: 'production',
+ *   version: '2.1.0',
+ * }));
+ * ```
+ *
+ * @example With sample rate
+ * ```typescript
+ * init(createHoneycombConfig({
+ *   apiKey: process.env.HONEYCOMB_API_KEY!,
+ *   service: 'my-app',
+ *   sampleRate: 10, // Sample 10% of traces (head-based sampling)
+ * }));
+ * ```
+ */
+declare function createHoneycombConfig(config: HoneycombPresetConfig): AutotelConfig;
+
+export { type HoneycombPresetConfig, createHoneycombConfig };