npm - @mastra/core - Versions diffs - 1.6.0 → 1.7.0 - Mend

@mastra/core 1.6.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (453) hide show

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

@@ -1,202 +0,0 @@
-# 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 DELETED Viewed

@@ -1,479 +0,0 @@
-# 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)