KakaFlow KB

Mastra Logging System Configuration

6 phút đọc

Mastra Logging System Configuration

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Guide for developers configuring Mastra’s logging system, covering PinoLogger setup, observability integration, and programmatic logging from workflows and tools.

Insight

Mastra’s logging system captures function execution, input data, and output responses in a structured format. When deploying to the Mastra platform, logs appear in the dashboard. In self-hosted environments, logs can be directed to files or external services via configured transports. The PinoLogger class is included by default when initializing a new Mastra project using the CLI. The logger wraps configured loggers to write to both the original logger (console, file, or custom transport) and observability storage simultaneously, requiring no code changes. Log levels supported include debug, info, warn, error, and trackException. Observability log forwarding can be controlled independently via the logging.enabled (boolean, default true) and logging.level (LogLevel, default ‘debug’) options in the Observability configuration. Logs written to observability storage are queryable through the Mastra client SDK using client.listLogsVNext() with support for filtering by level, pagination, and ordering by timestamp.

Hành động

To configure PinoLogger, import Mastra from @mastra/core/mastra and PinoLogger from @mastra/loggers, then pass a new PinoLogger instance with name and level options to the Mastra constructor. To enable observability log forwarding, import Observability and DefaultExporter from @mastra/observability, configure the logging object within your observability config with enabled and level properties. To query logs, import MastraClient from @mastra/client-js and call client.listLogsVNext() with filters, pagination, and orderBy parameters. To log from workflow steps, access the logger via mastra.getLogger() inside the execute function. To log from tools, access via context?.mastra.getLogger(). Logger methods accept an optional second argument for additional structured data objects.

Kết quả

Logs are captured in structured format and forwarded to both the configured logger destination (console, file, or custom transport) and observability storage simultaneously. The console logger outputs all levels at or above the configured level, while observability storage receives only levels at or above the observability logging level, keeping storage clean during development. Queryable logs survive restarts when using persistent storage backends like DuckDB or ClickHouse.

Điều kiện áp dụng

PinoLogger is included by default in new Mastra projects initialized with the CLI. Observability logging requires the @mastra/observability package.

Nội dung gốc (Original)

Logging

Mastra’s logging system captures function execution, input data, and output responses in a structured format.

When deploying to the Mastra platform, logs are shown in the dashboard. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.

Configuring logs with PinoLogger

When initializing a new Mastra project using the CLI, PinoLogger is included by default.

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
 
export const mastra = new Mastra({
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})

Info: Visit PinoLogger for all available configuration options.

Logging to observability storage

When observability is configured, all logger calls are automatically forwarded to your observability storage. This means every debug, info, warn, error, and trackException call from your application and from Mastra’s internal components appears alongside your traces.

No code changes are required. Mastra wraps the configured logger so that it writes to both the original logger (console, file, or custom transport) and the observability system simultaneously.

Configuring observability log level

You can control which log levels reach observability storage independently from your console logger. Add a logging option to your observability instance configuration:

import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
import { Observability, DefaultExporter } from '@mastra/observability'
 
export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'Mastra', level: 'debug' }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new DefaultExporter()],
        logging: {
          enabled: true, // set to false to disable log forwarding
          level: 'info', // minimum level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'
        },
      },
    },
  }),
})

In this example, the console logger outputs all levels starting from debug, but only info and above are written to observability storage. This keeps your storage clean while still having verbose console output during development.

OptionTypeDefaultDescription
enabledbooleantrueSet to false to disable all log forwarding to observability storage.
levelLogLevel'debug'Minimum severity level. Logs below this level are discarded.

Querying logs

Logs written to observability storage are queryable through the Mastra client SDK:

import { MastraClient } from '@mastra/client-js'
 
const client = new MastraClient()
 
const logs = await client.listLogsVNext({
  filters: { level: 'error' },
  pagination: { page: 1, perPage: 50 },
  orderBy: { field: 'timestamp', direction: 'desc' },
})

When using a persistent storage backend like DuckDB or ClickHouse, logs survive restarts and are available for historical analysis.

Customizing logs

Mastra provides access to a logger instance via the mastra.getLogger() method, available inside both workflow steps and tools. The logger supports standard severity levels: debug, info, warn, and error.

Logging from workflow steps

Within a workflow step, access the logger via the mastra parameter inside the execute function. This allows you to log messages relevant to the step’s execution.

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
 
const step1 = createStep({
  execute: async ({ mastra }) => {
    const logger = mastra.getLogger();
    logger.info("workflow info log");
 
    return {
      output: ""
    };
  }
});
 
export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();

Logging from tools

Similarly, tools have access to the logger instance via the mastra parameter. Use this to log tool-specific activity during execution.

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'
 
export const testTool = createTool({
  execute: async (inputData, context) => {
    const logger = context?.mastra.getLogger()
    logger?.info('tool info log')
 
    return {
      output: '',
    }
  },
})

Logging with additional data

Logger methods accept an optional second argument for additional data. Pass a structured object to make logs filterable in observability storage.

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
 
const step1 = createStep({
  execute: async ({ mastra }) => {
    const testAgent = mastra.getAgent("testAgent");
    const logger = mastra.getLogger();
 
    logger.info("workflow info log", { agent: testAgent });
 
    return {
      output: ""
    };
  }
});
 
export const testWorkflow = createWorkflow({...})
  .then(step1)
  .commit();

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược