0
# Winston
1
2
Winston is a comprehensive, multi-transport logging library for Node.js applications that provides flexible and extensible logging capabilities. It supports multiple storage destinations (transports) like console output, files, databases, and remote services, with configurable log levels and custom formatting options.
3
4
## Package Information
5
6
- **Package Name**: winston
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install winston`
10
11
## Core Imports
12
13
```javascript
14
const winston = require('winston');
15
```
16
17
ES Modules:
18
19
```javascript
20
import winston from 'winston';
21
```
22
23
Named imports:
24
25
```javascript
26
import { createLogger, format, transports } from 'winston';
27
```
28
29
## Basic Usage
30
31
```javascript
32
const winston = require('winston');
33
34
// Create a logger
35
const logger = winston.createLogger({
36
level: 'info',
37
format: winston.format.json(),
38
defaultMeta: { service: 'user-service' },
39
transports: [
40
new winston.transports.File({ filename: 'error.log', level: 'error' }),
41
new winston.transports.File({ filename: 'combined.log' })
42
]
43
});
44
45
// Add console transport for development
46
if (process.env.NODE_ENV !== 'production') {
47
logger.add(new winston.transports.Console({
48
format: winston.format.simple()
49
}));
50
}
51
52
// Log messages
53
logger.error('Something went wrong');
54
logger.warn('This is a warning');
55
logger.info('Hello distributed log files!');
56
logger.debug('Debugging info');
57
58
// Use default logger directly
59
winston.info('Using default logger');
60
```
61
62
## Architecture
63
64
Winston is built around several key components:
65
66
- **Logger**: Core logging class that manages transports and formats log messages
67
- **Transports**: Storage destinations for log messages (Console, File, HTTP, Stream)
68
- **Formats**: Log message formatting system with composable formatters
69
- **Container**: Management system for multiple named logger instances
70
- **Exception/Rejection Handling**: Automatic handling of uncaught exceptions and unhandled promise rejections
71
- **Profiling**: Built-in performance timing utilities
72
73
## Capabilities
74
75
### Logger Creation and Management
76
77
Core functionality for creating and configuring logger instances with custom transports, formats, and levels.
78
79
```javascript { .api }
80
function createLogger(options?: LoggerOptions): Logger;
81
82
interface LoggerOptions {
83
levels?: object;
84
silent?: boolean;
85
format?: Format;
86
level?: string;
87
exitOnError?: Function | boolean;
88
defaultMeta?: any;
89
transports?: Transport[] | Transport;
90
handleExceptions?: boolean;
91
handleRejections?: boolean;
92
exceptionHandlers?: any;
93
rejectionHandlers?: any;
94
}
95
```
96
97
[Logger Management](./logger-management.md)
98
99
### Built-in Transports
100
101
Transport classes for outputting logs to various destinations including console, files, HTTP endpoints, and arbitrary streams.
102
103
```javascript { .api }
104
class Console extends TransportStream {
105
constructor(options?: ConsoleTransportOptions);
106
}
107
108
class File extends TransportStream {
109
constructor(options: FileTransportOptions);
110
}
111
112
class Http extends TransportStream {
113
constructor(options?: HttpTransportOptions);
114
}
115
116
class Stream extends TransportStream {
117
constructor(options: StreamTransportOptions);
118
}
119
```
120
121
[Transports](./transports.md)
122
123
### Default Logger Interface
124
125
Direct logging methods available on the winston module for quick access without creating logger instances.
126
127
```javascript { .api }
128
function log(level: string, message: string, ...meta: any[]): Logger;
129
function error(message: string, ...meta: any[]): Logger;
130
function warn(message: string, ...meta: any[]): Logger;
131
function info(message: string, ...meta: any[]): Logger;
132
function http(message: string, ...meta: any[]): Logger;
133
function verbose(message: string, ...meta: any[]): Logger;
134
function debug(message: string, ...meta: any[]): Logger;
135
function silly(message: string, ...meta: any[]): Logger;
136
137
// CLI-specific methods (when using CLI levels)
138
function help(message: string, ...meta: any[]): Logger;
139
function data(message: string, ...meta: any[]): Logger;
140
function prompt(message: string, ...meta: any[]): Logger;
141
function input(message: string, ...meta: any[]): Logger;
142
143
// Syslog-specific methods (when using syslog levels)
144
function emerg(message: string, ...meta: any[]): Logger;
145
function alert(message: string, ...meta: any[]): Logger;
146
function crit(message: string, ...meta: any[]): Logger;
147
function warning(message: string, ...meta: any[]): Logger;
148
function notice(message: string, ...meta: any[]): Logger;
149
150
// Transport and configuration management
151
function add(transport: Transport): Logger;
152
function remove(transport: Transport): Logger;
153
function clear(): Logger;
154
function configure(options: LoggerOptions): void;
155
function child(options: object): Logger;
156
157
// Exception and rejection handling
158
function handleExceptions(...transports: Transport[]): void;
159
function unhandleExceptions(...transports: Transport[]): void;
160
function handleRejections(...transports: Transport[]): void;
161
function unhandleRejections(...transports: Transport[]): void;
162
163
// Query and streaming
164
function query(options?: QueryOptions, callback?: (err: Error, results: any) => void): any;
165
function stream(options?: any): ReadableStream;
166
167
// Profiling
168
function startTimer(): Profiler;
169
function profile(id: string | number, meta?: Record<string, any>): Logger;
170
```
171
172
[Default Logger](./default-logger.md)
173
174
### Container and Multi-Logger Management
175
176
Container class for managing multiple named logger instances with shared configurations and lifecycle management.
177
178
```javascript { .api }
179
class Container {
180
constructor(options?: LoggerOptions);
181
add(id: string, options?: LoggerOptions): Logger;
182
get(id: string, options?: LoggerOptions): Logger;
183
has(id: string): boolean;
184
close(id?: string): void;
185
}
186
187
// Default container instance
188
const loggers: Container;
189
```
190
191
[Container Management](./container-management.md)
192
193
### Exception and Rejection Handling
194
195
Automatic handling of uncaught exceptions and unhandled promise rejections with configurable transports and exit behavior.
196
197
```javascript { .api }
198
class ExceptionHandler {
199
constructor(logger: Logger);
200
handle(...transports: Transport[]): void;
201
unhandle(...transports: Transport[]): void;
202
getAllInfo(err: string | Error): object;
203
}
204
205
class RejectionHandler {
206
constructor(logger: Logger);
207
handle(...transports: Transport[]): void;
208
unhandle(...transports: Transport[]): void;
209
getAllInfo(err: string | Error): object;
210
}
211
```
212
213
[Exception and Rejection Handling](./exception-rejection-handling.md)
214
215
### Profiling and Performance
216
217
Built-in profiling utilities for measuring operation performance and logging execution times.
218
219
```javascript { .api }
220
class Profiler {
221
constructor(logger: Logger);
222
done(info?: any): boolean;
223
}
224
225
function startTimer(): Profiler;
226
function profile(id: string | number, meta?: Record<string, any>): Logger;
227
```
228
229
[Profiling](./profiling.md)
230
231
### Format System
232
233
Comprehensive log message formatting system with built-in formatters and composable format transformations.
234
235
```javascript { .api }
236
const format: {
237
json: () => Format;
238
simple: () => Format;
239
combine: (...formats: Format[]) => Format;
240
timestamp: (options?: TimestampOptions) => Format;
241
colorize: (options?: ColorizeOptions) => Format;
242
printf: (templateFunction: (info: any) => string) => Format;
243
errors: (options?: ErrorsOptions) => Format;
244
label: (options?: LabelOptions) => Format;
245
logstash: () => Format;
246
prettyPrint: (options?: PrettyPrintOptions) => Format;
247
splat: () => Format;
248
uncolorize: () => Format;
249
align: () => Format;
250
cli: (options?: CliOptions) => Format;
251
ms: () => Format;
252
};
253
254
interface Format {
255
transform: (info: TransformableInfo, options?: any) => TransformableInfo | boolean;
256
}
257
```
258
259
[Format System](./formats.md)
260
261
## Configuration and Utilities
262
263
```javascript { .api }
264
// Version information
265
const version: string;
266
267
// Configuration utilities
268
const config: {
269
npm: object;
270
cli: object;
271
syslog: object;
272
addColors: (colors: object) => any;
273
};
274
275
// Format system (from logform)
276
const format: {
277
json: () => Format;
278
simple: () => Format;
279
combine: (...formats: Format[]) => Format;
280
timestamp: (options?: object) => Format;
281
colorize: (options?: object) => Format;
282
printf: (templateFunction: (info: any) => string) => Format;
283
// ... and many more formatting options
284
};
285
286
// Transport base class
287
class Transport {
288
constructor(options?: object);
289
}
290
291
// Utility functions
292
function addColors(colors: object): any;
293
```
294
295
## Global Properties
296
297
```javascript { .api }
298
// Properties available on winston module
299
let level: string;
300
let exceptions: ExceptionHandler;
301
let rejections: RejectionHandler;
302
let exitOnError: Function | boolean;
303
```
304
305
## Type Definitions
306
307
```javascript { .api }
308
interface TransformableInfo {
309
level: string;
310
message: string;
311
[key: string]: any;
312
}
313
314
interface QueryOptions {
315
rows?: number;
316
limit?: number;
317
start?: number;
318
from?: Date;
319
until?: Date;
320
order?: 'asc' | 'desc';
321
fields?: any;
322
}
323
324
interface TimestampOptions {
325
format?: string;
326
alias?: string;
327
}
328
329
interface ColorizeOptions {
330
level?: boolean;
331
all?: boolean;
332
message?: boolean;
333
colors?: object;
334
}
335
336
interface ErrorsOptions {
337
stack?: boolean;
338
}
339
340
interface LabelOptions {
341
label?: string;
342
message?: boolean;
343
}
344
345
interface PrettyPrintOptions {
346
depth?: number;
347
colorize?: boolean;
348
}
349
350
interface CliOptions {
351
levels?: object;
352
colors?: object;
353
}
354
355
abstract class TransportStream {
356
constructor(options?: object);
357
silent: boolean;
358
level: string;
359
format?: Format;
360
log(info: TransformableInfo, callback: () => void): void;
361
}
362
```