0
# Transports
1

2
Transport classes for outputting logs to various destinations including console, files, HTTP endpoints, and arbitrary streams.
3

4
## Capabilities
5

6
### Console Transport
7

8
Transport for outputting log messages to the console with configurable output streams and formatting.
9

10
```javascript { .api }
11
/**
12
 * Console transport for outputting to console/terminal
13
 */
14
class Console extends TransportStream {
15
  constructor(options?: ConsoleTransportOptions);
16
}
17

18
interface ConsoleTransportOptions {
19
  /** Transport name for identification */
20
  name?: string;
21
  /** Minimum log level for this transport */
22
  level?: string;
23
  /** Suppress all output from this transport */
24
  silent?: boolean;
25
  /** End of line character(s) */
26
  eol?: string;
27
  /** Array of levels to output to stderr instead of stdout */
28
  stderrLevels?: string[];
29
  /** Array of levels to use console.warn instead of console.log */
30
  consoleWarnLevels?: string[];
31
  /** Force console output even when not in a TTY */
32
  forceConsole?: boolean;
33
  /** Log message formatting */
34
  format?: Format;
35
}
36
```
37

38
**Usage Examples:**
39

40
```javascript
41
const winston = require('winston');
42

43
// Basic console transport
44
const logger = winston.createLogger({
45
  transports: [
46
    new winston.transports.Console()
47
  ]
48
});
49

50
// Console with custom options
51
const logger2 = winston.createLogger({
52
  transports: [
53
    new winston.transports.Console({
54
      level: 'debug',
55
      format: winston.format.combine(
56
        winston.format.colorize(),
57
        winston.format.simple()
58
      ),
59
      stderrLevels: ['error'],
60
      consoleWarnLevels: ['warn']
61
    })
62
  ]
63
});
64
```
65

66
### File Transport
67

68
Transport for outputting log messages to files with support for rotation, compression, and custom streams.
69

70
```javascript { .api }
71
/**
72
 * File transport for outputting to log files
73
 */
74
class File extends TransportStream {
75
  constructor(options: FileTransportOptions);
76
}
77

78
interface FileTransportOptions {
79
  /** Target file path (required) */
80
  filename: string;
81
  /** Directory for log files */
82
  dirname?: string;
83
  /** Transport name for identification */
84
  name?: string;
85
  /** Minimum log level for this transport */
86
  level?: string;
87
  /** Suppress all output from this transport */
88
  silent?: boolean;
89
  /** End of line character(s) */
90
  eol?: string;
91
  /** Maximum file size in bytes before rotation */
92
  maxsize?: number;
93
  /** Maximum number of files to keep */
94
  maxFiles?: number;
95
  /** Function to generate rotation filename */
96
  rotationFormat?: Function;
97
  /** Compress rotated files with gzip */
98
  zippedArchive?: boolean;
99
  /** File stream options */
100
  options?: object;
101
  /** Custom writable stream */
102
  stream?: Stream;
103
  /** Whether the log file is tailable */
104
  tailable?: boolean;
105
  /** Whether to lazy-open the file stream */
106
  lazy?: boolean;
107
  /** Create directory if it doesn't exist */
108
  handleExceptions?: boolean;
109
  /** Handle uncaught exceptions */
110
  handleRejections?: boolean;
111
  /** Log message formatting */
112
  format?: Format;
113
}
114
```
115

116
**Usage Examples:**
117

118
```javascript
119
const winston = require('winston');
120

121
// Basic file transport
122
const logger = winston.createLogger({
123
  transports: [
124
    new winston.transports.File({ filename: 'app.log' })
125
  ]
126
});
127

128
// File with rotation and compression
129
const logger2 = winston.createLogger({
130
  transports: [
131
    new winston.transports.File({
132
      filename: 'error.log',
133
      level: 'error',
134
      maxsize: 5242880, // 5MB
135
      maxFiles: 5,
136
      zippedArchive: true
137
    }),
138
    new winston.transports.File({
139
      filename: 'combined.log',
140
      maxsize: 5242880,
141
      maxFiles: 10
142
    })
143
  ]
144
});
145
```
146

147
### HTTP Transport
148

149
Transport for sending log messages to HTTP endpoints with support for batching and authentication.
150

151
```javascript { .api }
152
/**
153
 * HTTP transport for sending logs to HTTP endpoints
154
 */
155
class Http extends TransportStream {
156
  constructor(options?: HttpTransportOptions);
157
}
158

159
interface HttpTransportOptions {
160
  /** Target hostname */
161
  host?: string;
162
  /** Target port number */
163
  port?: number;
164
  /** HTTP path */
165
  path?: string;
166
  /** HTTP method */
167
  method?: string;
168
  /** Use HTTPS instead of HTTP */
169
  ssl?: boolean;
170
  /** HTTP headers object */
171
  headers?: object;
172
  /** Authentication credentials */
173
  auth?: object;
174
  /** HTTP agent for connection pooling */
175
  agent?: object;
176
  /** Transport name for identification */
177
  name?: string;
178
  /** Minimum log level for this transport */
179
  level?: string;
180
  /** Suppress all output from this transport */
181
  silent?: boolean;
182
  /** Enable request batching */
183
  batch?: boolean;
184
  /** Batch interval in milliseconds */
185
  batchInterval?: number;
186
  /** Maximum batch size */
187
  batchCount?: number;
188
  /** Log message formatting */
189
  format?: Format;
190
}
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
const winston = require('winston');
197

198
// Basic HTTP transport
199
const logger = winston.createLogger({
200
  transports: [
201
    new winston.transports.Http({
202
      host: 'logs.example.com',
203
      port: 80,
204
      path: '/api/logs'
205
    })
206
  ]
207
});
208

209
// HTTPS with authentication and batching
210
const logger2 = winston.createLogger({
211
  transports: [
212
    new winston.transports.Http({
213
      host: 'secure-logs.example.com',
214
      port: 443,
215
      path: '/logs',
216
      ssl: true,
217
      auth: {
218
        username: 'user',
219
        password: 'pass'
220
      },
221
      headers: {
222
        'Authorization': 'Bearer token123'
223
      },
224
      batch: true,
225
      batchInterval: 5000,
226
      batchCount: 10
227
    })
228
  ]
229
});
230
```
231

232
### Stream Transport
233

234
Transport for outputting log messages to arbitrary writable streams.
235

236
```javascript { .api }
237
/**
238
 * Stream transport for outputting to any writable stream
239
 */
240
class Stream extends TransportStream {
241
  constructor(options: StreamTransportOptions);
242
}
243

244
interface StreamTransportOptions {
245
  /** Target writable stream (required) */
246
  stream: Stream;
247
  /** Transport name for identification */
248
  name?: string;
249
  /** Minimum log level for this transport */
250
  level?: string;
251
  /** Suppress all output from this transport */
252
  silent?: boolean;
253
  /** End of line character(s) */
254
  eol?: string;
255
  /** Log message formatting */
256
  format?: Format;
257
}
258
```
259

260
**Usage Examples:**
261

262
```javascript
263
const winston = require('winston');
264
const fs = require('fs');
265

266
// Stream to file
267
const fileStream = fs.createWriteStream('./logs/app.log');
268
const logger = winston.createLogger({
269
  transports: [
270
    new winston.transports.Stream({
271
      stream: fileStream
272
    })
273
  ]
274
});
275

276
// Stream to process stdout
277
const logger2 = winston.createLogger({
278
  transports: [
279
    new winston.transports.Stream({
280
      stream: process.stdout,
281
      format: winston.format.simple()
282
    })
283
  ]
284
});
285
```
286

287
### Transport Base Classes
288

289
Base classes that all transports extend, providing common functionality and streaming capabilities.
290

291
```javascript { .api }
292
/**
293
 * Base transport class
294
 */
295
class Transport {
296
  constructor(options?: TransportOptions);
297
  
298
  /** Transport name */
299
  name: string;
300
  /** Minimum log level */
301
  level: string;
302
  /** Silent mode flag */
303
  silent: boolean;
304
  /** Log message formatting */
305
  format?: Format;
306
}
307

308
/**
309
 * Stream-based transport class (extends Node.js Writable stream)
310
 */
311
abstract class TransportStream extends Transport {
312
  constructor(options?: TransportOptions);
313
  
314
  /** Log method that must be implemented by subclasses */
315
  abstract log(info: TransformableInfo, callback: () => void): void;
316
  
317
  /** Handle logging errors */
318
  handleError(err: Error): void;
319
  
320
  /** Close the transport and clean up resources */
321
  close(): void;
322
  
323
  /** Query historical logs (if supported) */
324
  query?(options: QueryOptions, callback: (err: Error, results: any) => void): void;
325
  
326
  /** Create log stream (if supported) */
327
  stream?(options: StreamOptions): ReadableStream;
328
}
329

330
interface TransportOptions {
331
  /** Transport name for identification */
332
  name?: string;
333
  /** Minimum log level for this transport */
334
  level?: string;
335
  /** Suppress all output from this transport */
336
  silent?: boolean;
337
  /** Log message formatting */
338
  format?: Format;
339
  /** Handle exceptions through this transport */
340
  handleExceptions?: boolean;
341
  /** Handle rejections through this transport */
342
  handleRejections?: boolean;
343
}
344

345
interface TransformableInfo {
346
  /** Log level */
347
  level: string;
348
  /** Log message */
349
  message: string;
350
  /** Timestamp if present */
351
  timestamp?: string;
352
  /** Stack trace if error */
353
  stack?: string;
354
  /** Additional metadata */
355
  [key: string]: any;
356
}
357

358
interface QueryOptions {
359
  rows?: number;
360
  limit?: number;
361
  start?: number;
362
  from?: Date;
363
  until?: Date;
364
  order?: 'asc' | 'desc';
365
  fields?: any;
366
}
367

368
interface StreamOptions {
369
  start?: number;
370
  [key: string]: any;
371
}
372
```
373

374
## Common Transport Usage Patterns
375

376
**Multiple transports with different levels:**
377

378
```javascript
379
const winston = require('winston');
380

381
const logger = winston.createLogger({
382
  level: 'debug',
383
  format: winston.format.combine(
384
    winston.format.timestamp(),
385
    winston.format.json()
386
  ),
387
  transports: [
388
    // Error logs to separate file
389
    new winston.transports.File({
390
      filename: 'error.log',
391
      level: 'error'
392
    }),
393
    // All logs to combined file
394
    new winston.transports.File({
395
      filename: 'combined.log'
396
    }),
397
    // Console output in development
398
    new winston.transports.Console({
399
      format: winston.format.combine(
400
        winston.format.colorize(),
401
        winston.format.simple()
402
      )
403
    })
404
  ]
405
});
406
```
407

408
**Dynamic transport management:**
409

410
```javascript
411
const winston = require('winston');
412

413
const logger = winston.createLogger({
414
  transports: [
415
    new winston.transports.Console()
416
  ]
417
});
418

419
// Add file transport in production
420
if (process.env.NODE_ENV === 'production') {
421
  logger.add(new winston.transports.File({
422
    filename: 'production.log'
423
  }));
424
}
425

426
// Remove console transport in production
427
if (process.env.NODE_ENV === 'production') {
428
  logger.remove(winston.transports.Console);
429
}
430
```