# 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](https://mastra.ai/docs/mastra-cloud/observability) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.

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

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