@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/observability/tracing/exporters/langsmith.md

@@ -0,0 +1,108 @@
+# LangSmithExporter
+
+Sends Tracing data to LangSmith for observability.
+
+## Constructor
+
+```typescript
+new LangSmithExporter(config: LangSmithExporterConfig)
+```
+
+## LangSmithExporterConfig
+
+```typescript
+interface LangSmithExporterConfig extends ClientConfig, BaseExporterConfig {
+  client?: Client
+  projectName?: string
+}
+```
+
+Extends both `ClientConfig` (from LangSmith SDK) and `BaseExporterConfig`:
+
+- From `BaseExporterConfig`: `logger?: IMastraLogger`, `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'`
+- From `ClientConfig`: `apiKey`, `apiUrl`, `callerOptions`, `hideInputs`, `hideOutputs`, etc.
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to LangSmith.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any pending spans to LangSmith without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Ends all active spans and clears the trace map.
+
+## Usage
+
+```typescript
+import { LangSmithExporter } from '@mastra/langsmith'
+
+const exporter = new LangSmithExporter({
+  apiKey: process.env.LANGSMITH_API_KEY,
+  projectName: 'my-project', // Optional: specify which project to send traces to
+  apiUrl: 'https://api.smith.langchain.com',
+  logLevel: 'info',
+})
+```
+
+## Environment Variables
+
+| Variable             | Description                                                           |
+| -------------------- | --------------------------------------------------------------------- |
+| `LANGSMITH_API_KEY`  | Your LangSmith API key                                                |
+| `LANGCHAIN_PROJECT`  | Default project name for traces (used if `projectName` not specified) |
+| `LANGSMITH_BASE_URL` | API URL for self-hosted instances                                     |
+
+## Span Type Mapping
+
+| Span Type          | LangSmith Type |
+| ------------------ | -------------- |
+| `MODEL_GENERATION` | `llm`          |
+| `MODEL_CHUNK`      | `llm`          |
+| `TOOL_CALL`        | `tool`         |
+| `MCP_TOOL_CALL`    | `tool`         |
+| All others         | `chain`        |
+
+## withLangsmithMetadata
+
+Helper function to add LangSmith-specific metadata to tracing options.
+
+```typescript
+function withLangsmithMetadata(metadata: LangSmithMetadataInput): TracingOptionsUpdater
+```
+
+### LangSmithMetadataInput
+
+### Usage
+
+```typescript
+import { buildTracingOptions } from '@mastra/observability'
+import { withLangsmithMetadata } from '@mastra/langsmith'
+
+// Route to a specific project
+const tracingOptions = buildTracingOptions(withLangsmithMetadata({ projectName: 'my-project' }))
+
+// Set multiple fields
+const tracingOptions = buildTracingOptions(
+  withLangsmithMetadata({
+    projectName: 'my-project',
+    sessionId: 'user-123',
+  }),
+)
+```

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -0,0 +1,199 @@
+# OtelExporter
+
+Sends Tracing data to any OpenTelemetry-compatible observability platform using standardized GenAI semantic conventions.
+
+## Constructor
+
+```typescript
+new OtelExporter(config: OtelExporterConfig)
+```
+
+## OtelExporterConfig
+
+```typescript
+interface OtelExporterConfig {
+  provider?: ProviderConfig
+  timeout?: number
+  batchSize?: number
+  logLevel?: 'debug' | 'info' | 'warn' | 'error'
+}
+```
+
+## Provider Configurations
+
+### Dash0Config
+
+```typescript
+interface Dash0Config {
+  apiKey?: string
+  endpoint?: string
+  dataset?: string
+}
+```
+
+### SignozConfig
+
+```typescript
+interface SignozConfig {
+  apiKey?: string
+  region?: 'us' | 'eu' | 'in'
+  endpoint?: string
+}
+```
+
+### NewRelicConfig
+
+```typescript
+interface NewRelicConfig {
+  apiKey?: string
+  endpoint?: string
+}
+```
+
+### TraceloopConfig
+
+```typescript
+interface TraceloopConfig {
+  apiKey?: string
+  destinationId?: string
+  endpoint?: string
+}
+```
+
+### LaminarConfig
+
+```typescript
+interface LaminarConfig {
+  apiKey?: string
+  endpoint?: string
+}
+```
+
+### CustomConfig
+
+```typescript
+interface CustomConfig {
+  endpoint: string
+  protocol?: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'
+  headers?: Record<string, string>
+}
+```
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to the configured OTEL backend.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to the OTEL backend without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending traces and shuts down the exporter.
+
+## Usage Examples
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter'
+
+// Set SIGNOZ_API_KEY, SIGNOZ_REGION environment variables
+const exporter = new OtelExporter({ provider: { signoz: {} } })
+
+// Or for other providers:
+// Set DASH0_API_KEY, DASH0_ENDPOINT for Dash0
+// Set NEW_RELIC_LICENSE_KEY for New Relic
+// Set TRACELOOP_API_KEY for Traceloop
+// Set LMNR_PROJECT_API_KEY for Laminar
+```
+
+### Explicit Configuration
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter'
+
+const exporter = new OtelExporter({
+  provider: {
+    signoz: {
+      apiKey: process.env.SIGNOZ_API_KEY,
+      region: 'us',
+    },
+  },
+})
+```
+
+### With Custom Endpoint
+
+```typescript
+const exporter = new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: 'https://my-collector.example.com/v1/traces',
+      protocol: 'http/protobuf',
+      headers: {
+        'x-api-key': process.env.API_KEY,
+      },
+    },
+  },
+  timeout: 60000,
+  logLevel: 'debug',
+})
+```
+
+## Protocol Requirements
+
+Different providers require different OTEL exporter packages:
+
+| Protocol      | Required Package                           | Providers                  |
+| ------------- | ------------------------------------------ | -------------------------- |
+| gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  | Dash0                      |
+| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | SigNoz, New Relic, Laminar |
+| HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  | Traceloop, Custom          |
+| Zipkin        | `@opentelemetry/exporter-zipkin`           | Zipkin collectors          |
+
+## Tags Support
+
+The OtelExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are stored as the `mastra.tags` attribute.
+
+### Usage
+
+```typescript
+const result = await agent.generate('Hello', {
+  tracingOptions: {
+    tags: ['production', 'experiment-v2', 'user-request'],
+  },
+})
+```
+
+### How Tags Are Stored
+
+Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute for maximum backend compatibility:
+
+```json
+{
+  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
+}
+```
+
+> **Note:** While the OpenTelemetry specification supports native array attributes, many backends (Jaeger, Zipkin, Tempo) have limited array support. JSON strings ensure consistent behavior across all observability platforms.
+
+## Related
+
+- [OtelExporter Guide](https://mastra.ai/docs/observability/tracing/exporters/otel) - Setup guide with provider configurations
+- [OtelBridge](https://mastra.ai/docs/observability/tracing/bridges/otel) - For bidirectional OTEL context integration
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - General tracing concepts

package/.docs/reference/observability/tracing/exporters/posthog.md

@@ -0,0 +1,92 @@
+# PosthogExporter
+
+Sends Tracing data to PostHog for AI observability and analytics.
+
+## Constructor
+
+```typescript
+new PosthogExporter(config: PosthogExporterConfig)
+```
+
+## PosthogExporterConfig
+
+```typescript
+interface PosthogExporterConfig extends BaseExporterConfig {
+  apiKey?: string
+  host?: string
+  flushAt?: number
+  flushInterval?: number
+  serverless?: boolean
+  defaultDistinctId?: string
+  enablePrivacyMode?: boolean
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to PostHog.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to PostHog without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending batched events and shuts down the PostHog client.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { PosthogExporter } from '@mastra/posthog'
+
+// Reads from POSTHOG_API_KEY, POSTHOG_HOST
+const exporter = new PosthogExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { PosthogExporter } from '@mastra/posthog'
+
+const exporter = new PosthogExporter({
+  apiKey: process.env.POSTHOG_API_KEY!,
+  host: 'https://us.i.posthog.com',
+  serverless: true,
+})
+```
+
+## Span Type Mapping
+
+| Mastra Span Type    | PostHog Event Type |
+| ------------------- | ------------------ |
+| `MODEL_GENERATION`  | `$ai_generation`   |
+| `MODEL_STEP`        | `$ai_generation`   |
+| `MODEL_CHUNK`       | `$ai_span`         |
+| `TOOL_CALL`         | `$ai_span`         |
+| `MCP_TOOL_CALL`     | `$ai_span`         |
+| `PROCESSOR_RUN`     | `$ai_span`         |
+| `AGENT_RUN`         | `$ai_span`         |
+| `WORKFLOW_RUN`      | `$ai_span`         |
+| All other workflows | `$ai_span`         |
+| `GENERIC`           | `$ai_span`         |

package/.docs/reference/observability/tracing/exporters/sentry.md

@@ -0,0 +1,184 @@
+# SentryExporter
+
+Sends Tracing data to Sentry for AI tracing and monitoring using OpenTelemetry semantic conventions.
+
+## Constructor
+
+```typescript
+new SentryExporter(config: SentryExporterConfig)
+```
+
+## SentryExporterConfig
+
+```typescript
+interface SentryExporterConfig extends BaseExporterConfig {
+  dsn?: string
+  environment?: string
+  tracesSampleRate?: number
+  release?: string
+  options?: Partial<Sentry.NodeOptions>
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Sentry. Handles SPAN\_STARTED, SPAN\_UPDATED, and SPAN\_ENDED events.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any pending spans to Sentry without shutting down the exporter. Waits up to 2 seconds for pending data to be sent. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Ends all active spans, clears internal state, and closes the Sentry connection. Waits up to 2 seconds for pending data to be sent.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { SentryExporter } from '@mastra/sentry'
+
+// Reads from SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE
+const exporter = new SentryExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { SentryExporter } from '@mastra/sentry'
+
+const exporter = new SentryExporter({
+  dsn: process.env.SENTRY_DSN,
+  environment: 'production',
+  tracesSampleRate: 1.0,
+  release: '1.0.0',
+})
+```
+
+### With Sampling
+
+```typescript
+const exporter = new SentryExporter({
+  dsn: process.env.SENTRY_DSN,
+  environment: 'production',
+  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
+})
+```
+
+### With Custom Sentry Options
+
+```typescript
+const exporter = new SentryExporter({
+  dsn: process.env.SENTRY_DSN,
+  environment: 'production',
+  options: {
+    integrations: [
+      // Custom Sentry integrations
+    ],
+    beforeSend: event => {
+      // Custom event processing
+      return event
+    },
+  },
+})
+```
+
+## Span Mapping
+
+Mastra span types are mapped to Sentry operations:
+
+| Mastra SpanType             | Sentry Operation       |
+| --------------------------- | ---------------------- |
+| `AGENT_RUN`                 | `gen_ai.invoke_agent`  |
+| `MODEL_GENERATION`          | `gen_ai.chat`          |
+| `MODEL_STEP`                | _(skipped)_            |
+| `MODEL_CHUNK`               | _(skipped)_            |
+| `TOOL_CALL`                 | `gen_ai.execute_tool`  |
+| `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  |
+| `WORKFLOW_RUN`              | `workflow.run`         |
+| `WORKFLOW_STEP`             | `workflow.step`        |
+| `WORKFLOW_CONDITIONAL`      | `workflow.conditional` |
+| `WORKFLOW_CONDITIONAL_EVAL` | `workflow.conditional` |
+| `WORKFLOW_PARALLEL`         | `workflow.parallel`    |
+| `WORKFLOW_LOOP`             | `workflow.loop`        |
+| `WORKFLOW_SLEEP`            | `workflow.sleep`       |
+| `WORKFLOW_WAIT_EVENT`       | `workflow.wait`        |
+| `PROCESSOR_RUN`             | `ai.processor`         |
+| `GENERIC`                   | `ai.span`              |
+
+MODEL\_STEP and MODEL\_CHUNK spans are skipped to simplify trace hierarchy. Their data is aggregated into MODEL\_GENERATION spans.
+
+## Environment Variables
+
+The exporter reads configuration from these environment variables:
+
+| Variable             | Description                                           |
+| -------------------- | ----------------------------------------------------- |
+| `SENTRY_DSN`         | Data Source Name - tells the SDK where to send events |
+| `SENTRY_ENVIRONMENT` | Deployment environment name                           |
+| `SENTRY_RELEASE`     | Version of your code deployed                         |
+
+## OpenTelemetry Attributes
+
+The exporter sets these standard OpenTelemetry attributes:
+
+**Common attributes (all spans):**
+
+- `sentry.origin`: `auto.ai.mastra` (identifies spans from Mastra)
+- `ai.span.type`: Mastra span type
+
+**MODEL\_GENERATION spans:**
+
+- `gen_ai.operation.name`: `chat`
+- `gen_ai.system`: Model provider
+- `gen_ai.request.model`: Model identifier
+- `gen_ai.request.messages`: Input messages/prompts (JSON)
+- `gen_ai.response.model`: Response model
+- `gen_ai.response.text`: Output text
+- `gen_ai.response.tool_calls`: Tool calls made during generation (JSON array)
+- `gen_ai.usage.input_tokens`: Input token count
+- `gen_ai.usage.output_tokens`: Output token count
+- `gen_ai.usage.total_tokens`: Total tokens
+- `gen_ai.request.stream`: Streaming flag
+- `gen_ai.request.temperature`: Temperature parameter
+- `gen_ai.completion_start_time`: First token time
+
+**TOOL\_CALL spans:**
+
+- `gen_ai.operation.name`: `execute_tool`
+- `gen_ai.tool.name`: Tool identifier
+- `gen_ai.tool.type`: `function`
+- `gen_ai.tool.call.id`: Tool call ID
+- `gen_ai.tool.input`: Tool input
+- `gen_ai.tool.output`: Tool output
+- `tool.success`: Success flag
+
+**AGENT\_RUN spans:**
+
+- `gen_ai.operation.name`: `invoke_agent`
+- `gen_ai.agent.name`: Agent identifier
+- `gen_ai.pipeline.name`: Agent name
+- `gen_ai.agent.instructions`: Agent instructions
+- `gen_ai.response.model`: Model from child generation
+- `gen_ai.response.text`: Output from child generation
+- `gen_ai.usage.*`: Token usage from child generation

package/.docs/reference/observability/tracing/instances.md

@@ -0,0 +1,107 @@
+# Observability Instances
+
+## DefaultObservabilityInstance
+
+Default implementation of the ObservabilityInstance interface.
+
+### Constructor
+
+```typescript
+new DefaultObservabilityInstance(config: ObservabilityInstanceConfig)
+```
+
+Creates a new DefaultObservabilityInstance with the specified configuration.
+
+### Properties
+
+Inherits all properties and methods from BaseObservabilityInstance.
+
+## BaseObservabilityInstance
+
+Base class for custom ObservabilityInstance implementations.
+
+### Methods
+
+#### getConfig
+
+```typescript
+getConfig(): Readonly<Required<ObservabilityInstanceConfig>>
+```
+
+Returns the current observability configuration.
+
+#### getExporters
+
+```typescript
+getExporters(): readonly ObservabilityExporter[]
+```
+
+Returns all configured exporters.
+
+#### getSpanOutputProcessors
+
+```typescript
+getSpanOutputProcessors(): readonly SpanOutputProcessor[]
+```
+
+Returns all configured span output processors.
+
+#### getLogger
+
+```typescript
+getLogger(): IMastraLogger
+```
+
+Returns the logger instance for exporters and other components.
+
+#### startSpan
+
+```typescript
+startSpan<TType extends SpanType>(
+  options: StartSpanOptions<TType>
+): Span<TType>
+```
+
+Start a new span of a specific SpanType. Creates the root span of a trace if no parent is provided.
+
+#### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Shuts down all exporters and processors, cleaning up resources.
+
+## Custom Implementation
+
+To create a custom ObservabilityInstance implementation, extend BaseObservabilityInstance:
+
+```typescript
+class CustomObservabilityInstance extends BaseObservabilityInstance {
+  constructor(config: ObservabilityInstanceConfig) {
+    super(config)
+    // Custom initialization
+  }
+
+  // Override methods as needed
+  startSpan<TType extends SpanType>(options: StartSpanOptions<TType>): Span<TType> {
+    // Custom span creation logic
+    return super.startSpan(options)
+  }
+}
+```
+
+## See Also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - Concepts and usage guide
+- [Configuration Reference](https://mastra.ai/reference/observability/tracing/configuration) - Configuration options
+- [Interfaces Reference](https://mastra.ai/reference/observability/tracing/interfaces) - Type definitions
+- [Spans Reference](https://mastra.ai/reference/observability/tracing/spans) - Span lifecycle and methods
+
+### Exporters
+
+- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter) - Storage persistence
+- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) - Mastra Cloud integration
+- [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter) - Debug output