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

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

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

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

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

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

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