0
# Logging System
1

2
Configurable logging infrastructure with console output, verbose modes, log capture capabilities, and integration with the pino logging library for structured logging.
3

4
## Capabilities
5

6
### Logger Creation
7

8
Create module-specific loggers with consistent formatting and configuration.
9

10
```javascript { .api }
11
/**
12
 * Create a logger instance for a specific module
13
 * @param moduleURL - Module URL (typically import.meta.url)
14
 * @param options - Logger configuration options
15
 * @returns Configured pino logger instance
16
 */
17
function createLogger(moduleURL: string, options?: LoggerOptions): Logger;
18

19
interface LoggerOptions {
20
  /** Custom pino logger factory */
21
  createPinoLog?: Function;
22
}
23

24
interface Logger {
25
  /** Log debug messages (only shown in verbose mode) */
26
  debug(message: string, ...args: any[]): void;
27
  /** Log informational messages */
28
  info(message: string, ...args: any[]): void;
29
  /** Log warning messages */
30
  warn(message: string, ...args: any[]): void;
31
  /** Log error messages */
32
  error(message: string, ...args: any[]): void;
33
  /** Log fatal error messages */
34
  fatal(message: string, ...args: any[]): void;
35
}
36
```
37

38
**Usage Examples:**
39

40
```javascript
41
import { createLogger } from "web-ext/util/logger";
42

43
// Create module-specific logger
44
const log = createLogger(import.meta.url);
45

46
// Log at different levels
47
log.info('Extension build started');
48
log.debug('Processing file:', filePath);
49
log.warn('Deprecated API usage detected');
50
log.error('Build failed:', error.message);
51

52
// Logger with custom options
53
const customLog = createLogger(import.meta.url, {
54
  createPinoLog: customPinoFactory
55
});
56
```
57

58
### Console Stream
59

60
Custom stream implementation for handling log output with verbose mode support and log capture capabilities.
61

62
```javascript { .api }
63
class ConsoleStream {
64
  constructor(options?: ConsoleStreamOptions);
65
  /** Format log message for console output */
66
  format(logData: LogData): string;
67
  /** Enable verbose logging mode */
68
  makeVerbose(): void;
69
  /** Write log data to appropriate output stream */
70
  write(jsonString: string, options?: WriteOptions): void;
71
  /** Start capturing logs in memory */
72
  startCapturing(): void;
73
  /** Stop capturing and clear buffer */
74
  stopCapturing(): void;
75
  /** Output captured logs to console */
76
  flushCapturedLogs(options?: FlushOptions): void;
77
}
78

79
interface ConsoleStreamOptions {
80
  /** Start in verbose mode */
81
  verbose?: boolean;
82
}
83

84
interface LogData {
85
  /** Logger name/module identifier */
86
  name: string;
87
  /** Log message */
88
  msg: string;
89
  /** Log level (10=debug, 20=info, 30=warn, 40=error, 50=fatal) */
90
  level: number;
91
  /** Timestamp */
92
  time: number;
93
  /** Additional log properties */
94
  [key: string]: any;
95
}
96

97
interface WriteOptions {
98
  /** Character encoding */
99
  encoding?: string;
100
}
101

102
interface FlushOptions {
103
  /** Output stream to flush to */
104
  stream?: NodeJS.WritableStream;
105
}
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
import { ConsoleStream } from "web-ext/util/logger";
112

113
// Create custom console stream
114
const stream = new ConsoleStream({ verbose: true });
115

116
// Capture logs for processing
117
stream.startCapturing();
118

119
// ... perform operations that generate logs ...
120

121
// Output captured logs
122
stream.flushCapturedLogs();
123
stream.stopCapturing();
124
```
125

126
### Shared Console Stream
127

128
Pre-configured console stream instance used throughout web-ext.
129

130
```javascript { .api }
131
/** Shared console stream instance for consistent logging */
132
const consoleStream: ConsoleStream;
133
```
134

135
**Usage Example:**
136

137
```javascript
138
import { consoleStream } from "web-ext/util/logger";
139

140
// Enable verbose mode globally
141
consoleStream.makeVerbose();
142

143
// Start capturing for later analysis
144
consoleStream.startCapturing();
145
```
146

147
### Log Formatting
148

149
The logging system provides structured, readable output with consistent formatting.
150

151
#### Standard Format
152

153
```
154
[timestamp] LEVEL (module): message
155
```
156

157
Example output:
158
```
159
[14:23:45] INFO (cmd/build): Building extension from ./my-extension
160
[14:23:45] DEBUG (util/manifest): Reading manifest.json
161
[14:23:46] WARN (cmd/build): File ignored: node_modules/package.json
162
[14:23:46] INFO (cmd/build): Extension built successfully: ./web-ext-artifacts/extension.zip
163
```
164

165
#### Verbose Format
166

167
In verbose mode, additional context and stack traces are included:
168

169
```
170
[14:23:45] DEBUG (util/file-filter): Processing file: src/content.js
171
  → File matches pattern: **/*.js
172
  → File size: 2.1KB
173
  → Including in package
174
```
175

176
### Log Levels
177

178
The logging system supports standard log levels with appropriate console output:
179

180
```javascript { .api }
181
enum LogLevel {
182
  /** Debug information (verbose mode only) */
183
  DEBUG = 10,
184
  /** General information */
185
  INFO = 20,
186
  /** Warning messages */
187
  WARN = 30,
188
  /** Error messages */
189
  ERROR = 40,
190
  /** Fatal errors */
191
  FATAL = 50
192
}
193
```
194

195
**Level Behavior:**
196
- `DEBUG`: Only shown in verbose mode, useful for troubleshooting
197
- `INFO`: Standard operational messages, always shown
198
- `WARN`: Potential issues that don't prevent operation
199
- `ERROR`: Serious problems that may cause failures
200
- `FATAL`: Critical errors that prevent continued operation
201

202
### Log Capture and Replay
203

204
Capture logs in memory for testing, analysis, or delayed output.
205

206
```javascript { .api }
207
/**
208
 * Start capturing log messages in memory
209
 * @returns void
210
 */
211
function startCapturing(): void;
212

213
/**
214
 * Stop capturing and clear the capture buffer
215
 * @returns void
216
 */
217
function stopCapturing(): void;
218

219
/**
220
 * Output all captured logs to console
221
 * @param options - Flush configuration
222
 * @returns void
223
 */
224
function flushCapturedLogs(options?: FlushOptions): void;
225
```
226

227
**Usage Example:**
228

229
```javascript
230
import { consoleStream } from "web-ext/util/logger";
231

232
// Capture logs during operation
233
consoleStream.startCapturing();
234

235
try {
236
  await performOperation();
237
  // Only show logs if operation succeeded
238
  consoleStream.flushCapturedLogs();
239
} catch (error) {
240
  // Don't show captured logs on error
241
  console.error('Operation failed:', error.message);
242
} finally {
243
  consoleStream.stopCapturing();
244
}
245
```
246

247
### Integration with Pino
248

249
web-ext uses the pino logging library for structured logging with performance and flexibility benefits.
250

251
```javascript { .api }
252
interface PinoLogger {
253
  /** Log at debug level */
254
  debug(obj: object, msg?: string): void;
255
  debug(msg: string, ...args: any[]): void;
256
  
257
  /** Log at info level */
258
  info(obj: object, msg?: string): void;
259
  info(msg: string, ...args: any[]): void;
260
  
261
  /** Log at warn level */
262
  warn(obj: object, msg?: string): void;
263
  warn(msg: string, ...args: any[]): void;
264
  
265
  /** Log at error level */
266
  error(obj: object, msg?: string): void;
267
  error(msg: string, ...args: any[]): void;
268
  
269
  /** Log at fatal level */
270
  fatal(obj: object, msg?: string): void;
271
  fatal(msg: string, ...args: any[]): void;
272
}
273
```
274

275
### Module-Specific Logging
276

277
Each web-ext module creates its own logger instance for better organization and debugging.
278

279
**Module Examples:**
280

281
```javascript
282
// In build.js
283
const log = createLogger(import.meta.url);
284
log.info('Starting extension build process');
285

286
// In run.js  
287
const log = createLogger(import.meta.url);
288
log.debug('Configuring Firefox profile');
289

290
// In lint.js
291
const log = createLogger(import.meta.url);
292
log.warn('Deprecated API usage detected in manifest');
293
```
294

295
This creates organized log output like:
296
```
297
[14:23:45] INFO (cmd/build): Starting extension build process
298
[14:23:45] DEBUG (cmd/run): Configuring Firefox profile  
299
[14:23:46] WARN (cmd/lint): Deprecated API usage detected in manifest
300
```
301

302
### Verbose Mode Integration
303

304
The logging system integrates with web-ext's global verbose mode:
305

306
```javascript { .api }
307
/**
308
 * Enable verbose mode for enhanced logging output
309
 * @param logStream - Console stream to make verbose
310
 * @param version - web-ext version for context
311
 * @returns void
312
 */
313
function enableVerboseMode(logStream: ConsoleStream, version: string): void;
314
```
315

316
When verbose mode is enabled:
317
- Debug messages are shown
318
- Additional context is included
319
- Stack traces are displayed for errors
320
- File operation details are logged
321
- Network request/response information is shown
322

323
### Error Logging
324

325
Enhanced error logging with stack traces and context:
326

327
```javascript
328
try {
329
  await riskyOperation();
330
} catch (error) {
331
  // In normal mode: shows error message
332
  // In verbose mode: shows full stack trace and context
333
  log.error('Operation failed:', error);
334
}
335
```
336

337
### Performance Considerations
338

339
The logging system is designed for minimal performance impact:
340

341
- Debug messages are completely skipped when not in verbose mode
342
- Log formatting is lazy (only when needed)
343
- Structured logging reduces string concatenation overhead
344
- Console stream buffering reduces I/O operations
345

346
**Usage Example for Performance:**
347

348
```javascript
349
// Efficient: debug message skipped entirely when not verbose
350
log.debug('Processing file: %s', expensiveComputation());
351

352
// Inefficient: always computes even when not verbose
353
log.debug(`Processing file: ${expensiveComputation()}`);
354
```