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