@mastra/core/dist/docs/references/reference-observability-tracing-configuration.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# Configuration

## `ObservabilityRegistryConfig`

```typescript
interface ObservabilityRegistryConfig {
  default?: { enabled?: boolean }
  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
  configSelector?: ConfigSelector
  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions
}
```

**default** (`{ enabled?: boolean }`): Enable default configuration with MastraStorageExporter and MastraPlatformExporter

**configs** (`Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>`): Named observability instance configurations or pre-instantiated instances

**configSelector** (`ConfigSelector`): Runtime configuration selector function

**sensitiveDataFilter** (`boolean | SensitiveDataFilterOptions`): Controls whether a \[SensitiveDataFilter]\(/reference/observability/tracing/processors/sensitive-data-filter) is auto-applied to every configured instance. Defaults to \`true\`. Pass \`false\` to opt out, or pass a \`SensitiveDataFilterOptions\` object to customize fields, redaction token, or redaction style. If a config already includes a \`SensitiveDataFilter\` in \`spanOutputProcessors\`, it is not duplicated. Pre-instantiated instances are not modified.

## `ObservabilityInstanceConfig`

```typescript
interface ObservabilityInstanceConfig {
  name: string
  serviceName: string
  sampling?: SamplingStrategy
  exporters?: ObservabilityExporter[]
  spanOutputProcessors?: SpanOutputProcessor[]
  includeInternalSpans?: boolean
  excludeSpanTypes?: SpanType[]
  spanFilter?: (span: AnyExportedSpan) => boolean
  requestContextKeys?: string[]
  serializationOptions?: SerializationOptions
  logging?: { enabled?: boolean; level?: LogLevel }
}
```

**name** (`string`): Configuration identifier

**serviceName** (`string`): Service name in traces

**sampling** (`SamplingStrategy`): Sampling configuration (defaults to ALWAYS)

**exporters** (`ObservabilityExporter[]`): Trace data exporters

**spanOutputProcessors** (`SpanOutputProcessor[]`): Span output processors

**includeInternalSpans** (`boolean`): Include spans internal to Mastra operations

**excludeSpanTypes** (`SpanType[]`): Span types to exclude from export. Useful for reducing noise and costs in per-span billing platforms. See the \[Span filtering reference]\(/reference/observability/tracing/span-filtering) for details.

**spanFilter** (`(span: AnyExportedSpan) => boolean`): Filter function to control which spans are exported. Return true to keep, false to drop. Runs after excludeSpanTypes and spanOutputProcessors. See the \[Span filtering reference]\(/reference/observability/tracing/span-filtering) for details.

**requestContextKeys** (`string[]`): RequestContext keys to extract as metadata (supports dot notation)

**serializationOptions** (`SerializationOptions`): Options for controlling serialization of span data (input/output/attributes)

**serializationOptions.maxStringLength** (`number`): Maximum length for string values (default: 1024)

**serializationOptions.maxDepth** (`number`): Maximum depth for nested objects (default: 6)

**serializationOptions.maxArrayLength** (`number`): Maximum number of items in arrays (default: 50)

**serializationOptions.maxObjectKeys** (`number`): Maximum number of keys in objects (default: 50)

**logging** (`{ enabled?: boolean; level?: LogLevel }`): Controls log forwarding to observability storage. See \[Logging to observability storage]\(/docs/observability/logging#logging-to-observability-storage) for details.

**logging.enabled** (`boolean`): Set to false to disable log forwarding to observability storage (default: true)

**logging.level** (`LogLevel`): Minimum log level to forward. One of 'debug', 'info', 'warn', 'error', 'fatal' (default: 'debug')

## `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

- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter): Persists observability events to Mastra Storage
- [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter): Sends observability events to Mastra platform
- [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
- [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering): Selectively exclude spans