0
# Transports
1

2
High-performance log processing system using worker threads for handling log output without blocking the main thread. Transports allow you to send logs to multiple destinations, transform log data, and process logs in separate processes for optimal performance.
3

4
## Capabilities
5

6
### Transport Function
7

8
Create transport streams for processing logs in worker threads.
9

10
```typescript { .api }
11
/**
12
 * Creates a transport stream that processes logs in a separate worker thread
13
 * @param options - Transport configuration options
14
 * @returns ThreadStream for use as logger destination
15
 */
16
function transport(options: TransportSingleOptions | TransportMultiOptions | TransportPipelineOptions): ThreadStream;
17

18
type ThreadStream = any; // Worker thread stream interface
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const transport = pino.transport({
25
  target: 'pino-pretty'
26
});
27

28
const logger = pino(transport);
29
logger.info('This will be pretty printed');
30
```
31

32
## Single Transport
33

34
### Single Transport Configuration
35

36
Configure a single transport target for log processing.
37

38
```typescript { .api }
39
interface TransportSingleOptions {
40
  /** Target module name or file path for transport */
41
  target: string;
42
  
43
  /** Options passed to the transport */
44
  options?: Record<string, any>;
45
  
46
  /** Worker thread options */
47
  worker?: WorkerOptions & { autoEnd?: boolean };
48
}
49

50
interface WorkerOptions {
51
  /** Worker thread environment settings */
52
  env?: Record<string, string>;
53
  /** Worker execution arguments */
54
  execArgv?: string[];
55
  /** Worker resource limits */
56
  resourceLimits?: {
57
    maxOldGenerationSizeMb?: number;
58
    maxYoungGenerationSizeMb?: number;
59
    codeRangeSizeMb?: number;
60
  };
61
}
62
```
63

64
**Usage Examples:**
65

66
```javascript
67
// Pretty printing transport
68
const transport = pino.transport({
69
  target: 'pino-pretty',
70
  options: {
71
    colorize: true,
72
    translateTime: 'SYS:standard'
73
  }
74
});
75

76
// File transport
77
const transport = pino.transport({
78
  target: 'pino/file',
79
  options: {
80
    destination: './logs/app.log',
81
    mkdir: true
82
  }
83
});
84

85
// Custom transport with worker options
86
const transport = pino.transport({
87
  target: './my-custom-transport.js',
88
  options: {
89
    customOption: 'value'
90
  },
91
  worker: {
92
    autoEnd: false,
93
    env: { NODE_ENV: 'production' }
94
  }
95
});
96
```
97

98
## Multiple Transports
99

100
### Multi-Transport Configuration
101

102
Send logs to multiple destinations with different configurations and filtering.
103

104
```typescript { .api }
105
interface TransportMultiOptions {
106
  /** Array of transport targets */
107
  targets: readonly (TransportTargetOptions | TransportPipelineOptions)[];
108
  
109
  /** Custom levels configuration */
110
  levels?: Record<string, number>;
111
  
112
  /** Remove duplicate log entries */
113
  dedupe?: boolean;
114
  
115
  /** Options passed to each transport */
116
  options?: Record<string, any>;
117
  
118
  /** Worker thread options */
119
  worker?: WorkerOptions & { autoEnd?: boolean };
120
}
121

122
interface TransportTargetOptions {
123
  /** Target module name or file path */
124
  target: string;
125
  
126
  /** Minimum level for this transport */
127
  level?: string;
128
  
129
  /** Transport-specific options */
130
  options?: Record<string, any>;
131
}
132
```
133

134
**Usage Examples:**
135

136
```javascript
137
const transport = pino.transport({
138
  targets: [
139
    {
140
      level: 'error',
141
      target: 'pino/file',
142
      options: {
143
        destination: './logs/error.log'
144
      }
145
    },
146
    {
147
      level: 'info',
148
      target: 'pino-pretty',
149
      options: {
150
        colorize: true
151
      }
152
    },
153
    {
154
      level: 'warn',
155
      target: 'pino-elasticsearch',
156
      options: {
157
        node: 'http://localhost:9200',
158
        index: 'app-logs'
159
      }
160
    }
161
  ]
162
});
163

164
const logger = pino(transport);
165

166
logger.info('Info message'); // Goes to pretty and elasticsearch
167
logger.error('Error message'); // Goes to all three transports
168
```
169

170
## Pipeline Transports
171

172
### Pipeline Configuration
173

174
Chain multiple transports together for sequential processing.
175

176
```typescript { .api }
177
interface TransportPipelineOptions {
178
  /** Array of transports to chain together */
179
  pipeline: TransportSingleOptions[];
180
  
181
  /** Minimum level for the pipeline */
182
  level?: string;
183
  
184
  /** Options passed to the pipeline */
185
  options?: Record<string, any>;
186
  
187
  /** Worker thread options */
188
  worker?: WorkerOptions & { autoEnd?: boolean };
189
}
190
```
191

192
**Usage Examples:**
193

194
```javascript
195
const transport = pino.transport({
196
  pipeline: [
197
    {
198
      target: './transform-logs.js', // First: transform log format
199
      options: { addTimezone: true }
200
    },
201
    {
202
      target: './filter-logs.js', // Second: filter sensitive data
203
      options: { removePasswords: true }
204
    },
205
    {
206
      target: 'pino/file', // Third: write to file
207
      options: { destination: './logs/processed.log' }
208
    }
209
  ]
210
});
211
```
212

213
## Built-in Transports
214

215
### File Transport
216

217
Write logs directly to files with built-in rotation support.
218

219
```typescript { .api }
220
// Built-in file transport: 'pino/file'
221
interface FileTransportOptions {
222
  /** File path for log output */
223
  destination: string;
224
  
225
  /** Create directory if it doesn't exist */
226
  mkdir?: boolean;
227
  
228
  /** Append to existing file */
229
  append?: boolean;
230
}
231
```
232

233
**Usage Examples:**
234

235
```javascript
236
const transport = pino.transport({
237
  target: 'pino/file',
238
  options: {
239
    destination: './logs/app.log',
240
    mkdir: true
241
  }
242
});
243

244
// With daily rotation (requires pino-roll)
245
const transport = pino.transport({
246
  target: 'pino-roll',
247
  options: {
248
    file: './logs/app.log',
249
    frequency: 'daily',
250
    size: '10m'
251
  }
252
});
253
```
254

255
## Custom Transports
256

257
### Creating Custom Transports
258

259
Build custom transport modules for specialized log processing.
260

261
```typescript { .api }
262
// Custom transport module structure
263
export interface TransportStream {
264
  /** Write method for processing log data */
265
  write(chunk: string): void;
266
  
267
  /** Optional end method for cleanup */
268
  end?(): void;
269
  
270
  /** Optional flush method */
271
  flush?(): void;
272
}
273
```
274

275
**Custom Transport Example:**
276

277
```javascript
278
// custom-transport.js
279
import { Transform } from 'stream';
280

281
export default function customTransport(options) {
282
  return new Transform({
283
    objectMode: true,
284
    transform(chunk, encoding, callback) {
285
      const logObj = JSON.parse(chunk);
286
      
287
      // Custom processing
288
      if (logObj.level >= 50) { // error level and above
289
        // Send to external monitoring system
290
        sendToMonitoring(logObj);
291
      }
292
      
293
      // Transform and pass through
294
      logObj.processed = true;
295
      logObj.processingTime = Date.now();
296
      
297
      callback(null, JSON.stringify(logObj) + '\n');
298
    }
299
  });
300
}
301

302
// Usage
303
const transport = pino.transport({
304
  target: './custom-transport.js',
305
  options: {
306
    apiKey: 'monitoring-api-key'
307
  }
308
});
309
```
310

311
## Transport Error Handling
312

313
### Error Management
314

315
Handle transport errors without affecting main application performance.
316

317
**Usage Examples:**
318

319
```javascript
320
const transport = pino.transport({
321
  targets: [
322
    {
323
      target: 'pino/file',
324
      options: { destination: './logs/app.log' }
325
    },
326
    {
327
      target: 'unreliable-transport', // May fail
328
      options: { endpoint: 'https://api.example.com/logs' }
329
    }
330
  ]
331
});
332

333
// Transport errors are isolated and don't crash the main process
334
const logger = pino(transport);
335

336
// Main application continues even if transport fails
337
logger.info('Application continues running');
338
```
339

340
### Transport Events
341

342
Monitor transport status and handle transport lifecycle events.
343

344
**Usage Examples:**
345

346
```javascript
347
const transport = pino.transport({
348
  target: 'pino-pretty'
349
});
350

351
// Monitor transport events (if supported by the transport)
352
transport.on('ready', () => {
353
  console.log('Transport ready');
354
});
355

356
transport.on('error', (err) => {
357
  console.error('Transport error:', err);
358
});
359

360
transport.on('close', () => {
361
  console.log('Transport closed');
362
});
363
```
364

365
## Popular Transport Modules
366

367
### Community Transports
368

369
Common transport modules available from the Pino ecosystem:
370

371
```typescript { .api }
372
// Popular transport targets (npm packages)
373
type PopularTransports = 
374
  | "pino-pretty"           // Pretty printing for development
375
  | "pino-elasticsearch"    // Elasticsearch integration
376
  | "pino-mongodb"          // MongoDB storage
377
  | "pino-syslog"          // Syslog protocol
378
  | "pino-socket"          // TCP/UDP socket transport
379
  | "pino-http-send"       // HTTP endpoint transport
380
  | "pino-datadog"         // Datadog integration
381
  | "pino-cloudwatch"      // AWS CloudWatch
382
  | "pino-slack"           // Slack notifications
383
  | "pino/file";           // Built-in file transport
384
```
385

386
**Usage Examples:**
387

388
```javascript
389
// Development setup with pretty printing
390
const devTransport = pino.transport({
391
  target: 'pino-pretty',
392
  options: {
393
    colorize: true,
394
    translateTime: 'SYS:standard',
395
    ignore: 'pid,hostname'
396
  }
397
});
398

399
// Production setup with multiple outputs
400
const prodTransport = pino.transport({
401
  targets: [
402
    {
403
      level: 'info',
404
      target: 'pino/file',
405
      options: { destination: './logs/app.log' }
406
    },
407
    {
408
      level: 'error',
409
      target: 'pino-elasticsearch',
410
      options: {
411
        node: 'http://elasticsearch:9200',
412
        index: 'error-logs'
413
      }
414
    },
415
    {
416
      level: 'fatal',
417
      target: 'pino-slack',
418
      options: {
419
        webhookUrl: process.env.SLACK_WEBHOOK_URL,
420
        channel: '#alerts'
421
      }
422
    }
423
  ]
424
});
425

426
// Environment-specific logger
427
const logger = pino(
428
  process.env.NODE_ENV === 'production' ? prodTransport : devTransport
429
);
430
```