@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/docs-observability-tracing-exporters-langsmith.md

@@ -0,0 +1,198 @@
+# LangSmith Exporter
+
+[LangSmith](https://smith.langchain.com/) is LangChain's platform for monitoring and evaluating LLM applications. The LangSmith exporter sends your traces to LangSmith, providing insights into model performance, debugging capabilities, and evaluation workflows.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/langsmith@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/langsmith@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/langsmith@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/langsmith@latest
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **LangSmith Account**: Sign up at [smith.langchain.com](https://smith.langchain.com)
+2. **API Key**: Generate an API key in LangSmith Settings → API Keys
+3. **Environment Variables**: Set your credentials
+
+```bash
+# Required
+LANGSMITH_API_KEY=ls-xxxxxxxxxxxx
+
+# Optional
+LANGCHAIN_PROJECT=my-project  # Default project for traces
+LANGSMITH_BASE_URL=https://api.smith.langchain.com  # For self-hosted
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { LangSmithExporter } from '@mastra/langsmith'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      langsmith: {
+        serviceName: 'my-service',
+        exporters: [new LangSmithExporter()],
+      },
+    },
+  }),
+})
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { LangSmithExporter } from '@mastra/langsmith'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      langsmith: {
+        serviceName: 'my-service',
+        exporters: [
+          new LangSmithExporter({
+            apiKey: process.env.LANGSMITH_API_KEY,
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new LangSmithExporter({
+  // Required credentials
+  apiKey: process.env.LANGSMITH_API_KEY!,
+
+  // Optional settings
+  apiUrl: process.env.LANGSMITH_BASE_URL, // Default: https://api.smith.langchain.com
+  projectName: 'my-project', // Project to send traces to (overrides LANGCHAIN_PROJECT env var)
+  callerOptions: {
+    // HTTP client options
+    timeout: 30000, // Request timeout in ms
+    maxRetries: 3, // Retry attempts
+  },
+  logLevel: 'info', // Diagnostic logging: debug | info | warn | error
+
+  // LangSmith-specific options
+  hideInputs: false, // Hide input data in UI
+  hideOutputs: false, // Hide output data in UI
+})
+```
+
+### Environment Variables
+
+| Variable             | Description                                                       |
+| -------------------- | ----------------------------------------------------------------- |
+| `LANGSMITH_API_KEY`  | Your LangSmith API key (required)                                 |
+| `LANGCHAIN_PROJECT`  | Default project name for traces (optional, defaults to "default") |
+| `LANGSMITH_BASE_URL` | API URL for self-hosted instances (optional)                      |
+
+The `projectName` config option takes precedence over the `LANGCHAIN_PROJECT` environment variable, allowing you to programmatically route traces to different projects.
+
+## Dynamic Configuration
+
+You can dynamically override LangSmith settings per-span using `withLangsmithMetadata`. This is useful for routing traces to different projects based on runtime conditions (e.g., customer, environment, or feature).
+
+### Using the Helper
+
+Use `withLangsmithMetadata` with `buildTracingOptions` to set LangSmith-specific options:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { buildTracingOptions } from '@mastra/observability'
+import { withLangsmithMetadata } from '@mastra/langsmith'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'support-agent',
+  instructions: 'You are a helpful support agent.',
+  model: 'openai/gpt-4o',
+  defaultOptions: {
+    tracingOptions: buildTracingOptions(withLangsmithMetadata({ projectName: 'customer-support' })),
+  },
+})
+```
+
+### Dynamic Project Routing
+
+Use `requestContext` to route traces to different projects based on runtime conditions.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { buildTracingOptions } from '@mastra/observability'
+import { withLangsmithMetadata } from '@mastra/langsmith'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'support-agent',
+  instructions: 'You are a helpful support agent.',
+  model: 'openai/gpt-4o',
+  defaultOptions: ({ requestContext }) => {
+    const userTier = requestContext?.get('user-tier') as string
+    const userId = requestContext?.get('user-id') as string
+
+    return {
+      tracingOptions: buildTracingOptions(
+        withLangsmithMetadata({
+          projectName: userTier === 'enterprise' ? 'enterprise-traces' : 'standard-traces',
+          sessionId: userId,
+        }),
+      ),
+    }
+  },
+})
+```
+
+### Available Fields
+
+The `withLangsmithMetadata` helper accepts these fields:
+
+| Field         | Type   | Description                         |
+| ------------- | ------ | ----------------------------------- |
+| `projectName` | string | Override the project for this trace |
+| `sessionId`   | string | Group related traces by session     |
+| `sessionName` | string | Display name for the session        |
+
+All fields are optional. The helper merges with any existing metadata, so you can call it multiple times or combine with other tracing options.
+
+## Related
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [LangSmith Documentation](https://docs.smith.langchain.com/)

package/dist/docs/references/docs-observability-tracing-exporters-otel.md

@@ -0,0 +1,476 @@
+# OpenTelemetry Exporter
+
+The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.
+
+> **Looking for bidirectional OTEL integration?:** If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](https://mastra.ai/docs/observability/tracing/bridges/otel) instead.
+
+## Installation
+
+Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:
+
+### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow)
+
+**npm**:
+
+```bash
+npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
+```
+
+### For gRPC Providers (Dash0, Datadog)
+
+**npm**:
+
+```bash
+npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+```
+
+### For HTTP/JSON Providers (Traceloop)
+
+**npm**:
+
+```bash
+npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
+```
+
+## 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)                            |
+
+## Provider Configurations
+
+### MLflow
+
+[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces land in the correct MLflow experiment:
+
+```typescript
+new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
+      protocol: 'http/protobuf',
+      headers: {
+        'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID,
+      },
+    },
+  },
+})
+```
+
+### Dash0
+
+[Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.
+
+#### Zero-Config Setup
+
+Set environment variables and use the exporter with an empty config:
+
+```bash
+# Required
+DASH0_API_KEY=your-api-key
+DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317
+
+# Optional
+DASH0_DATASET=production
+```
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { OtelExporter } from '@mastra/otel-exporter'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      otel: {
+        serviceName: 'my-service',
+        exporters: [new OtelExporter({ provider: { dash0: {} } })],
+      },
+    },
+  }),
+})
+```
+
+#### Explicit Configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { OtelExporter } from '@mastra/otel-exporter'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      otel: {
+        serviceName: 'my-service',
+        exporters: [
+          new OtelExporter({
+            provider: {
+              dash0: {
+                apiKey: process.env.DASH0_API_KEY,
+                endpoint: process.env.DASH0_ENDPOINT, // e.g., 'ingress.us-west-2.aws.dash0.com:4317'
+                dataset: 'production', // Optional dataset name
+              },
+            },
+            resourceAttributes: {
+              // Optional OpenTelemetry Resource Attributes for the trace
+              ['deployment.environment']: 'dev',
+            },
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+> **Info:** Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
+
+### SigNoz
+
+[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support.
+
+#### 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
+new OtelExporter({ provider: { signoz: {} } })
+```
+
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    signoz: {
+      apiKey: process.env.SIGNOZ_API_KEY,
+      region: 'us', // 'us' | 'eu' | 'in'
+      // endpoint: 'https://my-signoz.example.com', // For self-hosted
+    },
+  },
+})
+```
+
+### New Relic
+
+[New Relic](https://newrelic.com/) provides comprehensive observability with AI monitoring capabilities.
+
+#### 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
+new OtelExporter({ provider: { newrelic: {} } })
+```
+
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    newrelic: {
+      apiKey: process.env.NEW_RELIC_LICENSE_KEY,
+      // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region
+    },
+  },
+})
+```
+
+### Traceloop
+
+[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking.
+
+#### Zero-Config Setup
+
+```bash
+# Required
+TRACELOOP_API_KEY=your-api-key
+
+# Optional
+TRACELOOP_DESTINATION_ID=my-destination
+TRACELOOP_ENDPOINT=https://custom.traceloop.com
+```
+
+```typescript
+new OtelExporter({ provider: { traceloop: {} } })
+```
+
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    traceloop: {
+      apiKey: process.env.TRACELOOP_API_KEY,
+      destinationId: 'my-destination', // Optional
+    },
+  },
+})
+```
+
+### Laminar
+
+[Laminar](https://laminar.sh/) provides specialized LLM observability and analytics.
+
+#### Zero-Config Setup
+
+```bash
+# Required
+LMNR_PROJECT_API_KEY=your-api-key
+
+# Optional
+LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
+```
+
+```typescript
+new OtelExporter({ provider: { laminar: {} } })
+```
+
+#### Explicit Configuration
+
+```typescript
+new OtelExporter({
+  provider: {
+    laminar: {
+      apiKey: process.env.LMNR_PROJECT_API_KEY,
+    },
+  },
+})
+```
+
+> **Laminar-Native Exporter:** For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](https://mastra.ai/docs/observability/tracing/exporters/laminar) exporter instead. It provides optimized integration with Laminar's platform.
+
+### Datadog
+
+[Datadog](https://www.datadoghq.com/) APM provides application performance monitoring with distributed tracing. To send traces to Datadog via OTLP, you need the Datadog Agent running with OTLP ingestion enabled.
+
+Datadog uses gRPC for OTLP ingestion, which requires explicit imports and [bundler configuration](https://mastra.ai/reference/configuration) to work correctly:
+
+```typescript
+// Explicitly import gRPC dependencies for the bundler
+import '@grpc/grpc-js'
+import '@opentelemetry/exporter-trace-otlp-grpc'
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { OtelExporter, type ExportProtocol } from '@mastra/otel-exporter'
+
+export const mastra = new Mastra({
+  // Add grpc-js to externals so it's handled at runtime
+  bundler: {
+    externals: ['@grpc/grpc-js'],
+  },
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-service',
+        exporters: [
+          new OtelExporter({
+            provider: {
+              custom: {
+                endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
+                protocol: (process.env.OTEL_EXPORTER_OTLP_PROTOCOL || 'grpc') as ExportProtocol,
+                headers: {},
+              },
+            },
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+> **Info:** The Datadog Agent must be configured with OTLP ingestion enabled. Add the following to your `datadog.yaml`:
+>
+> ```yaml
+> otlp_config:
+>   receiver:
+>     protocols:
+>       grpc:
+>         endpoint: 0.0.0.0:4317
+> ```
+>
+> The default OTLP endpoint is `http://localhost:4317` when running the Datadog Agent locally.
+
+> **Warning:** The explicit imports of `@grpc/grpc-js` and `@opentelemetry/exporter-trace-otlp-grpc` at the top of the file, along with the [`bundler.externals`](https://mastra.ai/reference/configuration) configuration, are required for the gRPC transport to work correctly. Without these, you may encounter connection issues.
+
+> **Datadog-Native Exporter:** For Datadog-specific features like automatic span type mapping, LLM span categorization, and simplified setup without gRPC configuration, consider using the dedicated [`@mastra/datadog`](https://mastra.ai/docs/observability/tracing/exporters/datadog) exporter instead. It provides optimized integration with Datadog's APM platform.
+
+### Custom/Generic OTEL Endpoints
+
+For other OTEL-compatible platforms or custom collectors:
+
+```typescript
+new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: 'https://your-collector.example.com/v1/traces',
+      protocol: 'http/protobuf', // 'http/json' | 'http/protobuf' | 'grpc'
+      headers: {
+        'x-api-key': process.env.API_KEY,
+      },
+    },
+  },
+})
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new OtelExporter({
+  // Provider configuration (required)
+  provider: {
+    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
+  },
+
+  // Export configuration
+  timeout: 30000, // Export timeout in milliseconds
+  batchSize: 100, // Number of spans per batch
+
+  // Debug options
+  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
+})
+```
+
+## OpenTelemetry Semantic Conventions
+
+The exporter follows [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai), ensuring compatibility with observability platforms:
+
+### Span Naming
+
+- **LLM Operations**: `chat {model}`
+- **Tool Execution**: `execute_tool {tool_name}`
+- **Agent Runs**: `invoke_agent {agent_id}`
+- **Workflow Runs**: `invoke_workflow {workflow_id}`
+
+### Key Attributes
+
+- `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
+- `gen_ai.provider.name` - AI provider (openai, anthropic, etc.)
+- `gen_ai.request.model` - Model identifier
+- `gen_ai.input.messages` - Chat history provided to the model
+- `gen_ai.output.messages` - Messages returned by the model
+- `gen_ai.usage.input_tokens` - Number of input tokens
+- `gen_ai.usage.output_tokens` - Number of output tokens
+- `gen_ai.request.temperature` - Sampling temperature
+- `gen_ai.response.finish_reasons` - Completion reasons
+
+## Protocol Selection Guide
+
+Choose the right protocol package based on your provider:
+
+| Provider  | Protocol      | Required Package                           |
+| --------- | ------------- | ------------------------------------------ |
+| Dash0     | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
+| Datadog   | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
+| SigNoz    | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| Traceloop | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  |
+| Laminar   | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| Custom    | Varies        | Depends on your collector                  |
+
+> **Warning:** Make sure to install the correct protocol package for your provider. The exporter will provide a helpful error message if the wrong package is installed.
+
+## Troubleshooting
+
+### Missing Dependency Error
+
+If you see an error like:
+
+```text
+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
+```
+
+Install the suggested package for your provider.
+
+### Common Issues
+
+1. **Wrong protocol package**: Verify you installed the correct exporter for your provider
+2. **Invalid endpoint**: Check endpoint format matches provider requirements
+3. **Authentication failures**: Verify API keys and headers are correct
+
+## Related
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [OpenTelemetry Bridge](https://mastra.ai/docs/observability/tracing/bridges/otel)
+- [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
+- [OTEL Exporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)