@mastra/core 1.18.1-alpha.0 → 1.19.0-alpha.2

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

@@ -1,213 +0,0 @@
-# Langfuse exporter
-
-[Langfuse](https://langfuse.com/) is an open-source observability platform specifically designed for LLM applications. The Langfuse exporter sends your traces to Langfuse, providing detailed insights into model performance, token usage, and conversation flows.
-
-## Installation
-
-**npm**:
-
-```bash
-npm install @mastra/langfuse@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/langfuse@latest
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/langfuse@latest
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/langfuse@latest
-```
-
-## Configuration
-
-### Prerequisites
-
-1. **Langfuse Account**: Sign up at [cloud.langfuse.com](https://cloud.langfuse.com) or deploy self-hosted
-2. **API Keys**: Create public/secret key pair in Langfuse Settings → API Keys
-3. **Environment Variables**: Set your credentials
-
-```bash
-LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxx
-LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxx
-LANGFUSE_BASE_URL=https://cloud.langfuse.com  # Or your self-hosted URL
-```
-
-### 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 { LangfuseExporter } from '@mastra/langfuse'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      langfuse: {
-        serviceName: 'my-service',
-        exporters: [new LangfuseExporter()],
-      },
-    },
-  }),
-})
-```
-
-### 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 { LangfuseExporter } from '@mastra/langfuse'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      langfuse: {
-        serviceName: 'my-service',
-        exporters: [
-          new LangfuseExporter({
-            publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
-            secretKey: process.env.LANGFUSE_SECRET_KEY!,
-            baseUrl: process.env.LANGFUSE_BASE_URL,
-            options: {
-              environment: process.env.NODE_ENV,
-            },
-          }),
-        ],
-      },
-    },
-  }),
-})
-```
-
-## Configuration options
-
-### Realtime vs Batch Mode
-
-The Langfuse exporter supports two modes for sending traces:
-
-#### Realtime Mode (Development)
-
-Traces appear immediately in Langfuse dashboard, ideal for debugging:
-
-```typescript
-new LangfuseExporter({
-  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
-  secretKey: process.env.LANGFUSE_SECRET_KEY!,
-  realtime: true, // Flush after each event
-})
-```
-
-#### Batch Mode (Production)
-
-Better performance with automatic batching:
-
-```typescript
-new LangfuseExporter({
-  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
-  secretKey: process.env.LANGFUSE_SECRET_KEY!,
-  realtime: false, // Default - batch traces
-})
-```
-
-### Complete Configuration
-
-```typescript
-new LangfuseExporter({
-  // Required credentials
-  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
-  secretKey: process.env.LANGFUSE_SECRET_KEY!,
-
-  // Optional settings
-  baseUrl: process.env.LANGFUSE_BASE_URL, // Default: https://cloud.langfuse.com
-  realtime: process.env.NODE_ENV === 'development', // Dynamic mode selection
-  logLevel: 'info', // Diagnostic logging: debug | info | warn | error
-
-  // Langfuse-specific options
-  options: {
-    environment: process.env.NODE_ENV, // Shows in UI for filtering
-    version: process.env.APP_VERSION, // Track different versions
-    release: process.env.GIT_COMMIT, // Git commit hash
-  },
-})
-```
-
-## Prompt linking
-
-You can link LLM generations to prompts stored in [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management). This enables version tracking and metrics for your prompts.
-
-### Using the Helper (Recommended)
-
-Use `withLangfusePrompt` with `buildTracingOptions` for the cleanest API:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { buildTracingOptions } from '@mastra/observability'
-import { withLangfusePrompt } from '@mastra/langfuse'
-import { Langfuse } from 'langfuse'
-
-// Reads credentials from LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, LANGFUSE_BASE_URL env vars
-const langfuse = new Langfuse()
-
-// Fetch the prompt from Langfuse Prompt Management
-const prompt = await langfuse.getPrompt('customer-support')
-
-export const supportAgent = new Agent({
-  name: 'support-agent',
-  instructions: prompt.prompt, // Use the prompt text from Langfuse
-  model: 'openai/gpt-5.4',
-  defaultGenerateOptions: {
-    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
-  },
-})
-```
-
-The `withLangfusePrompt` helper automatically extracts `name`, `version`, and `id` from the Langfuse prompt object.
-
-### Manual Fields
-
-You can also pass manual fields if you're not using the Langfuse SDK:
-
-```typescript
-const tracingOptions = buildTracingOptions(withLangfusePrompt({ name: 'my-prompt', version: 1 }))
-
-// Or with just an ID
-const tracingOptions = buildTracingOptions(withLangfusePrompt({ id: 'prompt-uuid-12345' }))
-```
-
-### Prompt Object Fields
-
-The prompt object supports these fields:
-
-| Field     | Type   | Description                        |
-| --------- | ------ | ---------------------------------- |
-| `name`    | string | The prompt name in Langfuse        |
-| `version` | number | The prompt version number          |
-| `id`      | string | The prompt UUID for direct linking |
-
-You can link prompts using either:
-
-- `id` alone (the UUID uniquely identifies a prompt version)
-- `name` + `version` together
-- All three fields
-
-When set on a `MODEL_GENERATION` span, the Langfuse exporter automatically links the generation to the corresponding prompt.
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [Langfuse Documentation](https://langfuse.com/docs)
-- [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management)

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

@@ -1,198 +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-5.4',
-  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-5.4',
-  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/)