---
title: "Reference: PinoLogger | Observability"
description: Documentation for PinoLogger, which provides methods to record events at various severity levels.
packages:
  - "@mastra/core"
  - "@mastra/loggers"
---

# PinoLogger

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

When deploying to Mastra Cloud, logs are displayed on the [Logs](/docs/v1/mastra-cloud/observability#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.

## Usage example

```typescript title="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

<PropertiesTable
  content={[
    {
      name: "name",
      type: "string",
      description: "A label used to group and identify logs from this logger.",
    },
    {
      name: "level",
      type: `"debug" | "info" | "warn" | "error"`,
      description:
        "Sets the minimum log level. Messages below this level are ignored.",
    },
    {
      name: "transports",
      type: "Record<string, LoggerTransport>",
      description: "A map of transport instances used to persist logs.",
    },
    {
      name: "overrideDefaultTransports",
      type: "boolean",
      isOptional: true,
      description: "If true, disables the default console transport.",
    },
    {
      name: "formatters",
      type: "pino.LoggerOptions['formatters']",
      isOptional: true,
      description: "Custom Pino formatters for log serialization.",
    },
  ]}
/>

## 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 title="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

```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 title="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 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 title="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 },
});
```
