PinoLogger

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

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.

redact?:

pino.LoggerOptions['redact']

Paths or options for redacting sensitive fields from log output (Pino redact).

prettyPrint?:

boolean

= true

When false, disables pino-pretty and writes raw JSON lines (useful for log aggregators).

mixin?:

pino.MixinFn

Pino mixin function merged into every log object (for example request-scoped traceId or other shared metadata).

customLevels?:

Record<string, number>

Custom log levels and numeric values, forwarded to Pino. Standard severity is still logged via debug, info, warn, and error; extra levels follow Pino’s custom-level behavior.

serializers?:

pino.LoggerOptions['serializers']

Custom Pino serializers, merged over the defaults. By default the error key uses Pino’s standard error serializer (alongside the built-in err), so logger.warn("...", { error }) records the type, message, and stack instead of an empty object.

Log enrichment with mixin

Use mixin when you want the same structured fields on every line (for correlation with the rest of your services):

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

function getTraceContext() {
  return { traceId: 'abc-123' }
}

export const mastra = new Mastra({
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
    mixin() {
      return getTraceContext()
    },
  }),
})

Custom levels

customLevels is passed through to Pino. PinoLogger only exposes debug, info, warn, and error; for any extra level name (for example audit), subclass and forward to the underlying Pino instance:

src/mastra/logger.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

type AuditLevel = 'audit'

class MastraPinoWithAudit extends PinoLogger<AuditLevel> {
  audit(message: string, meta: Record<string, unknown> = {}) {
    this.logger.audit(meta, message)
  }
}

const logger = new MastraPinoWithAudit({
  name: 'Mastra',
  level: 'info',
  customLevels: { audit: 35 },
})

export const mastra = new Mastra({ logger })

Numeric values follow Pino’s ordering (built-in levels use 10 to 60). A level of 35 sits between info (30) and warn (40), so with level: 'info' both info and audit lines are emitted.

File transport (structured logs)

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'

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 transport (remote log drain)

Streams structured logs to a remote Redis list using the UpstashTransport. The logger accepts a string message and a structured metadata object. It supports 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'

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 transport usage

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

Custom transport

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

Sentry transport example

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

src/mastra/loggers/sentry-transport.ts

import { createCustomTransport } from '@mastra/core/logger'
import { PinoLogger } from '@mastra/loggers'
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 },
})