1 | /// <reference types="node" />
|
2 | import { Writable } from 'stream';
|
3 | /**
|
4 | * A Bunyan `Serializer` function.
|
5 | *
|
6 | * @param input The input to be serialized.
|
7 | * **See** {@link https://github.com/forcedotcom/node-bunyan#serializers|Bunyan Serializers API}
|
8 | */
|
9 | export declare type Serializer = (input: unknown) => unknown;
|
10 | /**
|
11 | * A collection of named `Serializer`s.
|
12 | *
|
13 | * **See** {@link https://github.com/forcedotcom/node-bunyan#serializers|Bunyan Serializers API}
|
14 | */
|
15 | export interface Serializers {
|
16 | [key: string]: Serializer;
|
17 | }
|
18 | /**
|
19 | * The common set of `Logger` options.
|
20 | */
|
21 | export interface LoggerOptions {
|
22 | /**
|
23 | * The logger name.
|
24 | */
|
25 | name: string;
|
26 | /**
|
27 | * The logger format type. Current options include LogFmt or JSON (default).
|
28 | */
|
29 | format?: LoggerFormat;
|
30 | /**
|
31 | * The logger's serializers.
|
32 | */
|
33 | serializers?: Serializers;
|
34 | /**
|
35 | * Whether or not to log source file, line, and function information.
|
36 | */
|
37 | src?: boolean;
|
38 | /**
|
39 | * The desired log level.
|
40 | */
|
41 | level?: LoggerLevelValue;
|
42 | /**
|
43 | * A stream to write to.
|
44 | */
|
45 | stream?: Writable;
|
46 | /**
|
47 | * An array of streams to write to.
|
48 | */
|
49 | streams?: LoggerStream[];
|
50 | }
|
51 | /**
|
52 | * Standard `Logger` levels.
|
53 | *
|
54 | * **See** {@link https://github.com/forcedotcom/node-bunyan#levels|Bunyan Levels}
|
55 | */
|
56 | export declare enum LoggerLevel {
|
57 | TRACE = 10,
|
58 | DEBUG = 20,
|
59 | INFO = 30,
|
60 | WARN = 40,
|
61 | ERROR = 50,
|
62 | FATAL = 60
|
63 | }
|
64 | /**
|
65 | * `Logger` format types.
|
66 | */
|
67 | export declare enum LoggerFormat {
|
68 | JSON = 0,
|
69 | LOGFMT = 1
|
70 | }
|
71 | /**
|
72 | * A Bunyan stream configuration.
|
73 | *
|
74 | * @see {@link https://github.com/forcedotcom/node-bunyan#streams|Bunyan Streams}
|
75 | */
|
76 | export interface LoggerStream {
|
77 | [key: string]: any;
|
78 | /**
|
79 | * The type of stream -- may be inferred from other properties.
|
80 | */
|
81 | type?: string;
|
82 | /**
|
83 | * The desired log level for the stream.
|
84 | */
|
85 | level?: LoggerLevelValue;
|
86 | /**
|
87 | * The stream to write to. Mutually exclusive with `path`.
|
88 | */
|
89 | stream?: Writable;
|
90 | /**
|
91 | * The name of the stream.
|
92 | */
|
93 | name?: string;
|
94 | /**
|
95 | * A log file path to write to. Mutually exclusive with `stream`.
|
96 | */
|
97 | path?: string;
|
98 | }
|
99 | /**
|
100 | * Any numeric `Logger` level.
|
101 | */
|
102 | export declare type LoggerLevelValue = LoggerLevel | number;
|
103 | /**
|
104 | * A collection of named `FieldValue`s.
|
105 | *
|
106 | * **See** {@link https://github.com/forcedotcom/node-bunyan#log-record-fields|Bunyan Log Record Fields}
|
107 | */
|
108 | export interface Fields {
|
109 | [key: string]: FieldValue;
|
110 | }
|
111 | /**
|
112 | * All possible field value types.
|
113 | */
|
114 | export declare type FieldValue = string | number | boolean;
|
115 | /**
|
116 | * Log line interface
|
117 | */
|
118 | export interface LogLine {
|
119 | name: string;
|
120 | hostname: string;
|
121 | pid: string;
|
122 | log: string;
|
123 | level: number;
|
124 | msg: string;
|
125 | time: string;
|
126 | v: number;
|
127 | }
|
128 | /**
|
129 | * A logging abstraction powered by {@link https://github.com/forcedotcom/node-bunyan|Bunyan} that provides both a default
|
130 | * logger configuration that will log to `sfdx.log`, and a way to create custom loggers based on the same foundation.
|
131 | *
|
132 | * ```
|
133 | * // Gets the root sfdx logger
|
134 | * const logger = await Logger.root();
|
135 | *
|
136 | * // Creates a child logger of the root sfdx logger with custom fields applied
|
137 | * const childLogger = await Logger.child('myRootChild', {tag: 'value'});
|
138 | *
|
139 | * // Creates a custom logger unaffiliated with the root logger
|
140 | * const myCustomLogger = new Logger('myCustomLogger');
|
141 | *
|
142 | * // Creates a child of a custom logger unaffiliated with the root logger with custom fields applied
|
143 | * const myCustomChildLogger = myCustomLogger.child('myCustomChild', {tag: 'value'});
|
144 | * ```
|
145 | * **See** https://github.com/forcedotcom/node-bunyan
|
146 | *
|
147 | * **See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm
|
148 | */
|
149 | export declare class Logger {
|
150 | /**
|
151 | * The name of the root sfdx `Logger`.
|
152 | */
|
153 | static readonly ROOT_NAME = "sf";
|
154 | /**
|
155 | * The default `LoggerLevel` when constructing new `Logger` instances.
|
156 | */
|
157 | static readonly DEFAULT_LEVEL = LoggerLevel.WARN;
|
158 | /**
|
159 | * A list of all lower case `LoggerLevel` names.
|
160 | *
|
161 | * **See** {@link LoggerLevel}
|
162 | */
|
163 | static readonly LEVEL_NAMES: string[];
|
164 | private static readonly lifecycle;
|
165 | private static rootLogger?;
|
166 | /**
|
167 | * The default rotation period for logs. Example '1d' will rotate logs daily (at midnight).
|
168 | * See 'period' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file
|
169 | */
|
170 | readonly logRotationPeriod: string;
|
171 | /**
|
172 | * The number of backup rotated log files to keep.
|
173 | * Example: '3' will have the base sf.log file, and the past 3 (period) log files.
|
174 | * See 'count' docs here: https://github.com/forcedotcom/node-bunyan#stream-type-rotating-file
|
175 | */
|
176 | readonly logRotationCount: number;
|
177 | /**
|
178 | * Whether debug is enabled for this Logger.
|
179 | */
|
180 | debugEnabled: boolean;
|
181 | private bunyan;
|
182 | private readonly format;
|
183 | /**
|
184 | * Constructs a new `Logger`.
|
185 | *
|
186 | * @param optionsOrName A set of `LoggerOptions` or name to use with the default options.
|
187 | *
|
188 | * **Throws** *{@link SfError}{ name: 'RedundantRootLoggerError' }* More than one attempt is made to construct the root
|
189 | * `Logger`.
|
190 | */
|
191 | constructor(optionsOrName: LoggerOptions | string);
|
192 | /**
|
193 | * Gets the root logger with the default level, file stream, and DEBUG enabled.
|
194 | */
|
195 | static root(): Promise<Logger>;
|
196 | /**
|
197 | * Gets the root logger with the default level, file stream, and DEBUG enabled.
|
198 | */
|
199 | static getRoot(): Logger;
|
200 | /**
|
201 | * Destroys the root `Logger`.
|
202 | *
|
203 | * @ignore
|
204 | */
|
205 | static destroyRoot(): void;
|
206 | /**
|
207 | * Create a child of the root logger, inheriting this instance's configuration such as `level`, `streams`, etc.
|
208 | *
|
209 | * @param name The name of the child logger.
|
210 | * @param fields Additional fields included in all log lines.
|
211 | */
|
212 | static child(name: string, fields?: Fields): Promise<Logger>;
|
213 | /**
|
214 | * Create a child of the root logger, inheriting this instance's configuration such as `level`, `streams`, etc.
|
215 | *
|
216 | * @param name The name of the child logger.
|
217 | * @param fields Additional fields included in all log lines.
|
218 | */
|
219 | static childFromRoot(name: string, fields?: Fields): Logger;
|
220 | /**
|
221 | * Gets a numeric `LoggerLevel` value by string name.
|
222 | *
|
223 | * @param {string} levelName The level name to convert to a `LoggerLevel` enum value.
|
224 | *
|
225 | * **Throws** *{'UnrecognizedLoggerLevelNameError' }* The level name was not case-insensitively recognized as a valid `LoggerLevel` value.
SfError}{ name: |
226 | * { LoggerLevel}
|
227 | */
|
228 | static getLevelByName(levelName: string): LoggerLevelValue;
|
229 | /**
|
230 | * Adds a stream.
|
231 | *
|
232 | * @param stream The stream configuration to add.
|
233 | * @param defaultLevel The default level of the stream.
|
234 | */
|
235 | addStream(stream: LoggerStream, defaultLevel?: LoggerLevelValue): void;
|
236 | /**
|
237 | * Adds a file stream to this logger. Resolved or rejected upon completion of the addition.
|
238 | *
|
239 | * @param logFile The path to the log file. If it doesn't exist it will be created.
|
240 | */
|
241 | addLogFileStream(logFile: string): Promise<void>;
|
242 | /**
|
243 | * Adds a file stream to this logger. Resolved or rejected upon completion of the addition.
|
244 | *
|
245 | * @param logFile The path to the log file. If it doesn't exist it will be created.
|
246 | */
|
247 | addLogFileStreamSync(logFile: string): void;
|
248 | /**
|
249 | * Gets the name of this logger.
|
250 | */
|
251 | getName(): string;
|
252 | /**
|
253 | * Gets the current level of this logger.
|
254 | */
|
255 | getLevel(): LoggerLevelValue;
|
256 | /**
|
257 | * Set the logging level of all streams for this logger. If a specific `level` is not provided, this method will
|
258 | * attempt to read it from the environment variable `SFDX_LOG_LEVEL`, and if not found,
|
259 | * {@link Logger.DEFAULT_LOG_LEVEL} will be used instead. For convenience `this` object is returned.
|
260 | *
|
261 | * @param {LoggerLevelValue} [level] The logger level.
|
262 | *
|
263 | * **Throws** *{@link SfError}{ name: 'UnrecognizedLoggerLevelNameError' }* A value of `level` read from `SFDX_LOG_LEVEL`
|
264 | * was invalid.
|
265 | *
|
266 | * ```
|
267 | * // Sets the level from the environment or default value
|
268 | * logger.setLevel()
|
269 | *
|
270 | * // Set the level from the INFO enum
|
271 | * logger.setLevel(LoggerLevel.INFO)
|
272 | *
|
273 | * // Sets the level case-insensitively from a string value
|
274 | * logger.setLevel(Logger.getLevelByName('info'))
|
275 | * ```
|
276 | */
|
277 | setLevel(level?: LoggerLevelValue): Logger;
|
278 | /**
|
279 | * Gets the underlying Bunyan logger.
|
280 | */
|
281 | getBunyanLogger(): any;
|
282 | /**
|
283 | * Compares the requested log level with the current log level. Returns true if
|
284 | * the requested log level is greater than or equal to the current log level.
|
285 | *
|
286 | * @param level The requested log level to compare against the currently set log level.
|
287 | */
|
288 | shouldLog(level: LoggerLevelValue): boolean;
|
289 | /**
|
290 | * Use in-memory logging for this logger instance instead of any parent streams. Useful for testing.
|
291 | * For convenience this object is returned.
|
292 | *
|
293 | * **WARNING: This cannot be undone for this logger instance.**
|
294 | */
|
295 | useMemoryLogging(): Logger;
|
296 | /**
|
297 | * Gets an array of log line objects. Each element is an object that corresponds to a log line.
|
298 | */
|
299 | getBufferedRecords(): LogLine[];
|
300 | /**
|
301 | * Reads a text blob of all the log lines contained in memory or the log file.
|
302 | */
|
303 | readLogContentsAsText(): string;
|
304 | /**
|
305 | * Adds a filter to be applied to all logged messages.
|
306 | *
|
307 | * @param filter A function with signature `(...args: any[]) => any[]` that transforms log message arguments.
|
308 | */
|
309 | addFilter(filter: (...args: unknown[]) => unknown): void;
|
310 | /**
|
311 | * Close the logger, including any streams, and remove all listeners.
|
312 | *
|
313 | * @param fn A function with signature `(stream: LoggerStream) => void` to call for each stream with
|
314 | * the stream as an arg.
|
315 | */
|
316 | close(fn?: (stream: LoggerStream) => void): void;
|
317 | /**
|
318 | * Create a child logger, typically to add a few log record fields. For convenience this object is returned.
|
319 | *
|
320 | * @param name The name of the child logger that is emitted w/ log line as `log:<name>`.
|
321 | * @param fields Additional fields included in all log lines for the child logger.
|
322 | */
|
323 | child(name: string, fields?: Fields): Logger;
|
324 | /**
|
325 | * Add a field to all log lines for this logger. For convenience `this` object is returned.
|
326 | *
|
327 | * @param name The name of the field to add.
|
328 | * @param value The value of the field to be logged.
|
329 | */
|
330 | addField(name: string, value: FieldValue): Logger;
|
331 | /**
|
332 | * Logs at `trace` level with filtering applied. For convenience `this` object is returned.
|
333 | *
|
334 | * @param args Any number of arguments to be logged.
|
335 | */
|
336 | trace(...args: any[]): Logger;
|
337 | /**
|
338 | * Logs at `debug` level with filtering applied. For convenience `this` object is returned.
|
339 | *
|
340 | * @param args Any number of arguments to be logged.
|
341 | */
|
342 | debug(...args: unknown[]): Logger;
|
343 | /**
|
344 | * Logs at `debug` level with filtering applied.
|
345 | *
|
346 | * @param cb A callback that returns on array objects to be logged.
|
347 | */
|
348 | debugCallback(cb: () => unknown[] | string): void;
|
349 | /**
|
350 | * Logs at `info` level with filtering applied. For convenience `this` object is returned.
|
351 | *
|
352 | * @param args Any number of arguments to be logged.
|
353 | */
|
354 | info(...args: unknown[]): Logger;
|
355 | /**
|
356 | * Logs at `warn` level with filtering applied. For convenience `this` object is returned.
|
357 | *
|
358 | * @param args Any number of arguments to be logged.
|
359 | */
|
360 | warn(...args: unknown[]): Logger;
|
361 | /**
|
362 | * Logs at `error` level with filtering applied. For convenience `this` object is returned.
|
363 | *
|
364 | * @param args Any number of arguments to be logged.
|
365 | */
|
366 | error(...args: unknown[]): Logger;
|
367 | /**
|
368 | * Logs at `fatal` level with filtering applied. For convenience `this` object is returned.
|
369 | *
|
370 | * @param args Any number of arguments to be logged.
|
371 | */
|
372 | fatal(...args: unknown[]): Logger;
|
373 | /**
|
374 | * Enables logging to stdout when the DEBUG environment variable is used. It uses the logger
|
375 | * name as the debug name, so you can do DEBUG=<logger-name> to filter the results to your logger.
|
376 | */
|
377 | enableDEBUG(): void;
|
378 | private applyFilters;
|
379 | private uncaughtExceptionHandler;
|
380 | private exitHandler;
|
381 | private createLogFmtFormatterStream;
|
382 | }
|