@mastra/otel-exporter 0.0.0-suspendRuntimeContextTypeFix-20250930142630

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @mastra/otel-exporter
+
+## 0.0.0-suspendRuntimeContextTypeFix-20250930142630
+
+### Patch Changes
+
+- Initial release of the otel-exporter for ai observability ([#8273](https://github.com/mastra-ai/mastra/pull/8273))
+
+- Updated dependencies [[`dc099b4`](https://github.com/mastra-ai/mastra/commit/dc099b40fb31147ba3f362f98d991892033c4c67), [`504438b`](https://github.com/mastra-ai/mastra/commit/504438b961bde211071186bba63a842c4e3db879), [`b342a68`](https://github.com/mastra-ai/mastra/commit/b342a68e1399cf1ece9ba11bda112db89d21118c), [`7fceb0a`](https://github.com/mastra-ai/mastra/commit/7fceb0a327d678e812f90f5387c5bc4f38bd039e), [`303a9c0`](https://github.com/mastra-ai/mastra/commit/303a9c0d7dd58795915979f06a0512359e4532fb), [`c7db3e0`](https://github.com/mastra-ai/mastra/commit/c7db3e057c4b2858a630a7c3f3d3aae571e3e5b7), [`370f8a6`](https://github.com/mastra-ai/mastra/commit/370f8a6480faec70fef18d72e5f7538f27004301), [`809eea0`](https://github.com/mastra-ai/mastra/commit/809eea092fa80c3f69b9eaf078d843b57fd2a88e), [`623ffaf`](https://github.com/mastra-ai/mastra/commit/623ffaf2d969e11e99a0224633cf7b5a0815c857), [`9fc1613`](https://github.com/mastra-ai/mastra/commit/9fc16136400186648880fd990119ac15f7c02ee4), [`61f62aa`](https://github.com/mastra-ai/mastra/commit/61f62aa31bc88fe4ddf8da6240dbcfbeb07358bd), [`db1891a`](https://github.com/mastra-ai/mastra/commit/db1891a4707443720b7cd8a260dc7e1d49b3609c), [`e8f379d`](https://github.com/mastra-ai/mastra/commit/e8f379d390efa264c4e0874f9ac0cf8839b07777), [`3e292ba`](https://github.com/mastra-ai/mastra/commit/3e292ba00837886d5d68a34cbc0d9b703c991883), [`418c136`](https://github.com/mastra-ai/mastra/commit/418c1366843d88e491bca3f87763899ce855ca29), [`c2a4919`](https://github.com/mastra-ai/mastra/commit/c2a4919ba6797d8bdb1509e02287496eef69303e), [`c84b7d0`](https://github.com/mastra-ai/mastra/commit/c84b7d093c4657772140cbfd2b15ef72f3315ed5)]:
+  - @mastra/core@0.0.0-suspendRuntimeContextTypeFix-20250930142630

package/LICENSE.md

@@ -0,0 +1,15 @@
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,435 @@
+# OtelExporter - OpenTelemetry AI Tracing Exporter
+
+Export Mastra AI 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.
+
+## Supported Providers
+
+### Dash0
+
+#### Installation
+
+```bash
+# Dash0 uses gRPC protocol, requires both packages
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+```
+
+#### Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+import { Mastra } from '@mastra/core';
+
+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
+              }
+            },
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+**Note:** Get your endpoint from your Dash0 dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
+
+### SigNoz
+
+#### Installation
+
+```bash
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
+```
+
+#### Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+import { Mastra } from '@mastra/core';
+
+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
+              }
+            },
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+### New Relic
+
+#### Installation
+
+```bash
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
+```
+
+#### Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+import { Mastra } from '@mastra/core';
+
+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
+              }
+            },
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+### Traceloop
+
+#### Installation
+
+```bash
+# Traceloop uses HTTP/JSON protocol
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
+```
+
+#### Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+import { Mastra } from '@mastra/core';
+
+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
+              }
+            },
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+### Laminar
+
+#### Installation
+
+```bash
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
+```
+
+#### Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+import { Mastra } from '@mastra/core';
+
+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
+              }
+            },
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+**Note:** Laminar now only requires the `LMNR_PROJECT_API_KEY`. The `teamId` is optional.
+
+### Zipkin
+
+#### Installation
+
+```bash
+npm install @mastra/otel-exporter @opentelemetry/exporter-zipkin
+```
+
+#### Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+import { Mastra } from '@mastra/core';
+
+const mastra = new Mastra({
+  ...,
+  observability: {
+    configs: {
+      otel: {
+        serviceName: 'mastra-service',
+        exporters: [
+          new OtelExporter({
+            provider: {
+              custom: {
+                endpoint: 'http://localhost:9411/api/v2/spans',
+                protocol: 'zipkin',
+              }
+            },
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+### Custom/Other Providers
+
+#### Installation
+
+Choose the appropriate exporter based on your collector's protocol:
+
+```bash
+# For HTTP/JSON: Human-readable, larger payload, good for debugging
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
+
+# For HTTP/Protobuf: Binary format, smaller payload, recommended for production
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
+
+# For gRPC: Bidirectional streaming, lowest latency, requires gRPC support
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+
+# For Zipkin: Zipkin-specific format
+npm install @mastra/otel-exporter @opentelemetry/exporter-zipkin
+```
+
+Most providers recommend HTTP/Protobuf for production use.
+
+#### Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+import { Mastra } from '@mastra/core';
+
+const mastra = new Mastra({
+  ...,
+  observability: {
+    configs: {
+      otel: {
+        serviceName: 'mastra-service',
+        exporters: [
+          new OtelExporter({
+            provider: {
+              custom: {
+                endpoint: 'https://your-collector.example.com/v1/traces', // Required at runtime
+                protocol: 'http/protobuf', // Optional: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'
+                headers: { // Optional
+                  'x-api-key': process.env.API_KEY,
+                },
+              }
+            }
+          })
+        ],
+      },
+    },
+  },
+});
+```
+
+## Why Separate Packages?
+
+We've made exporter dependencies optional to:
+
+- **Reduce bundle size** - Only include what you need
+- **Faster installs** - Fewer dependencies to download
+- **Avoid conflicts** - Some exporters have conflicting dependencies
+
+If you forget to install the required exporter, you'll get a helpful error message telling you exactly what to install.
+
+## Endpoint Configuration Notes
+
+### Protocol Requirements
+
+- **gRPC endpoints**: Automatically append `/v1/traces` to the base endpoint
+- **HTTP endpoints**: Most providers expect `/v1/traces` or provider-specific paths
+- **Authentication**:
+  - HTTP uses `headers` with standard HTTP headers
+  - gRPC uses lowercase metadata keys (e.g., `authorization` instead of `Authorization`)
+
+### Provider-Specific Endpoints
+
+| Provider  | Protocol      | Endpoint Format                                      | Notes              |
+| --------- | ------------- | ---------------------------------------------------- | ------------------ |
+| Dash0     | gRPC          | `ingress.{region}.aws.dash0.com:4317`                | Get from dashboard |
+| SigNoz    | HTTP/Protobuf | `https://ingest.{region}.signoz.cloud:443/v1/traces` | Cloud hosted       |
+| New Relic | HTTP/Protobuf | `https://otlp.nr-data.net:443/v1/traces`             | US region          |
+| Traceloop | HTTP/JSON     | `https://api.traceloop.com/v1/traces`                | Default endpoint   |
+| Laminar   | HTTP/Protobuf | `https://api.lmnr.ai/v1/traces`                      | Default endpoint   |
+
+## Additional configuration
+
+```typescript
+// Main configuration interface
+interface OtelExporterConfig {
+  // Provider configuration (discriminated union)
+  provider?: ProviderConfig;
+
+  // Export configuration
+  timeout?: number; // Export timeout in milliseconds (default: 30000)
+  batchSize?: number; // Max spans per batch (default: 512)
+
+  // Debug
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+```
+
+## Batching Strategy
+
+The OtelExporter uses OpenTelemetry's `BatchSpanProcessor` for efficient span export:
+
+- **Automatic batching**: Spans are queued and exported in batches
+- **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
+
+This approach ensures:
+
+- Efficient network usage (fewer HTTP/gRPC calls)
+- Better performance under load
+- Automatic retry with backoff
+- Proper trace context propagation across all spans in a trace
+
+## OpenTelemetry Semantic Conventions
+
+This exporter follows the [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) to ensure compatibility with observability platforms.
+
+### Span Naming
+
+Spans are named following OTEL conventions:
+
+- **LLM Operations**: `chat {model}` or `tool_selection {model}`
+- **Tool Execution**: `tool.execute {tool_name}`
+- **Agent Runs**: `agent.{agent_id}`
+- **Workflow Runs**: `workflow.{workflow_id}`
+
+### Attributes
+
+The exporter maps Mastra's AI tracing data to OTEL-compliant attributes:
+
+#### Core Attributes
+
+- `gen_ai.operation.name` - Operation type (chat, tool.execute, agent.run, workflow.run)
+- `gen_ai.system` - AI provider (openai, anthropic, etc.)
+- `gen_ai.request.model` - Model identifier
+
+#### LLM-Specific Attributes
+
+- `gen_ai.usage.input_tokens` - Number of input tokens
+- `gen_ai.usage.output_tokens` - Number of output tokens
+- `gen_ai.usage.total_tokens` - Total token count
+- `gen_ai.request.temperature` - Sampling temperature
+- `gen_ai.request.max_tokens` - Maximum tokens to generate
+- `gen_ai.request.top_p` - Top-p sampling parameter
+- `gen_ai.request.top_k` - Top-k sampling parameter
+- `gen_ai.response.finish_reasons` - Reason for completion
+- `gen_ai.prompt` - Input prompt (for LLM spans)
+- `gen_ai.completion` - Model output (for LLM spans)
+
+#### Tool Attributes
+
+- `gen_ai.tool.name` - Tool identifier
+- `gen_ai.tool.description` - Tool description
+- `gen_ai.tool.success` - Whether tool execution succeeded
+- `gen_ai.tool.input` - Tool input parameters
+- `gen_ai.tool.output` - Tool execution result
+
+#### Agent & Workflow Attributes
+
+- `agent.id` - Agent identifier
+- `agent.max_steps` - Maximum agent steps
+- `workflow.id` - Workflow identifier
+- `workflow.status` - Workflow execution status
+
+#### Error Attributes
+
+- `error` - Boolean indicating error occurred
+- `error.type` - Error identifier
+- `error.message` - Error description
+- `error.domain` - Error domain/category
+
+## Troubleshooting
+
+### Missing Dependency Error
+
+If you forget to install the required exporter package, you'll get a clear error message:
+
+```
+HTTP/Protobuf exporter is not installed (required for signoz).
+To use HTTP/Protobuf export, install the required package:
+
+  npm install @opentelemetry/exporter-trace-otlp-proto
+  # or
+  pnpm add @opentelemetry/exporter-trace-otlp-proto
+  # or
+  yarn add @opentelemetry/exporter-trace-otlp-proto
+```
+
+### Common Issues
+
+1. **Wrong exporter installed**: Make sure you installed the exporter matching your provider's protocol
+2. **Multiple exporters needed**: If switching between providers, you may need multiple exporters installed
+3. **Bundle size concerns**: Only install the exporters you actually use
+
+## License
+
+Apache 2.0

package/dist/ai-tracing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OpenTelemetry AI Tracing Exporter for Mastra
+ */
+import type { AITracingExporter, AITracingEvent, TracingConfig } from '@mastra/core/ai-tracing';
+import type { OtelExporterConfig } from './types.js';
+export declare class OtelExporter implements AITracingExporter {
+    private config;
+    private tracingConfig?;
+    private spanConverter;
+    private processor?;
+    private exporter?;
+    private isSetup;
+    private isDisabled;
+    private logger;
+    name: string;
+    constructor(config: OtelExporterConfig);
+    /**
+     * Initialize with tracing configuration
+     */
+    init(config: TracingConfig): void;
+    private setupExporter;
+    exportEvent(event: AITracingEvent): Promise<void>;
+    private exportSpan;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=ai-tracing.d.ts.map

package/dist/ai-tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tracing.d.ts","sourceRoot":"","sources":["../src/ai-tracing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAqB,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAiBnH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,qBAAa,YAAa,YAAW,iBAAiB;IACpD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,QAAQ,CAAC,CAAe;IAChC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,MAAM,CAAgB;IAE9B,IAAI,SAAmB;gBAEX,MAAM,EAAE,kBAAkB;IAWtC;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;YAInB,aAAa;IAiHrB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;YAgBzC,UAAU;IA8BlB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAMhC"}