@mastra/core/dist/docs/references/reference-logging-pino-logger.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# PinoLogger

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

## Usage example

```typescript
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`): When false, disables \`pino-pretty\` and writes raw JSON lines (useful for log aggregators). (Default: `true`)

**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.

## Log enrichment with `mixin`

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

```typescript
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:

```typescript
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–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.

```typescript
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

```typescript
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. This enables centralized logging for distributed environments, supporting filtering by `destinationPath`, `type`, and `runId`.

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

```typescript
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`. This allows forwarding logs to an external system like Sentry for advanced monitoring and observability.

```typescript
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 },
})
```