@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-observability-tracing-configuration.md

@@ -0,0 +1,178 @@
+# Configuration
+
+## ObservabilityRegistryConfig
+
+```typescript
+interface ObservabilityRegistryConfig {
+  default?: { enabled?: boolean }
+  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
+  configSelector?: ConfigSelector
+}
+```
+
+## ObservabilityInstanceConfig
+
+```typescript
+interface ObservabilityInstanceConfig {
+  name: string
+  serviceName: string
+  sampling?: SamplingStrategy
+  exporters?: ObservabilityExporter[]
+  spanOutputProcessors?: SpanOutputProcessor[]
+  includeInternalSpans?: boolean
+  requestContextKeys?: string[]
+  serializationOptions?: SerializationOptions
+}
+```
+
+## SerializationOptions
+
+Options for controlling how span data is serialized before export. Use these to customize truncation limits for large payloads.
+
+```typescript
+interface SerializationOptions {
+  maxStringLength?: number
+  maxDepth?: number
+  maxArrayLength?: number
+  maxObjectKeys?: number
+}
+```
+
+## SamplingStrategy
+
+```typescript
+type SamplingStrategy =
+  | { type: 'always' }
+  | { type: 'never' }
+  | { type: 'ratio'; probability: number }
+  | { type: 'custom'; sampler: (options?: TracingOptions) => boolean }
+```
+
+## ConfigSelector
+
+```typescript
+type ConfigSelector = (
+  options: ConfigSelectorOptions,
+  availableConfigs: ReadonlyMap<string, ObservabilityInstance>,
+) => string | undefined
+```
+
+## ConfigSelectorOptions
+
+```typescript
+interface ConfigSelectorOptions {
+  requestContext?: RequestContext
+}
+```
+
+# Registry Methods
+
+The Observability class provides methods for managing observability instances:
+
+## registerInstance
+
+```typescript
+registerInstance(
+  name: string,
+  instance: ObservabilityInstance,
+  isDefault?: boolean
+): void;
+```
+
+Registers an observability instance in the registry.
+
+## getInstance
+
+```typescript
+getInstance(name: string): ObservabilityInstance | undefined;
+```
+
+Retrieves an observability instance by name.
+
+## getDefaultInstance
+
+```typescript
+getDefaultInstance(): ObservabilityInstance | undefined;
+```
+
+Returns the default observability instance.
+
+## getSelectedInstance
+
+```typescript
+getSelectedInstance(
+  options: ConfigSelectorOptions
+): ObservabilityInstance | undefined;
+```
+
+Returns the observability instance selected by the config selector or default.
+
+## listInstances
+
+```typescript
+listInstances(): ReadonlyMap<string, ObservabilityInstance>;
+```
+
+Returns all registered observability instances.
+
+## hasInstance
+
+```typescript
+hasInstance(name: string): boolean;
+```
+
+Checks if an observability instance exists.
+
+## setConfigSelector
+
+```typescript
+setConfigSelector(selector: ConfigSelector): void;
+```
+
+Sets the config selector function.
+
+## unregisterInstance
+
+```typescript
+unregisterInstance(name: string): boolean;
+```
+
+Removes an observability instance from the registry.
+
+## clear
+
+```typescript
+clear(): void;
+```
+
+Clears all instances without shutdown.
+
+## shutdown
+
+```typescript
+async shutdown(): Promise<void>;
+```
+
+Shuts down all observability instances and clears the registry.
+
+## See Also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - Concepts and usage guide
+- [Sampling Strategies](https://mastra.ai/docs/observability/tracing/overview) - Sampling configuration details
+- [Multi-Config Setup](https://mastra.ai/docs/observability/tracing/overview) - Using multiple configurations
+
+### Reference
+
+- [Tracing Classes](https://mastra.ai/reference/observability/tracing/instances) - Core tracing classes
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) - Type definitions
+- [Spans Reference](https://mastra.ai/reference/observability/tracing/spans) - Span lifecycle
+
+### Exporters
+
+- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter) - Storage configuration
+- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) - Cloud setup
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust) - Braintrust integration
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse) - Langfuse integration
+- [LangSmith](https://mastra.ai/reference/observability/tracing/exporters/langsmith) - LangSmith integration

package/dist/docs/references/reference-observability-tracing-exporters-console-exporter.md

@@ -0,0 +1,138 @@
+# ConsoleExporter
+
+Outputs trace events to the console for debugging and development.
+
+## Constructor
+
+```typescript
+new ConsoleExporter(config?: BaseExporterConfig)
+```
+
+## BaseExporterConfig
+
+```typescript
+interface BaseExporterConfig {
+  logger?: IMastraLogger
+  logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'
+}
+```
+
+## Properties
+
+```typescript
+readonly name = 'tracing-console-exporter';
+```
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to the console.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Logs shutdown message.
+
+## Output Format
+
+The exporter outputs different formats based on event type:
+
+### SPAN\_STARTED
+
+```text
+🚀 SPAN_STARTED
+   Type: [span type]
+   Name: [span name]
+   ID: [span id]
+   Trace ID: [trace id]
+   Input: [formatted input]
+   Attributes: [formatted attributes]
+────────────────────────────────────────
+```
+
+### SPAN\_ENDED
+
+```text
+✅ SPAN_ENDED
+   Type: [span type]
+   Name: [span name]
+   ID: [span id]
+   Duration: [duration]ms
+   Trace ID: [trace id]
+   Input: [formatted input]
+   Output: [formatted output]
+   Error: [formatted error if present]
+   Attributes: [formatted attributes]
+────────────────────────────────────────
+```
+
+### SPAN\_UPDATED
+
+```text
+📝 SPAN_UPDATED
+   Type: [span type]
+   Name: [span name]
+   ID: [span id]
+   Trace ID: [trace id]
+   Input: [formatted input]
+   Output: [formatted output]
+   Error: [formatted error if present]
+   Updated Attributes: [formatted attributes]
+────────────────────────────────────────
+```
+
+## Usage
+
+```typescript
+import { ConsoleExporter } from '@mastra/observability'
+import { ConsoleLogger, LogLevel } from '@mastra/core/logger'
+
+// Use default logger (INFO level)
+const exporter = new ConsoleExporter()
+
+// Use custom log level
+const exporter = new ConsoleExporter({
+  logLevel: 'debug',
+})
+
+// Use custom logger instance
+const customLogger = new ConsoleLogger({ level: LogLevel.DEBUG })
+const exporterWithLogger = new ConsoleExporter({
+  logger: customLogger,
+})
+```
+
+## Implementation Details
+
+- Formats attributes as JSON with 2-space indentation
+- Calculates and displays span duration in milliseconds
+- Handles serialization errors gracefully
+- Logs unimplemented event types as warnings
+- Uses 80-character separator lines between events
+
+## See Also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - Complete guide
+- [Exporters](https://mastra.ai/docs/observability/tracing/overview) - Exporter concepts
+
+### Other 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
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse) - Langfuse integration
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust) - Braintrust integration
+
+### Reference
+
+- [Configuration](https://mastra.ai/reference/observability/tracing/configuration) - Configuration options
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) - Type definitions

package/dist/docs/references/reference-observability-tracing-exporters-datadog.md

@@ -0,0 +1,116 @@
+# DatadogExporter
+
+Sends Tracing data to Datadog's LLM Observability product for monitoring and analytics.
+
+## Constructor
+
+```typescript
+new DatadogExporter(config: DatadogExporterConfig)
+```
+
+## DatadogExporterConfig
+
+```typescript
+interface DatadogExporterConfig extends BaseExporterConfig {
+  apiKey?: string
+  mlApp?: string
+  site?: string
+  service?: string
+  env?: string
+  agentless?: boolean
+  integrationsEnabled?: 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 Datadog LLM Observability.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to Datadog 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 data and shuts down the exporter. Cancels any pending cleanup timers and disables LLM Observability.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { DatadogExporter } from '@mastra/datadog'
+
+// Reads from DD_LLMOBS_ML_APP, DD_API_KEY, DD_SITE, DD_ENV
+const exporter = new DatadogExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { DatadogExporter } from '@mastra/datadog'
+
+const exporter = new DatadogExporter({
+  mlApp: 'my-llm-app',
+  apiKey: process.env.DD_API_KEY,
+  site: 'datadoghq.com',
+  env: 'production',
+})
+```
+
+### With Local Datadog Agent
+
+```typescript
+const exporter = new DatadogExporter({
+  mlApp: 'my-llm-app',
+  agentless: false, // Use local Datadog Agent
+  env: 'production',
+})
+```
+
+## Span Mapping
+
+Mastra span types are mapped to Datadog LLMObs span kinds:
+
+| Mastra SpanType    | Datadog Kind |
+| ------------------ | ------------ |
+| `AGENT_RUN`        | `agent`      |
+| `MODEL_GENERATION` | `workflow`   |
+| `MODEL_STEP`       | `llm`        |
+| `TOOL_CALL`        | `tool`       |
+| `MCP_TOOL_CALL`    | `tool`       |
+| `WORKFLOW_RUN`     | `workflow`   |
+| All other types    | `task`       |
+
+All unmapped span types (including `MODEL_CHUNK`, `WORKFLOW_STEP`, `GENERIC`, and future span types) automatically default to `task`.
+
+## Environment Variables
+
+The exporter reads configuration from these environment variables:
+
+| Variable                      | Description                              |
+| ----------------------------- | ---------------------------------------- |
+| `DD_API_KEY`                  | Datadog API key                          |
+| `DD_LLMOBS_ML_APP`            | ML application name                      |
+| `DD_SITE`                     | Datadog site                             |
+| `DD_ENV`                      | Environment name                         |
+| `DD_LLMOBS_AGENTLESS_ENABLED` | Set to 'false' or '0' to use local agent |

package/dist/docs/references/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