Configuration

ObservabilityRegistryConfig

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

interface ObservabilityInstanceConfig {
  name: string
  serviceName: string
  sampling?: SamplingStrategy
  exporters?: ObservabilityExporter[]
  retainStorageExporterOnPlatform?: boolean
  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

retainStorageExporterOnPlatform:

boolean

Defaults to false. Retains configured MastraStorageExporter instances on Platform, including later registration. Known local storage remains blocked, and deprecated DefaultExporter remains disabled. See storage export on Platform for configuration, adapter requirements, and restrictions.

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 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 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: 131072)

maxDepth?:

number

Maximum depth for nested objects (default: 8)

maxArrayLength?:

number

Maximum number of items in arrays (default: 50)

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 for details.

{ enabled?: boolean; level?: LogLevel }

enabled?:

boolean

Set to false to disable log forwarding to observability storage (default: true)

level?:

LogLevel

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

SamplingStrategy

type SamplingStrategy =
  | { type: 'always' }
  | { type: 'never' }
  | { type: 'ratio'; probability: number }
  | { type: 'custom'; sampler: (options?: CustomSamplerOptions) => boolean }

CustomSamplerOptions

interface CustomSamplerOptions {
  requestContext?: RequestContext
  metadata?: Record<string, any>
}

ConfigSelector

type ConfigSelector = (
  options: ConfigSelectorOptions,
  availableConfigs: ReadonlyMap<string, ObservabilityInstance>,
) => string | undefined

ConfigSelectorOptions

interface ConfigSelectorOptions {
  requestContext?: RequestContext
}

Registry methods

The Observability class provides methods for managing observability instances:

registerInstance

registerInstance(
  name: string,
  instance: ObservabilityInstance,
  isDefault?: boolean
): void;

Registers an observability instance in the registry.

getInstance

getInstance(name: string): ObservabilityInstance | undefined;

Retrieves an observability instance by name.

getDefaultInstance

getDefaultInstance(): ObservabilityInstance | undefined;

Returns the default observability instance.

getSelectedInstance

getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;

Returns the observability instance selected by the config selector or default.

listInstances

listInstances(): ReadonlyMap<string, ObservabilityInstance>;

Returns all registered observability instances.

hasInstance

hasInstance(name: string): boolean;

Checks if an observability instance exists.

setConfigSelector

setConfigSelector(selector: ConfigSelector): void;

Sets the config selector function.

unregisterInstance

unregisterInstance(name: string): boolean;

Removes an observability instance from the registry.

clear

clear(): void;

Clears all instances without shutdown.

shutdown

async shutdown(): Promise<void>;

Shuts down all observability instances and clears the registry.

See also

Documentation

• Tracing Overview: Concepts and usage guide
• Sampling Strategies: Sampling configuration details
• Multi-Config Setup: Using multiple configurations

Reference

• Tracing Classes: Core tracing classes
• Interfaces: Type definitions
• Spans Reference: Span lifecycle

Exporters

• MastraStorageExporter: Persists observability events to Mastra Storage
• MastraPlatformExporter: Sends observability events to Mastra platform
• Braintrust: Braintrust integration
• Langfuse: Langfuse integration
• LangSmith: LangSmith integration
• Span filtering: Selectively exclude spans