0
# Logger Management
1

2
Core functionality for creating and configuring logger instances with custom transports, formats, and levels.
3

4
## Capabilities
5

6
### Create Logger
7

8
Creates a new Logger instance with custom configuration options.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Logger instance with custom configuration
13
 * @param options - Configuration options for the logger
14
 * @returns A new Logger instance
15
 */
16
function createLogger(options?: LoggerOptions): Logger;
17

18
interface LoggerOptions {
19
  /** Custom logging levels configuration */
20
  levels?: object;
21
  /** Suppress all logging output */
22
  silent?: boolean;
23
  /** Log message formatting configuration */
24
  format?: Format;
25
  /** Minimum logging level */
26
  level?: string;
27
  /** Controls process exit behavior on error */
28
  exitOnError?: Function | boolean;
29
  /** Default metadata to include with all log messages */
30
  defaultMeta?: any;
31
  /** Transport or array of transports for log output */
32
  transports?: Transport[] | Transport;
33
  /** Automatically handle uncaught exceptions */
34
  handleExceptions?: boolean;
35
  /** Automatically handle unhandled promise rejections */
36
  handleRejections?: boolean;
37
  /** Transports specifically for exception handling */
38
  exceptionHandlers?: any;
39
  /** Transports specifically for rejection handling */
40
  rejectionHandlers?: any;
41
}
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
const winston = require('winston');
48

49
// Basic logger
50
const logger = winston.createLogger({
51
  level: 'info',
52
  format: winston.format.json(),
53
  transports: [
54
    new winston.transports.Console()
55
  ]
56
});
57

58
// Advanced logger with custom configuration
59
const advancedLogger = winston.createLogger({
60
  level: 'debug',
61
  format: winston.format.combine(
62
    winston.format.timestamp(),
63
    winston.format.errors({ stack: true }),
64
    winston.format.json()
65
  ),
66
  defaultMeta: { service: 'api' },
67
  transports: [
68
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
69
    new winston.transports.File({ filename: 'combined.log' }),
70
    new winston.transports.Console({
71
      format: winston.format.simple()
72
    })
73
  ],
74
  handleExceptions: true,
75
  handleRejections: true,
76
  exitOnError: false
77
});
78
```
79

80
### Logger Class
81

82
Core Logger class providing logging functionality and transport management.
83

84
```javascript { .api }
85
/**
86
 * Core Logger class extending Node.js Transform stream
87
 */
88
class Logger extends Transform {
89
  constructor(options?: LoggerOptions);
90
  
91
  /** Current logging level */
92
  level: string;
93
  /** Silent mode flag */
94
  silent: boolean;
95
  /** Log formatting configuration */
96
  format: Format;
97
  /** Logging levels configuration */
98
  levels: object;
99
  /** Array of configured transports */
100
  transports: Transport[];
101
  /** Exception handler instance */
102
  exceptions: ExceptionHandler;
103
  /** Rejection handler instance */
104
  rejections: RejectionHandler;
105
  /** Profiler instances map */
106
  profilers: object;
107
  /** Exit on error behavior */
108
  exitOnError: Function | boolean;
109
  /** Default metadata for all logs */
110
  defaultMeta?: any;
111
}
112
```
113

114
### Core Logging Methods
115

116
Primary methods for logging messages at different levels.
117

118
```javascript { .api }
119
/**
120
 * Core logging method
121
 * @param level - Log level string
122
 * @param message - Log message
123
 * @param meta - Additional metadata
124
 * @returns Logger instance for chaining
125
 */
126
log(level: string, message: string, ...meta: any[]): Logger;
127

128
/**
129
 * Log at error level
130
 * @param message - Error message
131
 * @param meta - Additional metadata
132
 * @returns Logger instance for chaining
133
 */
134
error(message: string, ...meta: any[]): Logger;
135

136
/**
137
 * Log at warn level
138
 * @param message - Warning message
139
 * @param meta - Additional metadata
140
 * @returns Logger instance for chaining
141
 */
142
warn(message: string, ...meta: any[]): Logger;
143

144
/**
145
 * Log at info level
146
 * @param message - Info message
147
 * @param meta - Additional metadata
148
 * @returns Logger instance for chaining
149
 */
150
info(message: string, ...meta: any[]): Logger;
151

152
/**
153
 * Log at http level
154
 * @param message - HTTP-related message
155
 * @param meta - Additional metadata
156
 * @returns Logger instance for chaining
157
 */
158
http(message: string, ...meta: any[]): Logger;
159

160
/**
161
 * Log at verbose level
162
 * @param message - Verbose message
163
 * @param meta - Additional metadata
164
 * @returns Logger instance for chaining
165
 */
166
verbose(message: string, ...meta: any[]): Logger;
167

168
/**
169
 * Log at debug level
170
 * @param message - Debug message
171
 * @param meta - Additional metadata
172
 * @returns Logger instance for chaining
173
 */
174
debug(message: string, ...meta: any[]): Logger;
175

176
/**
177
 * Log at silly level
178
 * @param message - Debug message
179
 * @param meta - Additional metadata
180
 * @returns Logger instance for chaining
181
 */
182
silly(message: string, ...meta: any[]): Logger;
183
```
184

185
### Transport Management
186

187
Methods for adding, removing, and managing log transports.
188

189
```javascript { .api }
190
/**
191
 * Add a transport to this logger
192
 * @param transport - Transport instance to add
193
 * @returns Logger instance for chaining
194
 */
195
add(transport: Transport): Logger;
196

197
/**
198
 * Remove a transport from this logger
199
 * @param transport - Transport instance to remove
200
 * @returns Logger instance for chaining
201
 */
202
remove(transport: Transport): Logger;
203

204
/**
205
 * Remove all transports from this logger
206
 * @returns Logger instance for chaining
207
 */
208
clear(): Logger;
209

210
/**
211
 * Close all transports and clean up resources
212
 * @returns Logger instance for chaining
213
 */
214
close(): Logger;
215
```
216

217
### Configuration and Child Loggers
218

219
Methods for reconfiguring loggers and creating child logger instances.
220

221
```javascript { .api }
222
/**
223
 * Reconfigure this logger with new options
224
 * @param options - New configuration options
225
 */
226
configure(options: LoggerOptions): void;
227

228
/**
229
 * Create a child logger with additional default metadata
230
 * @param defaultMeta - Additional metadata to include in all logs
231
 * @returns Child logger instance
232
 */
233
child(defaultMeta: object): Logger;
234
```
235

236
### Level Checking Methods
237

238
Methods to check if specific log levels are enabled.
239

240
```javascript { .api }
241
/**
242
 * Check if a specific log level is enabled
243
 * @param level - Log level to check
244
 * @returns True if level is enabled
245
 */
246
isLevelEnabled(level: string): boolean;
247

248
/**
249
 * Check if error level is enabled
250
 * @returns True if error level is enabled
251
 */
252
isErrorEnabled(): boolean;
253

254
/**
255
 * Check if warn level is enabled
256
 * @returns True if warn level is enabled
257
 */
258
isWarnEnabled(): boolean;
259

260
/**
261
 * Check if info level is enabled
262
 * @returns True if info level is enabled
263
 */
264
isInfoEnabled(): boolean;
265

266
/**
267
 * Check if verbose level is enabled
268
 * @returns True if verbose level is enabled
269
 */
270
isVerboseEnabled(): boolean;
271

272
/**
273
 * Check if debug level is enabled
274
 * @returns True if debug level is enabled
275
 */
276
isDebugEnabled(): boolean;
277

278
/**
279
 * Check if silly level is enabled
280
 * @returns True if silly level is enabled
281
 */
282
isSillyEnabled(): boolean;
283
```
284

285
### Query and Streaming
286

287
Methods for querying historical logs and creating live streams of log data.
288

289
```javascript { .api }
290
/**
291
 * Query historical log data from transports that support querying
292
 * @param options - Query configuration options
293
 * @param callback - Optional callback function for results
294
 * @returns Query results or promise
295
 */
296
query(options?: QueryOptions, callback?: (err: Error, results: any) => void): any;
297

298
/**
299
 * Create a readable stream of log messages
300
 * @param options - Stream configuration options
301
 * @returns Readable stream of log messages
302
 */
303
stream(options?: StreamOptions): ReadableStream;
304

305
interface QueryOptions {
306
  /** Number of rows to return */
307
  rows?: number;
308
  /** Limit number of results */
309
  limit?: number;
310
  /** Starting index */
311
  start?: number;
312
  /** Start date filter */
313
  from?: Date;
314
  /** End date filter */
315
  until?: Date;
316
  /** Sort order ('asc' or 'desc') */
317
  order?: 'asc' | 'desc';
318
  /** Fields to include in results */
319
  fields?: any;
320
}
321

322
interface StreamOptions {
323
  /** Starting point for stream (-1 for tail) */
324
  start?: number;
325
  /** Additional stream options */
326
  [key: string]: any;
327
}
328
```
329

330
### Exception and Rejection Handling Methods  
331

332
Methods for configuring automatic exception and rejection handling at the logger level.
333

334
```javascript { .api }
335
/**
336
 * Configure logger to handle uncaught exceptions
337
 * @param transports - Transport instances for exception logging
338
 */
339
handleExceptions(...transports: Transport[]): void;
340

341
/**
342
 * Stop handling uncaught exceptions
343
 * @param transports - Transport instances to remove from exception handling
344
 */
345
unhandleExceptions(...transports: Transport[]): void;
346

347
/**
348
 * Configure logger to handle unhandled promise rejections
349
 * @param transports - Transport instances for rejection logging
350
 */
351
handleRejections(...transports: Transport[]): void;
352

353
/**
354
 * Stop handling unhandled promise rejections
355
 * @param transports - Transport instances to remove from rejection handling
356
 */
357
unhandleRejections(...transports: Transport[]): void;
358
```
359

360
**Usage Examples:**
361

362
```javascript
363
const winston = require('winston');
364

365
const logger = winston.createLogger({
366
  level: 'info',
367
  transports: [new winston.transports.Console()]
368
});
369

370
// Basic logging
371
logger.error('Something went wrong');
372
logger.warn('This is a warning');
373
logger.info('Information message');
374

375
// Check if levels are enabled
376
if (logger.isDebugEnabled()) {
377
  logger.debug('Debug information');
378
}
379

380
// Add transport
381
logger.add(new winston.transports.File({ filename: 'app.log' }));
382

383
// Create child logger
384
const childLogger = logger.child({ requestId: '12345' });
385
childLogger.info('This will include requestId in metadata');
386

387
// Reconfigure logger
388
logger.configure({
389
  level: 'debug',
390
  format: winston.format.json()
391
});
392
```