PinoLogger

使用 new PinoLogger() 创建一个 Logger 实例，并提供在各种严重性级别记录事件的方法。

🌐 A Logger instance is created using new PinoLogger() and provides methods to record events at various severity levels.

部署到 Mastra 云时，日志会显示在 Logs 页面。在自托管或自定义环境中，日志可以根据配置的传输方式定向到文件或外部服务。

🌐 When deploying to Mastra Cloud, logs are displayed on the Logs page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.

使用示例

🌐 Usage example

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { PinoLogger } from "@mastra/loggers";

export const mastra = new Mastra({
  logger: new PinoLogger({
    name: "Mastra",
    level: "info",
  }),
});

参数

🌐 Parameters

name:

string

A label used to group and identify logs from this logger.

level:

"debug" | "info" | "warn" | "error"

Sets the minimum log level. Messages below this level are ignored.

transports:

Record<string, LoggerTransport>

A map of transport instances used to persist logs.

overrideDefaultTransports?:

boolean

If true, disables the default console transport.

formatters?:

pino.LoggerOptions['formatters']

Custom Pino formatters for log serialization.

文件传输（结构化日志）

🌐 File transport (structured logs)

使用 FileTransport 将结构化日志写入文件。记录器接受第一个参数为普通消息，第二个参数为结构化元数据。这些在内部会被转换为 BaseLogMessage 并保存到配置的文件路径中。

🌐 Writes structured logs to a file using the FileTransport. The logger accepts a plain message as the first argument and structured metadata as the second argument. These are internally converted to a BaseLogMessage and persisted to the configured file path.

src/mastra/loggers/file-transport.ts

import { FileTransport } from "@mastra/loggers/file";
import { PinoLogger } from "@mastra/loggers/pino";

export const fileLogger = new PinoLogger({
  name: "Mastra",
  transports: { file: new FileTransport({ path: "test-dir/test.log" }) },
  level: "warn",
});

文件传输使用

🌐 File transport usage

fileLogger.warn("Low disk space", {
  destinationPath: "system",
  type: "WORKFLOW",
});

Upstash 传输（远程日志排放）

🌐 Upstash transport (remote log drain)

使用 UpstashTransport 将结构化日志流式传输到远程 Redis 列表。日志记录器接受字符串消息和结构化元数据对象。这支持分布式环境下的集中式日志记录，并支持按 destinationPath、type 和 runId 进行过滤。

🌐 Streams structured logs to a remote Redis list using the UpstashTransport. The logger accepts a string message and a structured metadata object. This enables centralized logging for distributed environments, supporting filtering by destinationPath, type, and runId.

src/mastra/loggers/upstash-transport.ts

import { UpstashTransport } from "@mastra/loggers/upstash";
import { PinoLogger } from "@mastra/loggers/pino";

export const upstashLogger = new PinoLogger({
  name: "Mastra",
  transports: {
    upstash: new UpstashTransport({
      listName: "production-logs",
      upstashUrl: process.env.UPSTASH_URL!,
      upstashToken: process.env.UPSTASH_TOKEN!,
    }),
  },
  level: "info",
});

Upstash 传输使用情况

🌐 Upstash transport usage

upstashLogger.info("User signed in", {
  destinationPath: "auth",
  type: "AGENT",
  runId: "run_123",
});

定制运输

🌐 Custom transport

你可以使用 createCustomTransport 工具创建自定义传输，以集成到任何日志服务或流中。

🌐 You can create custom transports using the createCustomTransport utility to integrate with any logging service or stream.

Sentry运输示例

🌐 Sentry transport example

使用 createCustomTransport 创建自定义传输，并将其与第三方日志流（如 pino-sentry-transport）集成。这允许将日志转发到像 Sentry 这样的外部系统，以实现高级监控和可观察性。

🌐 Creates a custom transport using createCustomTransport and integrates it with a third-party logging stream such as pino-sentry-transport. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.

src/mastra/loggers/sentry-transport.ts

import { createCustomTransport } from "@mastra/core/loggers";
import { PinoLogger } from "@mastra/loggers/pino";
import pinoSentry from "pino-sentry-transport";

const sentryStream = await pinoSentry({
  sentry: {
    dsn: "YOUR_SENTRY_DSN",
    _experiments: {
      enableLogs: true,
    },
  },
});

const customTransport = createCustomTransport(sentryStream);

export const sentryLogger = new PinoLogger({
  name: "Mastra",
  level: "info",
  transports: { sentry: customTransport },
});