https://mastra.ai/assets/js/14f1a0e1.a0e66331.js

1"use strict";(self.webpackChunkmastra_docs=self.webpackChunkmastra_docs||[]).push([["10051"],{95152(e,n,t){t.r(n),t.d(n,{metadata:()=>i,default:()=>g,frontMatter:()=>o,contentTitle:()=>l,toc:()=>d,assets:()=>c});var i=JSON.parse('{"id":"observability/tracing/configuration","title":"Reference: Configuration | Observability","description":"Configure Mastra observability instances, tracing exporters, sampling, propagation, span filters, and the global observability registry.","source":"@site/src/content/en/reference/observability/tracing/configuration.mdx","sourceDirName":"observability/tracing","slug":"/observability/tracing/configuration","permalink":"/reference/observability/tracing/configuration","draft":false,"unlisted":false,"editUrl":"https://github.com/mastra-ai/mastra/tree/main/docs/src/content/en/reference/observability/tracing/configuration.mdx","tags":[],"version":"current","frontMatter":{"title":"Reference: Configuration | Observability","description":"Configure Mastra observability instances, tracing exporters, sampling, propagation, span filters, and the global observability registry.","packages":["@mastra/core"]},"sidebar":"referenceSidebar","previous":{"title":"Metric queries","permalink":"/reference/observability/metrics/queries"},"next":{"title":"Advanced trace queries","permalink":"/reference/observability/tracing/trace-query"}}'),r=t(74848),s=t(28453),a=t(10107);let o={title:"Reference: Configuration | Observability",description:"Configure Mastra observability instances, tracing exporters, sampling, propagation, span filters, and the global observability registry.",packages:["@mastra/core"]},l="Configuration",c={},d=[{value:"<code>ObservabilityRegistryConfig</code>",id:"observabilityregistryconfig",level:2},{value:"<code>ObservabilityInstanceConfig</code>",id:"observabilityinstanceconfig",level:2},{value:"<code>SamplingStrategy</code>",id:"samplingstrategy",level:2},{value:"<code>ConfigSelector</code>",id:"configselector",level:2},{value:"<code>ConfigSelectorOptions</code>",id:"configselectoroptions",level:2},{value:"Registry methods",id:"registry-methods",level:2},{value:"<code>registerInstance</code>

1",id:"registerinstance",level:3},{value:"<code>getInstance</code>",id:"getinstance",level:3},{value:"<code>getDefaultInstance</code>",id:"getdefaultinstance",level:3},{value:"<code>getSelectedInstance</code>",id:"getselectedinstance",level:3},{value:"<code>listInstances</code>",id:"listinstances",level:3},{value:"<code>hasInstance</code>",id:"hasinstance",level:3},{value:"<code>setConfigSelector</code>",id:"setconfigselector",level:3},{value:"<code>unregisterInstance</code>",id:"unregisterinstance",level:3},{value:"clear",id:"clear",level:3},{value:"shutdown",id:"shutdown",level:3},{value:"See also",id:"see-also",level:2},{value:"Documentation",id:"documentation",level:3},{value:"Reference",id:"reference",level:3},{value:"Exporters",id:"exporters",level:3}];function p(e){let n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,s.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"configuration",children:"Configuration"})}),"\n",(0,r.jsx)(n.h2,{id:"observabilityregistryconfig",children:(0,r.jsx)(n.code,{children:"ObservabilityRegistryConfig"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",children:"interface ObservabilityRegistryConfig {\n  default?: { enabled?: boolean }\n  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'>

1 | ObservabilityInstance>\n  configSelector?: ConfigSelector\n  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions\n}\n"})}),"\n",(0,r.jsx)(a.A,{content:[{name:"default",type:"{ enabled?: boolean }",description:"Enable default configuration with MastraStorageExporter and MastraPlatformExporter",required:!1},{name:"configs",type:"Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>",description:"Named observability instance configurations or pre-instantiated instances",required:!1},{name:"configSelector",type:"ConfigSelector",description:"Runtime configuration selector function",required:!1},{name:"sensitiveDataFilter",type:"boolean | SensitiveDataFilterOptions",description:"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.",required:!1}]}),"\n",(0,r.jsx)(n.h2,{id:"observabilityinstanceconfig",children:(0,r.jsx)(n.code,{children:"ObservabilityInstanceConfig"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",children:"interface ObservabilityInstanceConfig {\n  name: string\n  serviceName: string\n  sampling?: SamplingStrategy\n  exporters?: ObservabilityExporter[]\n  spanOutputProcessors?: SpanOutputProcessor[]\n  includeInternalSpans?: boolean\n  excludeSpanTypes?: SpanType[]\n  spanFilter?: (span: AnyExportedSpan) => boolean\n  requestContextKeys?: string[]\n  serializationOptions?: SerializationOptions\n  logging?: { enabled?: boolean; level?: LogLevel }\n}\n"})}),"\n",(0,r.jsx)(a.A,{content:[{name:"name",type:"string",description:"Configuration identifier",required:!0},{name:"serviceName",type:"string",description:"Service name in traces",required:!0},{name:"sampling",type:"SamplingStrategy",description:"Sampling configuration (defaults to ALWAYS)",required:!1},{name:"exporters",type:"ObservabilityExporter[]",description:"Trace data exporters",required:!1},{name:"spanOutputProcessors",type:"SpanOutputProcessor[]",description:"Span output processors",required:!1},{name:"includeInternalSpans",type:"boolean",description:"Include spans internal to Mastra operations",required:!1},{name:"excludeSpanTypes",type:"SpanType[]",description:"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.",required:!1},{name:"spanFilter",type:"(span: AnyExportedSpan) => boolean",description:"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.",required:!1},{name:"requestContextKeys",type:"string[]",description:"RequestContext keys to extract as metadata (supports dot notation)",required:!1},{name:"serializationOptions",type:"SerializationOptions",description:"Options for controlling serialization of span data (input/output/attributes)",required:!1,properties:[{type:"SerializationOptions",parameters:[{name:"maxStringLength",type:"number",description:"Maximum length for string values (default: 131072)",isOptional:!0},{name:"maxDepth",type:"number",description:"Maximum depth for nested objects (default: 8)",isOptional:!0},{name:"maxArrayLength",type:"number",description:"Maximum number of items in arrays (default: 50)",isOptional:!0},{name:"maxObjectKeys",type:"number",description:"Maximum number of keys in objects (default: 50)",isOptional:!0}]}]},{name:"logging",type:"{ enabled?: boolean; level?: LogLevel }",description:"Controls log forwarding to observability storage. See [Logging to observability storage](/docs/observability/logging#logging-to-observability-storage) for details.",required:!1,properties:[{type:"{ enabled?: boolean; level?: LogLevel }",parameters:[{name:"enabled",type:"boolean",description:"Set to false to disable log forwarding to observability storage (default: true)",isOptional:!0},{name:"level",type:"LogLevel",description:"Minimum log level to forward. One of 'debug', 'info', 'warn', 'error', 'fatal' (default: 'debug')",isOptional:!0}]}]}]}),"\n",(0,r.jsx)(n.h2,{id:"samplingstrategy",children:(0,r.jsx)(n.code,{children:"SamplingStrategy"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",children:"type SamplingStrategy =\n  | { type: 'always' }\n  | { type: 'never' }\n  | { type: 'ratio'; probability: number }\n  | { type: 'custom'; sampler: (options?: TracingOptions) => boolean }\n"})}),"\n",(0,r.jsx)(n.h2,{id:"configselector",children:(0,r.jsx)(n.code,{children:"ConfigSelector"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",children:"type ConfigSelector = (\n  options: ConfigSelectorOptions,\n  availableConfigs: ReadonlyMap<string, ObservabilityInstance>,\n) => string | undefined\n"})}),"\n",(0,r.jsx)(n.h2,{id:"configselectoroptions",children:(0,r.jsx)(n.code,{children:"ConfigSelectorOptions"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",children:"interface ConfigSelectorOptions {\n  requestContext?: RequestContext\n}\n"})}),"\n",(0,r.jsx)(n.h2,{id:"registry-methods",children:"Registry methods"}),"\n",(0,r.jsx)(n.p,{children:"The Observability class provides methods for managing observability instances:"}),"\n",(0,r.jsx)(n.h3,{id:"registerinstance",children:(0,r.jsx)(n.code,{children:"registerInstance"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"registerInstance(\n  name: string,\n  instance: ObservabilityInstance,\n  isDefault?: boolean\n): void;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Registers an observability instance in the registry."}),"\n",(0,r.jsx)(n.h3,{id:"getinstance",children:(0,r.jsx)(n.code,{children:"getInstance"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"getInstance(name: string): ObservabilityInstance | undefined;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Retrieves an observability instance by name."}),"\n",(0,r.jsx)(n.h3,{id:"getdefaultinstance",children:(0,r.jsx)(n.code,{children:"getDefaultInstance"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"getDefaultInstance(): ObservabilityInstance | undefined;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Returns the default observability instance."}),"\n",(0,r.jsx)(n.h3,{id:"getselectedinstance",children:(0,r.jsx)(n.code,{children:"getSelectedInstance"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"getSelectedInstance(\n  options: ConfigSelectorOptions\n): ObservabilityInstance | undefined;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Returns the observability instance selected by the config selector or default."}),"\n",(0,r.jsx)(n.h3,{id:"listinstances",children:(0,r.jsx)(n.code,{children:"listInstances"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"listInstances(): ReadonlyMap<string, ObservabilityInstance>;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Returns all registered observability instances."}),"\n",(0,r.jsx)(n.h3,{id:"hasinstance",children:(0,r.jsx)(n.code,{children:"hasInstance"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"hasInstance(name: string): boolean;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Checks if an observability instance exists."}),"\n",(0,r.jsx)(n.h3,{id:"setconfigselector",children:(0,r.jsx)(n.code,{children:"setConfigSelector"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"setConfigSelector(selector: ConfigSelector): void;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Sets the config selector function."}),"\n",(0,r.jsx)(n.h3,{id:"unregisterinstance",children:(0,r.jsx)(n.code,{children:"unregisterInstance"})}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"unregisterInstance(name: string): boolean;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Removes an observability instance from the registry."}),"\n",(0,r.jsx)(n.h3,{id:"clear",children:"clear"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"clear(): void;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Clears all instances without shutdown."}),"\n",(0,r.jsx)(n.h3,{id:"shutdown",children:"shutdown"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-typescript",metastring:"oxfmt:false",children:"async shutdown(): Promise<void>;\n"})}),"\n",(0,r.jsx)(n.p,{children:"Shuts down all observability instances and clears the registry."}),"\n",(0,r.jsx)(n.h2,{id:"see-also",children:"See also"}),"\n",(0,r.jsx)(n.h3,{id:"documentation",children:"Documentation"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/docs/observability/tracing/overview",children:"Tracing Overview"}),": Concepts and usage guide"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/docs/observability/tracing/overview#sampling-strategies",children:"Sampling Strategies"}),": Sampling configuration details"]}

1),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/docs/observability/overview#multi-config-setup",children:"Multi-Config Setup"}),": Using multiple configurations"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"reference",children:"Reference"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/instances",children:"Tracing Classes"}),": Core tracing classes"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/interfaces",children:"Interfaces"}),": Type definitions"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/spans",children:"Spans Reference"}),": Span lifecycle"]}),"\n"]}),"\n",(0,r.jsx)(n.h3,{id:"exporters",children:"Exporters"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/exporters/mastra-storage-exporter",children:"MastraStorageExporter"}),": Persists observability events to Mastra Storage"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/exporters/mastra-platform-exporter",children:"MastraPlatformExporter"}),": Sends observability events to Mastra platform"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/exporters/braintrust",children:"Braintrust"}),": Braintrust integration"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/exporters/langfuse",children:"Langfuse"}),": Langfuse integration"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/exporters/langsmith",children:"LangSmith"}),": LangSmith integration"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.a,{href:"/reference/observability/tracing/span-filtering",children:"Span filtering"}),": Selectively exclude spans"]}),"\n"]})]})}function g(e={}){let{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(p,{...e})}):p(e)}},10107(e,n,t){t.d(n,{A:()=>a});var i=t(74848);t(96540);let r=/(`[^`]+`|\[[^\]]+\]\([^)]+\))/g,s=e=>e.split(r).map((e,n)=>{if(!e)return null;if(e.startsWith("`")&&e.endsWith("`"))return(0,i.jsx)("code",{className:"language-text",children:e.slice(1,-1)},n);let t=e.match(/^\[([^\]]+)\]\(([^)]+)\)$/);return t?(0,i.jsx)("a",{href:t[2],children:t[1]},n):e}),a=({content:e=[]})=>{let n=({properties:e=[]})=>{if(e&&e.length>0)return(0,i.jsx)("div",{className:"flex flex-col","data-testid":"property-nested",children:e.map((e,t)=>(0,i.jsx)("div",{className:"relative m-2 my-4 flex flex-col rounded-lg border border-(--ifm-color-emphasis-300)",children:(0,i.jsxs)("div",{className:"flex flex-col",children:[e.type?(0,i.jsx)("div",{className:"absolute -top-3 right-2 z-20 cursor-pointer rounded-md bg-(--ifm-color-emphasis-200) px-2 py-1 font-(family-name:--ifm-font-family-monospace) text-xs text-(--ifm-color-emphasis-700)",children:e.type}):null,e.parameters&&e.parameters.map((e,t)=>(0,i.jsxs)("div",{className:"flex flex-col gap-1 border-b border-(--ifm-color-emphasis-300) p-3 last:border-none","data-testid":"property-row",children:[(0,i.jsxs)("div",{className:"group relative flex flex-row items-start gap-2",children:[(0,i.jsxs)("h3",{className:"m-0 cursor-pointer font-(family-name:--ifm-font-family-monospace)! text-sm! font-medium!","data-testid":"property-name",children:[e.name,(0,i.jsx)("span",{children:e.isOptional?"?:":":"})]}),(0,i.jsx)("div",{className:"w-full font-(family-name:--ifm-font-family-monospace) text-sm text-(--ifm-color-emphasis-700)","data-testid":"property-type",children:e.type})]}),(0,i.jsx)("div",{className:"text-sm leading-5 text-(--ifm-color-emphasis-700)","data-testid":"property-description",children:s(e.description)}),n({properties:e.properties})]},t))]})},t))})};return(0,i.jsx)("div",{className:"mb-(--ifm-leading) flex flex-col","data-testid":"properties-table",children:e.map((e,t)=>(0,i.jsxs)("div",{id:e.name,className:"flex flex-col gap-1 border-b border-(--ifm-color-emphasis-300) py-3","data-testid":"property-row",children:[(0,i.jsxs)("div",{className:"group flex flex-row items-start gap-2",children:[(0,i.jsxs)("h3",{className:"m-0 cursor-pointer border-b-0! pb-0! font-(family-name:--ifm-font-family-monospace)! text-sm! font-medium!","data-testid":"property-name",children:[e.name,(0,i.jsx)("span",{children:e.isOptional?"?:":":"})]}),(0,i.jsx)("div",{className:"font-(family-name:--ifm-font-family-monospace) text-sm leading-5 text-(--ifm-color-emphasis-700)","data-testid":"property-type",children:e.type}),e.defaultValue&&(0,i.jsxs)("div",{className:"text-sm leading-5 text-(--ifm-color-emphasis-700)","data-testid":"property-default",children:["= ",e.defaultValue]})]}),(0,i.jsx)("div",{className:"text-sm leading-5 text-(--ifm-color-emphasis-700)","data-testid":"property-description",children:s(e.description)}),n({properties:e.properties})]},t))})}},28453(e,n,t){t.d(n,{R:()=>a,x:()=>o});var i=t(96540);let r={},s=i.createContext(r);function a(e){let n=i.useContext(s);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:a(e.components),i.createElement(s.Provider,{value:n},e.children)}}}]);