@mastra/loggers

A collection of logging transport implementations for Mastra, extending the LoggerTransport class from @mastra/core.

Installation

1npm install @mastra/loggers

Available Transports

File Transport

A transport that writes logs to a local file system.

1import { FileTransport } from '@mastra/loggers';
2
3const fileLogger = new FileTransport({
4  path: '/path/to/logs/app.log',
5});

Configuration

• path: Absolute path to the log file (must exist)

Features

• Append-mode logging
• Automatic stream cleanup
• JSON log parsing
• Query logs by run ID
• Stream-based implementation

Upstash Transport

A transport that sends logs to Upstash Redis with batching and auto-trimming capabilities.

1import { UpstashTransport } from '@mastra/loggers';
2
3const upstashLogger = new UpstashTransport({
4  upstashUrl: 'https://your-instance.upstash.io',
5  upstashToken: 'your-token',
6  listName: 'application-logs', // optional
7  maxListLength: 10000, // optional
8  batchSize: 100, // optional
9  flushInterval: 10000, // optional
10});

Configuration

Required:

• upstashUrl: Your Upstash Redis instance URL
• upstashToken: Your Upstash authentication token

Optional:

• listName: Redis list name for logs (default: 'application-logs')
• maxListLength: Maximum number of logs to keep (default: 10000)
• batchSize: Number of logs to send in one batch (default: 100)
• flushInterval: Milliseconds between flush attempts (default: 10000)

Features

• Batched log writing
• Automatic log rotation (LTRIM)
• Configurable buffer size
• Automatic retry on failure
• Query logs by run ID
• JSON log formatting
• Timestamp auto-injection
• Graceful shutdown with final flush

Usage with Mastra Core

Both transports implement the LoggerTransport interface from @mastra/core:

1import { Logger } from '@mastra/core/logger';
2import { FileTransport, UpstashTransport } from '@mastra/loggers';
3
4// Create transports
5const fileTransport = new FileTransport({
6  path: '/var/log/app.log',
7});
8
9const upstashTransport = new UpstashTransport({
10  upstashUrl: process.env.UPSTASH_URL!,
11  upstashToken: process.env.UPSTASH_TOKEN!,
12});
13
14// Create logger with multiple transports
15const logger = new Logger({
16  transports: [fileTransport, upstashTransport],
17});
18
19// Log messages
20logger.info('Hello world', { metadata: 'value' });
21
22// Query logs
23const allLogs = await fileTransport.getLogs();
24const runLogs = await upstashTransport.getLogsByRunId({ runId: 'abc-123' });

Log Message Format

Both transports handle log messages in JSON format with the following structure:

1interface BaseLogMessage {
2  time?: number; // Timestamp (auto-injected if not present)
3  level?: string; // Log level
4  msg?: {
5    // Message content
6    runId?: string; // Optional run ID for grouping logs
7    [key: string]: any;
8  };
9  [key: string]: any;
10}

Error Handling

Both transports include robust error handling:

• File Transport:

  • Validates file path existence
  • Handles stream errors
  • Graceful cleanup on destroy

• Upstash Transport:

  • Validates required configuration
  • Retries failed batches
  • Buffers logs during outages
  • Graceful shutdown with final flush

Related Links

• Upstash Redis Documentation
• Node.js Stream Documentation