Observability

Monitor and debug your Mastra application.

Topics

Overview - Introduction to observability
Logging - Log management
Tracing - Distributed tracing
- Bridges - OpenTelemetry bridge
- Exporters - Trace exporters
Metrics - Metrics collection

Observability Overview

Mastra provides comprehensive observability features for monitoring and debugging AI applications.

Components

Logging - Structured logs with context
Tracing - End-to-end request tracing
Metrics - Quantitative measurements

Quick Setup

import { Mastra } from '@mastra/core';

export const mastra = new Mastra({
  observability: {
    logging: {
      level: 'info',
      format: 'json',
    },
    tracing: {
      enabled: true,
      serviceName: 'my-mastra-app',
    },
    metrics: {
      enabled: true,
    },
  },
});

Why Observability?

Debug issues quickly
Understand agent behavior
Optimize performance
Ensure reliability

Logging

Structured logging for Mastra applications.

Logger Configuration

import { Mastra } from '@mastra/core';
import { PinoLogger } from '@mastra/logger';

export const mastra = new Mastra({
  logger: new PinoLogger({
    level: 'info',
    transport: {
      target: 'pino-pretty',
    },
  }),
});

Log Levels

debug - Detailed debugging information
info - Notable events
warn - Warning conditions
error - Error conditions

Structured Logging

const agent = mastra.getAgent('myAgent');

logger.info('Agent invoked', {
  agentId: agent.id,
  userId: context.userId,
  inputLength: input.length,
});

Log Output

{
  "level": "info",
  "time": 1712000000000,
  "msg": "Agent invoked",
  "agentId": "agent-123",
  "userId": "user-456",
  "inputLength": 150
}

Best Practices

Use structured logging (JSON)
Include relevant context
Set appropriate log levels
Rotate logs in production

Tracing

Distributed tracing for Mastra applications.

Overview

Tracing tracks requests as they flow through your application, enabling end-to-end visibility.

Configuration

import { Mastra } from '@mastra/core';

export const mastra = new Mastra({
  tracing: {
    enabled: true,
    serviceName: 'my-mastra-app',
    sampleRate: 1.0, // 100% sampling
  },
});

What Gets Traced

Agent invocations
Tool executions
Memory operations
Workflow steps
LLM calls

Trace Structure

Trace
├── Span: Agent Invocation
│   ├── Span: Memory Retrieval
│   ├── Span: Tool: search
│   ├── Span: LLM Call
│   └── Span: Response Generation

Using Traces

// Traces are automatically created
const response = await agent.generate('Hello');

// View traces in your observability dashboard

Tracing Bridges

Connect Mastra tracing to your observability backend.

OpenTelemetry Bridge

import { OtelBridge } from '@mastra/observability';

const bridge = new OtelBridge({
  serviceName: 'my-mastra-app',
  exporter: new OTLPExporter({
    endpoint: 'http://collector:4318',
  }),
});

await bridge.start();

Configuration

const bridge = new OtelBridge({
  serviceName: 'my-mastra-app',
  serviceVersion: '1.0.0',
  environment: 'production',
  exporter: otlpExporter,
  sampler: new AlwaysOnSampler(),
});

Supported Formats

OTLP - OpenTelemetry Protocol
Jaeger - Jaeger thrift
Zipkin - Zipkin JSON

OpenTelemetry Bridge

Connect Mastra to OpenTelemetry-compatible backends.

Setup

import { OtelBridge } from '@mastra/observability';
import { OTLPExporter } from '@opentelemetry/exporter-trace-otlp-http';

const bridge = new OtelBridge({
  serviceName: 'my-mastra-app',
  exporter: new OTLPExporter({
    url: 'http://otel-collector:4318/v1/traces',
  }),
});

await bridge.start();

Compatible Backends

Jaeger
Tempo
Honeycomb
Datadog
New Relic
And any OTLP-compatible system

Context Propagation

The bridge automatically propagates W3C Trace Context headers:

// Outgoing request includes trace context
fetch('https://api.example.com', {
  headers: {
    'traceparent': '00-...-...-01',
  },
});

Custom Span Attributes

logger.info('Custom span event', {
  attributes: {
    'custom.attribute': 'value',
    'user.id': userId,
  },
});

Trace Exporters

Export traces to various observability platforms.

Available Exporters

Default - Console exporter for development
OpenTelemetry - OTLP protocol
Jaeger
Zipkin
Datadog
Honeycomb

Basic Configuration

import { Mastra } from '@mastra/core';

export const mastra = new Mastra({
  tracing: {
    enabled: true,
    exporter: {
      type: 'otlp',
      endpoint: 'http://collector:4318',
    },
  },
});

Multiple Exporters

const exporter = {
  type: 'multi',
  exporters: [
    { type: 'otlp', endpoint: 'http://collector:4318' },
    { type: 'console' }, // For debugging
  ],
};

Default Exporter

Console exporter for development and debugging.

Configuration

export const mastra = new Mastra({
  tracing: {
    enabled: true,
    exporter: {
      type: 'default',
      prettyPrint: true,
    },
  },
});

Output

{
  "traceId": "abc123...",
  "spanId": "def456...",
  "parentSpanId": "ghi789...",
  "name": "agent.generate",
  "duration": 1234,
  "attributes": {
    "agent.name": "myAgent",
    "input.length": 150
  }
}

When to Use

Development
Debugging
Testing
Small deployments

Metrics

Metrics collection for monitoring application performance.

Overview

Metrics provide quantitative measurements of your application.

Metric Types

Counters

// Count occurrences
metrics.counter('requests_total', 1, {
  method: 'POST',
  path: '/api/agent',
});

Gauges

// Record current value
metrics.gauge('queue_depth', currentDepth);

Histograms

// Record distribution
metrics.histogram('request_duration_ms', duration, {
  method: 'POST',
  path: '/api/agent',
});

Default Metrics

agent.invocations_total
agent.errors_total
agent.latency_ms
tool.calls_total
tool.latency_ms
workflow.executions_total

Configuration

export const mastra = new Mastra({
  metrics: {
    enabled: true,
    port: 9090, // Metrics endpoint port
  },
});

Prometheus Format

curl http://localhost:9090/metrics

# HELP agent_invocations_total Total agent invocations
# TYPE agent_invocations_total counter
agent_invocations_total{method="generate"} 1234