@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/raw/reference/observability/ai-tracing/processors/sensitive-data-filter.mdx

@@ -1,178 +0,0 @@
----
-title: "SensitiveDataFilter | Processors | AI Tracing | Reference"
-description: API reference for the SensitiveDataFilter processor
----
-
-import { PropertiesTable } from "@/components/properties-table";
-
-# SensitiveDataFilter
-
-An AISpanProcessor that redacts sensitive information from span fields.
-
-## Constructor
-
-```typescript
-new SensitiveDataFilter(options?: SensitiveDataFilterOptions)
-```
-
-## SensitiveDataFilterOptions
-
-```typescript
-interface SensitiveDataFilterOptions {
-  /** 
-   * List of sensitive field names to redact.
-   * Matching is case-insensitive and normalizes separators 
-   * (api-key, api_key, Api Key → apikey).
-   * Defaults include: password, token, secret, key, apikey, auth, 
-   * authorization, bearer, bearertoken, jwt, credential, 
-   * clientsecret, privatekey, refresh, ssn.
-   */
-  sensitiveFields?: string[];
-  
-  /** 
-   * The token used for full redaction.
-   * Default: "[REDACTED]"
-   */
-  redactionToken?: string;
-  
-  /** 
-   * Style of redaction to use:
-   * - "full": always replace with redactionToken
-   * - "partial": show 3 characters from the start and end, redact the middle
-   * Default: "full"
-   */
-  redactionStyle?: RedactionStyle;
-}
-```
-
-<PropertiesTable
-  props={[
-    {
-      name: "sensitiveFields",
-      type: "string[]",
-      description: "Field names to redact (case-insensitive, separator-agnostic)",
-      required: false,
-    },
-    {
-      name: "redactionToken",
-      type: "string",
-      description: "Replacement token for full redaction",
-      required: false,
-    },
-    {
-      name: "redactionStyle",
-      type: "'full' | 'partial'",
-      description: "Redaction style",
-      required: false,
-    },
-  ]}
-/>
-
-## RedactionStyle
-
-```typescript
-type RedactionStyle = 'full' | 'partial';
-```
-
-## Methods
-
-### process
-
-```typescript
-process(span: AnyAISpan): AnyAISpan
-```
-
-Process a span by filtering sensitive data across its key fields: attributes, metadata, input, output, and errorInfo.
-
-<PropertiesTable
-  props={[
-    {
-      name: "span",
-      type: "AnyAISpan",
-      description: "The input span to filter",
-      required: true,
-    },
-  ]}
-/>
-
-**Returns:** A new span with sensitive values redacted.
-
-### shutdown
-
-```typescript
-async shutdown(): Promise<void>
-```
-
-No cleanup needed for this processor.
-
-## Properties
-
-```typescript
-readonly name = 'sensitive-data-filter';
-```
-
-## Default Sensitive Fields
-
-When no custom fields are provided:
-
-```typescript
-[
-  'password',
-  'token',
-  'secret',
-  'key',
-  'apikey',
-  'auth',
-  'authorization',
-  'bearer',
-  'bearertoken',
-  'jwt',
-  'credential',
-  'clientsecret',
-  'privatekey',
-  'refresh',
-  'ssn'
-]
-```
-
-## Processing Behavior
-
-### Field Matching
-
-- **Case-insensitive**: `APIKey`, `apikey`, `ApiKey` all match
-- **Separator-agnostic**: `api-key`, `api_key`, `apiKey` are treated identically  
-- **Exact matching**: After normalization, fields must match exactly
-  - `token` matches `token`, `Token`, `TOKEN`
-  - `token` does NOT match `promptTokens` or `tokenCount`
-
-### Redaction Styles
-
-#### Full Redaction (default)
-
-All matched values replaced with redactionToken.
-
-#### Partial Redaction
-
-- Shows first 3 and last 3 characters
-- Values ≤ 6 characters are fully redacted
-- Non-string values are converted to strings before partial redaction
-
-### Error Handling
-
-If filtering a field fails, the field is replaced with:
-
-```typescript
-{ error: { processor: "sensitive-data-filter" } }
-```
-
-### Processed Fields
-
-The filter recursively processes:
-
-- `span.attributes` - Span metadata and properties
-- `span.metadata` - Custom metadata
-- `span.input` - Input data
-- `span.output` - Output data  
-- `span.errorInfo` - Error information
-
-Handles nested objects, arrays, and circular references safely.

package/.docs/raw/reference/observability/ai-tracing/span.mdx

@@ -1,371 +0,0 @@
----
-title: "Span | AI Tracing | Reference"
-description: Span interfaces, methods, and lifecycle events
----
-
-import { PropertiesTable } from "@/components/properties-table";
-
-# Span
-
-## BaseSpan
-
-Base interface for all span types.
-
-```typescript
-interface BaseSpan<TType extends AISpanType> {
-  /** Unique span identifier */
-  id: string;
-  
-  /** OpenTelemetry-compatible trace ID (32 hex chars) */
-  traceId: string;
-  
-  /** Name of the span */
-  name: string;
-  
-  /** Type of the span */
-  type: TType;
-  
-  /** When span started */
-  startTime: Date;
-  
-  /** When span ended */
-  endTime?: Date;
-  
-  /** Type-specific attributes */
-  attributes?: AISpanTypeMap[TType];
-  
-  /** User-defined metadata */
-  metadata?: Record<string, any>;
-  
-  /** Input passed at the start of the span */
-  input?: any;
-  
-  /** Output generated at the end of the span */
-  output?: any;
-  
-  /** Error information if span failed */
-  errorInfo?: {
-    message: string;
-    id?: string;
-    domain?: string;
-    category?: string;
-    details?: Record<string, any>;
-  };
-  
-  /** Is an event span? (occurs at startTime, has no endTime) */
-  isEvent: boolean;
-}
-```
-
-## AISpan
-
-AI Span interface, used internally for tracing. Extends BaseSpan with lifecycle methods and properties.
-
-```typescript
-interface AISpan<TType extends AISpanType> extends BaseSpan<TType> {
-  /** Is an internal span? (spans internal to the operation of mastra) */
-  isInternal: boolean;
-  
-  /** Parent span reference (undefined for root spans) */
-  parent?: AnyAISpan;
-  
-  /** Pointer to the AITracing instance */
-  aiTracing: AITracing;
-}
-```
-
-### Properties
-
-```typescript
-/** Returns TRUE if the span is the root span of a trace */
-get isRootSpan(): boolean
-
-/** Returns TRUE if the span is a valid span (not a NO-OP Span) */
-get isValid(): boolean
-
-/** Get the closest parent spanId that isn't an internal span */
-getParentSpanId(includeInternalSpans?: boolean): string | undefined
-
-/** Returns a lightweight span ready for export */
-exportSpan(includeInternalSpans?: boolean): ExportedAISpan<TType> | undefined
-```
-
-### Methods
-
-#### end
-
-```typescript
-end(options?: EndSpanOptions<TType>): void
-```
-
-Ends the span and triggers export to configured exporters. Sets the `endTime` and optionally updates `output`, `metadata`, and `attributes`.
-
-<PropertiesTable
-  props={[
-    {
-      name: "output",
-      type: "any",
-      description: "Final output data from the operation",
-      required: false,
-    },
-    {
-      name: "metadata",
-      type: "Record<string, any>",
-      description: "Additional metadata to merge",
-      required: false,
-    },
-    {
-      name: "attributes",
-      type: "Partial<AISpanTypeMap[TType]>",
-      description: "Type-specific attributes to update",
-      required: false,
-    },
-  ]}
-/>
-
-#### error
-
-```typescript
-error(options: ErrorSpanOptions<TType>): void
-```
-
-Records an error on the span. Sets the `errorInfo` field and can optionally end the span.
-
-<PropertiesTable
-  props={[
-    {
-      name: "error",
-      type: "Error",
-      description: "The error that occurred",
-      required: true,
-    },
-    {
-      name: "endSpan",
-      type: "boolean",
-      description: "Whether to end the span after recording the error",
-      required: false,
-    },
-    {
-      name: "metadata",
-      type: "Record<string, any>",
-      description: "Additional error context metadata",
-      required: false,
-    },
-    {
-      name: "attributes",
-      type: "Partial<AISpanTypeMap[TType]>",
-      description: "Type-specific attributes to update",
-      required: false,
-    },
-  ]}
-/>
-
-#### update
-
-```typescript
-update(options: UpdateSpanOptions<TType>): void
-```
-
-Updates span data while it's still active. Can modify `input`, `output`, `metadata`, and `attributes`.
-
-<PropertiesTable
-  props={[
-    {
-      name: "input",
-      type: "any",
-      description: "Update or set input data",
-      required: false,
-    },
-    {
-      name: "output",
-      type: "any",
-      description: "Update or set output data",
-      required: false,
-    },
-    {
-      name: "metadata",
-      type: "Record<string, any>",
-      description: "Metadata to merge with existing",
-      required: false,
-    },
-    {
-      name: "attributes",
-      type: "Partial<AISpanTypeMap[TType]>",
-      description: "Type-specific attributes to update",
-      required: false,
-    },
-  ]}
-/>
-
-#### createChildSpan
-
-```typescript
-createChildSpan<TChildType extends AISpanType>(
-  options: ChildSpanOptions<TChildType>
-): AISpan<TChildType>
-```
-
-Creates a child span under this span. Child spans track sub-operations and inherit the trace context.
-
-<PropertiesTable
-  props={[
-    {
-      name: "type",
-      type: "TChildType",
-      description: "Type of the child span",
-      required: true,
-    },
-    {
-      name: "name",
-      type: "string",
-      description: "Name of the child span",
-      required: true,
-    },
-    {
-      name: "attributes",
-      type: "AISpanTypeMap[TChildType]",
-      description: "Type-specific attributes",
-      required: false,
-    },
-    {
-      name: "metadata",
-      type: "Record<string, any>",
-      description: "Initial metadata",
-      required: false,
-    },
-    {
-      name: "input",
-      type: "any",
-      description: "Initial input data",
-      required: false,
-    },
-  ]}
-/>
-
-#### createEventSpan
-
-```typescript
-createEventSpan<TChildType extends AISpanType>(
-  options: ChildEventOptions<TChildType>
-): AISpan<TChildType>
-```
-
-Creates an event span under this span. Event spans represent point-in-time occurrences with no duration.
-
-<PropertiesTable
-  props={[
-    {
-      name: "type",
-      type: "TChildType",
-      description: "Type of the event span",
-      required: true,
-    },
-    {
-      name: "name",
-      type: "string",
-      description: "Name of the event",
-      required: true,
-    },
-    {
-      name: "attributes",
-      type: "AISpanTypeMap[TChildType]",
-      description: "Type-specific attributes",
-      required: false,
-    },
-    {
-      name: "metadata",
-      type: "Record<string, any>",
-      description: "Event metadata",
-      required: false,
-    },
-    {
-      name: "input",
-      type: "any",
-      description: "Event input data",
-      required: false,
-    },
-    {
-      name: "output",
-      type: "any",
-      description: "Event output data",
-      required: false,
-    },
-  ]}
-/>
-
-## ExportedAISpan
-
-Exported AI Span interface, used for tracing exporters. A lightweight version of AISpan without methods or circular references.
-
-```typescript
-interface ExportedAISpan<TType extends AISpanType> extends BaseSpan<TType> {
-  /** Parent span id reference (undefined for root spans) */
-  parentSpanId?: string;
-  
-  /** TRUE if the span is the root span of a trace */
-  isRootSpan: boolean;
-}
-```
-
-## Span Lifecycle Events
-
-Events emitted during the span lifecycle.
-
-### AITracingEventType
-
-```typescript
-enum AITracingEventType {
-  /** Emitted when a span is created and started */
-  SPAN_STARTED = 'span_started',
-  
-  /** Emitted when a span is updated via update() */
-  SPAN_UPDATED = 'span_updated',
-  
-  /** Emitted when a span is ended via end() or error() */
-  SPAN_ENDED = 'span_ended',
-}
-```
-
-### AITracingEvent
-
-```typescript
-type AITracingEvent =
-  | { type: 'span_started'; exportedSpan: AnyExportedAISpan }
-  | { type: 'span_updated'; exportedSpan: AnyExportedAISpan }
-  | { type: 'span_ended'; exportedSpan: AnyExportedAISpan };
-```
-
-Exporters receive these events to process and send trace data to observability platforms.
-
-## Union Types
-
-### AnyAISpan
-
-```typescript
-type AnyAISpan = AISpan<keyof AISpanTypeMap>;
-```
-
-Union type for cases that need to handle any span type.
-
-### AnyExportedAISpan
-
-```typescript
-type AnyExportedAISpan = ExportedAISpan<keyof AISpanTypeMap>;
-```
-
-Union type for cases that need to handle any exported span type.
-
-## See Also
-
-### Documentation
-- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Concepts and usage
-- [Creating Child Spans](/docs/observability/ai-tracing/overview#creating-child-spans) - Practical examples
-- [Retrieving Trace IDs](/docs/observability/ai-tracing/overview#retrieving-trace-ids) - Using trace IDs
-
-### Reference
-- [AITracing Classes](/reference/observability/ai-tracing/ai-tracing) - Core tracing classes
-- [Interfaces](/reference/observability/ai-tracing/interfaces) - Complete type reference
-- [Configuration](/reference/observability/ai-tracing/configuration) - Configuration options
-
-### Examples
-- [Basic AI Tracing](/examples/observability/basic-ai-tracing) - Working with spans

package/.docs/raw/reference/observability/logging/pino-logger.mdx

@@ -1,148 +0,0 @@
----
-title: "Reference: PinoLogger | Mastra Observability Docs"
-description: Documentation for PinoLogger, which provides methods to record events at various severity levels.
----
-
-# PinoLogger
-
-A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
-
-When deploying to Mastra Cloud, logs are displayed on the [Logs](../../../docs/mastra-cloud/dashboard.mdx#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
-
-## Usage example
-
-```typescript filename="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from '@mastra/core/mastra';
-import { PinoLogger } from '@mastra/loggers';
-
-export const mastra = new Mastra({
-  // ...
-  logger: new PinoLogger({
-    name: 'Mastra',
-    level: 'info',
-  }),
-});
-```
-
-## Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: "name",
-      type: "string",
-      description: "A label used to group and identify logs from this logger.",
-    },
-     {
-      name: "level",
-      type: `"debug" | "info" | "warn" | "error"`,
-      description: "Sets the minimum log level. Messages below this level are ignored.",
-    },
-    {
-      name: "transports",
-      type: "Record<string, LoggerTransport>",
-      description: "A map of transport instances used to persist logs.",
-    },
-    {
-      name: "overrideDefaultTransports",
-      type: "boolean",
-      isOptional: true,
-      description: "If true, disables the default console transport.",
-    },
-    {
-      name: "formatters",
-      type: "pino.LoggerOptions['formatters']",
-      isOptional: true,
-      description: "Custom Pino formatters for log serialization.",
-    },
-  ]}
-/>
-
-
-## File transport (structured logs)
-
-Writes structured logs to a file using the `FileTransport`. The logger accepts a plain message as the first argument and structured metadata as the second argument. These are internally converted to a `BaseLogMessage` and persisted to the configured file path.
-
-
-```typescript filename="src/mastra/loggers/file-transport.ts" showLineNumbers copy
-import { FileTransport } from "@mastra/loggers/file";
-import { PinoLogger } from "@mastra/loggers/pino";
-
-export const fileLogger = new PinoLogger({
-  name: "Mastra",
-  transports: { file: new FileTransport({ path: "test-dir/test.log" }) },
-  level: "warn",
-});
-```
-
-### File transport usage
-
-```typescript showLineNumbers copy
-fileLogger.warn("Low disk space", {
-  destinationPath: "system",
-  type: "WORKFLOW",
-});
-```
-
-## Upstash transport (remote log drain)
-
-Streams structured logs to a remote Redis list using the `UpstashTransport`. The logger accepts a string message and a structured metadata object. This enables centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.
-
-```typescript filename="src/mastra/loggers/upstash-transport.ts" showLineNumbers copy
-import { UpstashTransport } from "@mastra/loggers/upstash";
-import { PinoLogger } from "@mastra/loggers/pino";
-
-export const upstashLogger = new PinoLogger({
-  name: "Mastra",
-  transports: {
-    upstash: new UpstashTransport({
-      listName: "production-logs",
-      upstashUrl: process.env.UPSTASH_URL!,
-      upstashToken: process.env.UPSTASH_TOKEN!,
-    }),
-  },
-  level: "info",
-});
-```
-
-
-### Upstash transport usage
-
-```typescript showLineNumbers copy
-upstashLogger.info("User signed in", {
-  destinationPath: "auth",
-  type: "AGENT",
-  runId: "run_123",
-});
-```
-
-## Custom transport
-
-You can create custom transports using the `createCustomTransport` utility to integrate with any logging service or stream.
-
-### Sentry transport example
-
-Creates a custom transport using `createCustomTransport` and integrates it with a third-party logging stream such as `pino-sentry-transport`. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.
-
-```typescript filename="src/mastra/loggers/sentry-transport.ts" showLineNumbers copy
-import { createCustomTransport } from "@mastra/core/loggers";
-import { PinoLogger } from "@mastra/loggers/pino";
-import pinoSentry from "pino-sentry-transport";
-
-const sentryStream = await pinoSentry({
-  sentry: {
-    dsn: "YOUR_SENTRY_DSN",
-    _experiments: {
-      enableLogs: true,
-    },
-  },
-});
-
-const customTransport = createCustomTransport(sentryStream);
-
-export const sentryLogger = new PinoLogger({
-  name: "Mastra",
-  level: "info",
-  transports: { sentry: customTransport },
-});
-```