@mastra/otel-exporter 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -4,6 +4,18 @@ Export Mastra traces to any OpenTelemetry-compatible observability platform.
 
 > **⚠️ Important:** This package requires you to install an additional exporter package based on your provider. Each provider section below includes the specific installation command.
 
+## Environment Variables
+
+All providers support zero-config setup via environment variables. Set the appropriate variables and the exporter will automatically use them:
+
+| Provider  | Environment Variables                                                                       |
+| --------- | ------------------------------------------------------------------------------------------- |
+| Dash0     | `DASH0_API_KEY` (required), `DASH0_ENDPOINT` (required), `DASH0_DATASET` (optional)         |
+| SigNoz    | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional)       |
+| New Relic | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional)                         |
+| Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) |
+| Laminar   | `LMNR_PROJECT_API_KEY` (required), `LAMINAR_ENDPOINT` (optional)                            |
+
 ## Supported Providers
 
 ### Dash0
@@ -15,7 +27,16 @@ Export Mastra traces to any OpenTelemetry-compatible observability platform.
 npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
 ```
 
-#### Configuration
+#### Zero-Config Setup
+
+```bash
+# Required
+DASH0_API_KEY=your-api-key
+DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317
+
+# Optional
+DASH0_DATASET=production
+```
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
@@ -26,24 +47,28 @@ const mastra = new Mastra({
   observability: {
     configs: {
       otel: {
-        serviceName: 'mastra-service',
-        exporters: [
-          new OtelExporter({
-            provider: {
-              dash0: {
-                apiKey: process.env.DASH0_API_KEY, // Required at runtime
-                endpoint: 'ingress.us-west-2.aws.dash0.com:4317', // Required at runtime
-                dataset: 'production', // Optional: dataset name
-              }
-            },
-          })
-        ],
+        serviceName: 'my-service',
+        exporters: [new OtelExporter({ provider: { dash0: {} } })],
       },
     },
   },
 });
 ```
 
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    dash0: {
+      apiKey: 'your-api-key',
+      endpoint: 'ingress.us-west-2.aws.dash0.com:4317',
+      dataset: 'production', // Optional
+    },
+  },
+});
+```
+
 **Note:** Get your endpoint from your Dash0 dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
 
 ### SigNoz
@@ -54,7 +79,16 @@ const mastra = new Mastra({
 npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
 ```
 
-#### Configuration
+#### Zero-Config Setup
+
+```bash
+# Required
+SIGNOZ_API_KEY=your-api-key
+
+# Optional
+SIGNOZ_REGION=us  # 'us' | 'eu' | 'in'
+SIGNOZ_ENDPOINT=https://my-signoz.example.com  # For self-hosted
+```
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
@@ -65,24 +99,28 @@ const mastra = new Mastra({
   observability: {
     configs: {
       otel: {
-        serviceName: 'mastra-service',
-        exporters: [
-          new OtelExporter({
-            provider: {
-              signoz: {
-                apiKey: process.env.SIGNOZ_API_KEY, // Required at runtime
-                region: 'us', // Optional: 'us' | 'eu' | 'in', defaults to 'us'
-                // endpoint: 'https://my-signoz.example.com', // Optional: for self-hosted
-              }
-            },
-          })
-        ],
+        serviceName: 'my-service',
+        exporters: [new OtelExporter({ provider: { signoz: {} } })],
       },
     },
   },
 });
 ```
 
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    signoz: {
+      apiKey: 'your-api-key',
+      region: 'us', // Optional: 'us' | 'eu' | 'in'
+      endpoint: 'https://my-signoz.example.com', // Optional: for self-hosted
+    },
+  },
+});
+```
+
 ### New Relic
 
 #### Installation
@@ -91,7 +129,15 @@ const mastra = new Mastra({
 npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
 ```
 
-#### Configuration
+#### Zero-Config Setup
+
+```bash
+# Required
+NEW_RELIC_LICENSE_KEY=your-license-key
+
+# Optional
+NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net  # For EU region
+```
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
@@ -102,23 +148,27 @@ const mastra = new Mastra({
   observability: {
     configs: {
       otel: {
-        serviceName: 'mastra-service',
-        exporters: [
-          new OtelExporter({
-            provider: {
-              newrelic: {
-                apiKey: process.env.NEW_RELIC_LICENSE_KEY, // Required at runtime
-                // endpoint: 'https://otlp.eu01.nr-data.net', // Optional: for EU region
-              }
-            },
-          })
-        ],
+        serviceName: 'my-service',
+        exporters: [new OtelExporter({ provider: { newrelic: {} } })],
       },
     },
   },
 });
 ```
 
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    newrelic: {
+      apiKey: 'your-license-key',
+      endpoint: 'https://otlp.eu01.nr-data.net', // Optional: for EU region
+    },
+  },
+});
+```
+
 ### Traceloop
 
 #### Installation
@@ -128,7 +178,16 @@ const mastra = new Mastra({
 npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
 ```
 
-#### Configuration
+#### Zero-Config Setup
+
+```bash
+# Required
+TRACELOOP_API_KEY=your-api-key
+
+# Optional
+TRACELOOP_DESTINATION_ID=my-destination
+TRACELOOP_ENDPOINT=https://custom.traceloop.com
+```
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
@@ -139,24 +198,28 @@ const mastra = new Mastra({
   observability: {
     configs: {
       otel: {
-        serviceName: 'mastra-service',
-        exporters: [
-          new OtelExporter({
-            provider: {
-              traceloop: {
-                apiKey: process.env.TRACELOOP_API_KEY, // Required at runtime
-                destinationId: 'my-destination', // Optional
-                // endpoint: 'https://custom.traceloop.com', // Optional
-              }
-            },
-          })
-        ],
+        serviceName: 'my-service',
+        exporters: [new OtelExporter({ provider: { traceloop: {} } })],
       },
     },
   },
 });
 ```
 
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    traceloop: {
+      apiKey: 'your-api-key',
+      destinationId: 'my-destination', // Optional
+      endpoint: 'https://custom.traceloop.com', // Optional
+    },
+  },
+});
+```
+
 ### Laminar
 
 #### Installation
@@ -165,7 +228,15 @@ const mastra = new Mastra({
 npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
 ```
 
-#### Configuration
+#### Zero-Config Setup
+
+```bash
+# Required
+LMNR_PROJECT_API_KEY=your-api-key
+
+# Optional
+LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
+```
 
 ```typescript
 import { OtelExporter } from '@mastra/otel-exporter';
@@ -176,25 +247,26 @@ const mastra = new Mastra({
   observability: {
     configs: {
       otel: {
-        serviceName: 'mastra-service',
-        exporters: [
-          new OtelExporter({
-            provider: {
-              laminar: {
-                apiKey: process.env.LMNR_PROJECT_API_KEY, // Required at runtime
-                // teamId: process.env.LAMINAR_TEAM_ID, // Optional, for backwards compatibility
-                // endpoint: 'https://api.lmnr.ai/v1/traces', // Optional
-              }
-            },
-          })
-        ],
+        serviceName: 'my-service',
+        exporters: [new OtelExporter({ provider: { laminar: {} } })],
       },
     },
   },
 });
 ```
 
-**Note:** Laminar now only requires the `LMNR_PROJECT_API_KEY`. The `teamId` is optional.
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    laminar: {
+      apiKey: 'your-api-key',
+      endpoint: 'https://api.lmnr.ai/v1/traces', // Optional
+    },
+  },
+});
+```
 
 ### Zipkin
 
@@ -340,7 +412,7 @@ The OtelExporter uses OpenTelemetry's `BatchSpanProcessor` for efficient span ex
 - **Default batch size**: 512 spans (configurable via `batchSize`)
 - **Export interval**: Every 5 seconds or when batch is full
 - **Queue size**: Up to 2048 spans queued in memory
-- **Production-ready**: Optimized for high-throughput applications
+- **High-throughput support**: Handles large volumes of spans efficiently
 
 This approach ensures:
 

package/dist/index.cjs

@@ -106,24 +106,31 @@ function resolveProviderConfig(config) {
   }
 }
 function resolveDash0Config(config) {
-  if (!config.apiKey) {
-    console.error("[OtelExporter] Dash0 configuration requires apiKey. Tracing will be disabled.");
+  const apiKey = config.apiKey ?? process.env.DASH0_API_KEY;
+  const configEndpoint = config.endpoint ?? process.env.DASH0_ENDPOINT;
+  const dataset = config.dataset ?? process.env.DASH0_DATASET;
+  if (!apiKey) {
+    console.error(
+      "[OtelExporter] Dash0 configuration requires apiKey. Set DASH0_API_KEY environment variable or pass it in config. Tracing will be disabled."
+    );
     return null;
   }
-  if (!config.endpoint) {
-    console.error("[OtelExporter] Dash0 configuration requires endpoint. Tracing will be disabled.");
+  if (!configEndpoint) {
+    console.error(
+      "[OtelExporter] Dash0 configuration requires endpoint. Set DASH0_ENDPOINT environment variable or pass it in config. Tracing will be disabled."
+    );
     return null;
   }
-  let endpoint = config.endpoint;
+  let endpoint = configEndpoint;
   if (!endpoint.includes("/v1/traces")) {
     endpoint = `${endpoint}/v1/traces`;
   }
   const headers = {
-    authorization: `Bearer ${config.apiKey}`
+    authorization: `Bearer ${apiKey}`
     // lowercase for gRPC metadata
   };
-  if (config.dataset) {
-    headers["dash0-dataset"] = config.dataset;
+  if (dataset) {
+    headers["dash0-dataset"] = dataset;
   }
   return {
     endpoint,
@@ -133,44 +140,58 @@ function resolveDash0Config(config) {
   };
 }
 function resolveSignozConfig(config) {
-  if (!config.apiKey) {
-    console.error("[OtelExporter] SigNoz configuration requires apiKey. Tracing will be disabled.");
+  const apiKey = config.apiKey ?? process.env.SIGNOZ_API_KEY;
+  const region = config.region ?? process.env.SIGNOZ_REGION;
+  const configEndpoint = config.endpoint ?? process.env.SIGNOZ_ENDPOINT;
+  if (!apiKey) {
+    console.error(
+      "[OtelExporter] SigNoz configuration requires apiKey. Set SIGNOZ_API_KEY environment variable or pass it in config. Tracing will be disabled."
+    );
     return null;
   }
-  const endpoint = config.endpoint || `https://ingest.${config.region || "us"}.signoz.cloud:443/v1/traces`;
+  const endpoint = configEndpoint || `https://ingest.${region || "us"}.signoz.cloud:443/v1/traces`;
   return {
     endpoint,
     headers: {
-      "signoz-ingestion-key": config.apiKey
+      "signoz-ingestion-key": apiKey
     },
     protocol: "http/protobuf"
   };
 }
 function resolveNewRelicConfig(config) {
-  if (!config.apiKey) {
-    console.error("[OtelExporter] New Relic configuration requires apiKey (license key). Tracing will be disabled.");
+  const apiKey = config.apiKey ?? process.env.NEW_RELIC_LICENSE_KEY;
+  const configEndpoint = config.endpoint ?? process.env.NEW_RELIC_ENDPOINT;
+  if (!apiKey) {
+    console.error(
+      "[OtelExporter] New Relic configuration requires apiKey (license key). Set NEW_RELIC_LICENSE_KEY environment variable or pass it in config. Tracing will be disabled."
+    );
     return null;
   }
-  const endpoint = config.endpoint || "https://otlp.nr-data.net:443/v1/traces";
+  const endpoint = configEndpoint || "https://otlp.nr-data.net:443/v1/traces";
   return {
     endpoint,
     headers: {
-      "api-key": config.apiKey
+      "api-key": apiKey
     },
     protocol: "http/protobuf"
   };
 }
 function resolveTraceloopConfig(config) {
-  if (!config.apiKey) {
-    console.error("[OtelExporter] Traceloop configuration requires apiKey. Tracing will be disabled.");
+  const apiKey = config.apiKey ?? process.env.TRACELOOP_API_KEY;
+  const destinationId = config.destinationId ?? process.env.TRACELOOP_DESTINATION_ID;
+  const configEndpoint = config.endpoint ?? process.env.TRACELOOP_ENDPOINT;
+  if (!apiKey) {
+    console.error(
+      "[OtelExporter] Traceloop configuration requires apiKey. Set TRACELOOP_API_KEY environment variable or pass it in config. Tracing will be disabled."
+    );
     return null;
   }
-  const endpoint = config.endpoint || "https://api.traceloop.com/v1/traces";
+  const endpoint = configEndpoint || "https://api.traceloop.com/v1/traces";
   const headers = {
-    Authorization: `Bearer ${config.apiKey}`
+    Authorization: `Bearer ${apiKey}`
   };
-  if (config.destinationId) {
-    headers["x-traceloop-destination-id"] = config.destinationId;
+  if (destinationId) {
+    headers["x-traceloop-destination-id"] = destinationId;
   }
   return {
     endpoint,
@@ -179,17 +200,18 @@ function resolveTraceloopConfig(config) {
   };
 }
 function resolveLaminarConfig(config) {
-  if (!config.apiKey) {
-    console.error("[OtelExporter] Laminar configuration requires apiKey. Tracing will be disabled.");
+  const apiKey = config.apiKey ?? process.env.LMNR_PROJECT_API_KEY;
+  const configEndpoint = config.endpoint ?? process.env.LAMINAR_ENDPOINT;
+  if (!apiKey) {
+    console.error(
+      "[OtelExporter] Laminar configuration requires apiKey. Set LMNR_PROJECT_API_KEY environment variable or pass it in config. Tracing will be disabled."
+    );
     return null;
   }
-  const endpoint = config.endpoint || "https://api.lmnr.ai/v1/traces";
+  const endpoint = configEndpoint || "https://api.lmnr.ai/v1/traces";
   const headers = {
-    Authorization: `Bearer ${config.apiKey}`
+    Authorization: `Bearer ${apiKey}`
   };
-  if (config.teamId) {
-    headers["x-laminar-team-id"] = config.teamId;
-  }
   return {
     endpoint,
     headers,
@@ -334,10 +356,10 @@ function getSpanIdentifier(span) {
   switch (span.type) {
     case observability.SpanType.MODEL_GENERATION: {
       const attrs = span.attributes;
-      return attrs?.model ?? "unknown";
+      return attrs?.model;
     }
     default:
-      return span.entityName ?? span.entityId ?? "unknown";
+      return span.entityName ?? span.entityId;
   }
 }
 function getSpanName(span) {
@@ -701,16 +723,15 @@ var OtelExporter = class extends observability$1.BaseExporter {
   async setupExporter() {
     if (this.isSetup || this.exporter) return;
     if (!this.config.provider) {
-      this.logger.error(
+      this.setDisabled(
         '[OtelExporter] Provider configuration is required. Use the "custom" provider for generic endpoints.'
       );
-      this.isDisabled = true;
       this.isSetup = true;
       return;
     }
     const resolved = resolveProviderConfig(this.config.provider);
     if (!resolved) {
-      this.isDisabled = true;
+      this.setDisabled("[OtelExporter] Provider configuration validation failed.");
       this.isSetup = true;
       return;
     }
@@ -724,7 +745,7 @@ var OtelExporter = class extends observability$1.BaseExporter {
     const providerName = Object.keys(this.config.provider)[0];
     const ExporterClass = await loadExporter(protocol, providerName);
     if (!ExporterClass) {
-      this.isDisabled = true;
+      this.setDisabled(`[OtelExporter] Exporter not available for protocol: ${protocol}`);
       this.isSetup = true;
       return;
     }
@@ -743,13 +764,11 @@ var OtelExporter = class extends observability$1.BaseExporter {
             metadata.set(key, value);
           });
         } catch (grpcError) {
-          this.logger.error(
+          this.setDisabled(
             `[OtelExporter] Failed to load gRPC metadata. Install required packages:
-  npm install @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
-`,
-            grpcError
+  npm install @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js`
           );
-          this.isDisabled = true;
+          this.logger.error("[OtelExporter] gRPC error details:", grpcError);
           this.isSetup = true;
           return;
         }
@@ -766,8 +785,8 @@ var OtelExporter = class extends observability$1.BaseExporter {
         });
       }
     } catch (error) {
-      this.logger.error(`[OtelExporter] Failed to create exporter:`, error);
-      this.isDisabled = true;
+      this.setDisabled("[OtelExporter] Failed to create exporter.");
+      this.logger.error("[OtelExporter] Exporter creation error details:", error);
       this.isSetup = true;
       return;
     }
@@ -827,6 +846,16 @@ var OtelExporter = class extends observability$1.BaseExporter {
       this.logger.error(`[OtelExporter] Failed to export span ${span.id}:`, error);
     }
   }
+  /**
+   * Force flush any buffered spans without shutting down the exporter.
+   * Delegates to the BatchSpanProcessor's forceFlush() method.
+   */
+  async flush() {
+    if (this.processor) {
+      await this.processor.forceFlush();
+      this.logger.debug("[OtelExporter] Flushed pending spans");
+    }
+  }
   async shutdown() {
     if (this.processor) {
       await this.processor.shutdown();
@@ -836,6 +865,8 @@ var OtelExporter = class extends observability$1.BaseExporter {
 
 exports.OtelExporter = OtelExporter;
 exports.SpanConverter = SpanConverter;
+exports.getAttributes = getAttributes;
 exports.getSpanKind = getSpanKind;
+exports.getSpanName = getSpanName;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map