Tracing

Mastra supports the OpenTelemetry Protocol (OTLP) for tracing and monitoring your application. When telemetry is enabled, Mastra automatically traces all core primitives including agent operations, LLM interactions, tool executions, integration calls, workflow runs, and database operations. Your telemetry data can then be exported to any OTEL collector.

Basic Configuration

Here’s a simple example of enabling telemetry:

mastra.config.ts


export const mastra = new Mastra({
  // ... other config
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    sampling: {
      type: "always_on",
    },
    export: {
      type: "otlp",
      endpoint: "http://localhost:4318", // SigNoz local endpoint
    },
  },
});

Configuration Options

The telemetry config accepts these properties:


type OtelConfig = {
  // Name to identify your service in traces (optional)
  serviceName?: string;
 
  // Enable/disable telemetry (defaults to true)
  enabled?: boolean;
 
  // Control how many traces are sampled
  sampling?: {
    type: "ratio" | "always_on" | "always_off" | "parent_based";
    probability?: number; // For ratio sampling
    root?: {
      probability: number; // For parent_based sampling
    };
  };
 
  // Where to send telemetry data
  export?: {
    type: "otlp" | "console";
    endpoint?: string;
    headers?: Record<string, string>;
  };
};

See the OtelConfig reference documentation for more details.

Environment Variables

You can configure the OTLP endpoint and headers through environment variables:

.env


OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key

Then in your config:

mastra.config.ts


export const mastra = new Mastra({
  // ... other config
  telemetry: {
    serviceName: "my-app",
    enabled: true,
    export: {
      type: "otlp",
      // endpoint and headers will be picked up from env vars
    },
  },
});

Example: SigNoz Integration

Here’s what a traced agent interaction looks like in SigNoz :

Agent interaction trace showing spans, LLM calls, and tool executions

Other Supported Providers

For a complete list of supported observability providers and their configuration details, see the Observability Providers reference.

Next.js-specific Tracing steps

If you’re using Next.js, you have three additional configuration steps:

Enable the instrumentation hook in next.config.ts
Configure Mastra telemetry settings
Set up an OpenTelemetry exporter

For implementation details, see the Next.js Tracing guide.