@mastra/mcp-docs-server 1.1.5 → 1.1.6

package/.docs/docs/observability/tracing/exporters/langfuse.md

@@ -0,0 +1,213 @@
+# 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-4o',
+  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/.docs/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/)