feat(observability): add LangWatch exporter for AI tracing

.changeset/add-langwatch-exporter.md

@@ -0,0 +1,13 @@
+---
+"@mastra/langwatch": major
+---
+
+Initial release of @mastra/langwatch observability exporter.
+
+Sends traces to LangWatch via OTLP/HTTP (protobuf) with automatic Bearer token authentication.
+
+Features:
+- Zero-config setup via `LANGWATCH_API_KEY` environment variable
+- Custom endpoint support via `LANGWATCH_ENDPOINT` for self-hosted instances
+- Extends `OtelExporter` for standard OpenTelemetry trace formatting
+- Automatic disable with warning when API key is missing

docs/src/content/en/docs/observability/tracing/exporters/langwatch.mdx

@@ -0,0 +1,152 @@
+---
+title: "LangWatch Exporter | Tracing | Observability"
+description: "Send traces to LangWatch for LLM monitoring, evaluations, and analytics"
+packages:
+  - "@mastra/langwatch"
+  - "@mastra/observability"
+---
+
+# LangWatch Exporter
+
+[LangWatch](https://langwatch.ai) is an LLM observability platform for monitoring, evaluating, and improving AI applications. The LangWatch exporter sends your traces via OTLP, providing insights into model performance, token usage, and tool executions.
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/langwatch@beta
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **LangWatch Account**: Sign up at [langwatch.ai](https://langwatch.ai)
+2. **API Key**: Get your API key from your LangWatch project settings
+3. **Environment Variables**: Set your configuration
+
+```bash title=".env"
+LANGWATCH_API_KEY=your-api-key
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { LangwatchExporter } from "@mastra/langwatch";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      langwatch: {
+        serviceName: "my-service",
+        exporters: [new LangwatchExporter()],
+      },
+    },
+  }),
+});
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { LangwatchExporter } from "@mastra/langwatch";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      langwatch: {
+        serviceName: "my-service",
+        exporters: [
+          new LangwatchExporter({
+            apiKey: process.env.LANGWATCH_API_KEY!,
+          }),
+        ],
+      },
+    },
+  }),
+});
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new LangwatchExporter({
+  // Required settings
+  apiKey: process.env.LANGWATCH_API_KEY!, // LangWatch API key
+
+  // Optional settings
+  endpoint: "https://app.langwatch.ai/api/otel/v1/traces", // Custom endpoint for self-hosted instances
+
+  // Diagnostic logging
+  logLevel: "info", // debug | info | warn | error
+});
+```
+
+## Self-Hosted Instances
+
+If you are running a self-hosted LangWatch instance, override the endpoint:
+
+```typescript
+new LangwatchExporter({
+  apiKey: process.env.LANGWATCH_API_KEY!,
+  endpoint: "https://your-langwatch-instance.example.com/api/otel/v1/traces",
+});
+```
+
+Or via environment variable:
+
+```bash title=".env"
+LANGWATCH_API_KEY=your-api-key
+LANGWATCH_ENDPOINT=https://your-langwatch-instance.example.com/api/otel/v1/traces
+```
+
+## How It Works
+
+The LangWatch exporter extends the [OpenTelemetry exporter](/docs/observability/tracing/exporters/otel) with pre-configured settings for LangWatch:
+
+- **Protocol**: OTLP/HTTP (protobuf)
+- **Endpoint**: `https://app.langwatch.ai/api/otel/v1/traces`
+- **Authentication**: Bearer token via `Authorization` header
+
+All Mastra span types (agent runs, LLM generations, tool calls, workflow steps) are automatically captured and sent to LangWatch using standard OpenTelemetry semantic conventions.
+
+## Migrating from Manual OtelExporter
+
+If you were previously using the manual OtelExporter configuration for LangWatch:
+
+```typescript
+// Before (manual)
+import { OtelExporter } from "@mastra/otel-exporter";
+
+new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: "https://app.langwatch.ai/api/otel/v1/traces",
+      protocol: "http/protobuf",
+      headers: {
+        Authorization: `Bearer ${process.env.LANGWATCH_API_KEY}`,
+      },
+    },
+  },
+});
+
+// After (dedicated exporter)
+import { LangwatchExporter } from "@mastra/langwatch";
+
+new LangwatchExporter();
+```
+
+## Related
+
+- [Tracing Overview](/docs/observability/tracing/overview)
+- [LangWatch Documentation](https://langwatch.ai/docs)
+- [OpenTelemetry Exporter](/docs/observability/tracing/exporters/otel)

docs/src/content/en/docs/observability/tracing/overview.mdx

@@ -85,6 +85,7 @@ In addition to the internal exporters, Mastra supports integration with popular
 - **[Datadog](/docs/observability/tracing/exporters/datadog)** - Sends traces to Datadog APM via OTLP for full-stack observability with AI tracing
 - **[Laminar](/docs/observability/tracing/exporters/laminar)** - Sends traces to Laminar via OTLP/HTTP (protobuf) with Laminar-native span attributes + scorer support
 - **[Langfuse](/docs/observability/tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
+- **[LangWatch](/docs/observability/tracing/exporters/langwatch)** - Sends traces to LangWatch via OTLP for LLM monitoring, evaluations, and analytics
 - **[LangSmith](/docs/observability/tracing/exporters/langsmith)** - Pushes traces into LangSmith's observability and evaluation toolkit
 - **[PostHog](/docs/observability/tracing/exporters/posthog)** - Sends traces to PostHog for AI analytics and product insights
 - **[Sentry](/docs/observability/tracing/exporters/sentry)** - Sends traces to Sentry for AI tracing and monitoring using OpenTelemetry semantic conventions

docs/src/content/en/docs/sidebars.js

@@ -556,6 +556,11 @@ const sidebars = {
                   id: 'observability/tracing/exporters/langfuse',
                   label: 'Langfuse',
                 },
+                {
+                  type: 'doc',
+                  id: 'observability/tracing/exporters/langwatch',
+                  label: 'LangWatch',
+                },
                 {
                   type: 'doc',
                   id: 'observability/tracing/exporters/langsmith',

docs/src/content/en/reference/observability/tracing/exporters/langwatch.mdx

@@ -0,0 +1,161 @@
+---
+title: "Reference: LangwatchExporter | Observability"
+description: LangWatch LLM observability exporter for Tracing
+packages:
+  - "@mastra/langwatch"
+  - "@mastra/observability"
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# LangwatchExporter
+
+Sends Tracing data to [LangWatch](https://langwatch.ai) via OTLP/HTTP (protobuf) for LLM monitoring, evaluations, and analytics.
+
+## Constructor
+
+```typescript
+new LangwatchExporter(config?: LangwatchExporterConfig)
+```
+
+## LangwatchExporterConfig
+
+```typescript
+type LangwatchExporterConfig = Omit<OtelExporterConfig, "provider"> & {
+  apiKey?: string;
+  endpoint?: string;
+};
+```
+
+Extends `OtelExporterConfig` (minus `provider`), which includes:
+- `logLevel?: 'debug' | 'info' | 'warn' | 'error'` - Diagnostic log level
+- `timeout?: number` - Export timeout in milliseconds
+- `batchSize?: number` - Spans per batch
+- `customSpanFormatter?: CustomSpanFormatter` - Per-exporter span transformation
+- `resourceAttributes?: Record<string, string>` - Additional OTEL resource attributes
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "LangWatch API key. Falls back to LANGWATCH_API_KEY environment variable. Required — exporter is disabled without it.",
+      required: false,
+    },
+    {
+      name: "endpoint",
+      type: "string",
+      description: "LangWatch OTLP endpoint. Falls back to LANGWATCH_ENDPOINT env var, then defaults to https://app.langwatch.ai/api/otel/v1/traces. Override for self-hosted instances.",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to LangWatch. Only processes SPAN_ENDED events (complete spans with start and end times).
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to LangWatch without shutting down the exporter. Useful in serverless environments.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending spans and releases resources. Call when your application is terminating.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { LangwatchExporter } from "@mastra/langwatch";
+
+// Reads from LANGWATCH_API_KEY and optionally LANGWATCH_ENDPOINT
+const exporter = new LangwatchExporter();
+```
+
+### Explicit Configuration
+
+```typescript
+import { LangwatchExporter } from "@mastra/langwatch";
+
+const exporter = new LangwatchExporter({
+  apiKey: process.env.LANGWATCH_API_KEY!,
+});
+```
+
+### Self-Hosted Instance
+
+```typescript
+import { LangwatchExporter } from "@mastra/langwatch";
+
+const exporter = new LangwatchExporter({
+  apiKey: process.env.LANGWATCH_API_KEY!,
+  endpoint: "https://your-instance.example.com/api/otel/v1/traces",
+});
+```
+
+### With Custom Span Formatter
+
+```typescript
+import { LangwatchExporter } from "@mastra/langwatch";
+import { SpanType } from "@mastra/core/observability";
+
+const exporter = new LangwatchExporter({
+  apiKey: process.env.LANGWATCH_API_KEY!,
+  customSpanFormatter: (span) => {
+    if (span.type === SpanType.AGENT_RUN) {
+      return {
+        ...span,
+        metadata: { ...span.metadata, team: "ml-ops" },
+      };
+    }
+    return span;
+  },
+});
+```
+
+### With Resource Attributes
+
+```typescript
+import { LangwatchExporter } from "@mastra/langwatch";
+
+const exporter = new LangwatchExporter({
+  apiKey: process.env.LANGWATCH_API_KEY!,
+  resourceAttributes: {
+    "deployment.environment": "production",
+    "service.version": "1.2.3",
+  },
+});
+```
+
+## Environment Variables
+
+The exporter reads configuration from these environment variables:
+
+| Variable             | Description                                                         |
+| -------------------- | ------------------------------------------------------------------- |
+| `LANGWATCH_API_KEY`  | LangWatch API key (required if not passed in config)                |
+| `LANGWATCH_ENDPOINT` | Custom OTLP endpoint (defaults to LangWatch cloud)                  |
+
+## Behavior
+
+- **Protocol**: OTLP/HTTP with protobuf encoding
+- **Authentication**: Bearer token via `Authorization` header
+- **Batching**: Uses `BatchSpanProcessor` with configurable batch size (default: 512)
+- **Disabled state**: If no API key is provided, the exporter logs a warning and becomes a no-op
+- **Extends**: `OtelExporter` from `@mastra/otel-exporter` — inherits OpenTelemetry GenAI semantic conventions

docs/src/content/en/reference/sidebars.js

@@ -408,6 +408,11 @@ const sidebars = {
                   id: 'observability/tracing/exporters/langfuse',
                   label: 'Langfuse',
                 },
+                {
+                  type: 'doc',
+                  id: 'observability/tracing/exporters/langwatch',
+                  label: 'LangWatch',
+                },
                 {
                   type: 'doc',
                   id: 'observability/tracing/exporters/langsmith',

observability/langwatch/CHANGELOG.md

@@ -0,0 +1 @@
+# @mastra/langwatch