1 | import { Logger as PinoLogger } from 'pino';
|
2 | /**
|
3 | * The common set of `Logger` options.
|
4 | */
|
5 | export type LoggerOptions = {
|
6 | /**
|
7 | * The logger name.
|
8 | */
|
9 | name: string;
|
10 | /**
|
11 | * The desired log level.
|
12 | */
|
13 | level?: LoggerLevelValue;
|
14 | /**
|
15 | * Create a logger with the fields set
|
16 | */
|
17 | fields?: Fields;
|
18 | /** log to memory instead of to a file. Intended for Unit Testing */
|
19 | useMemoryLogger?: boolean;
|
20 | };
|
21 | /**
|
22 | * Standard `Logger` levels.
|
23 | *
|
24 | * **See** {@link https://getpino.io/#/docs/api?id=logger-level |Logger Levels}
|
25 | */
|
26 | export declare enum LoggerLevel {
|
27 | TRACE = 10,
|
28 | DEBUG = 20,
|
29 | INFO = 30,
|
30 | WARN = 40,
|
31 | ERROR = 50,
|
32 | FATAL = 60
|
33 | }
|
34 | /**
|
35 | * Any numeric `Logger` level.
|
36 | */
|
37 | export type LoggerLevelValue = LoggerLevel | number;
|
38 | /**
|
39 | * An object
|
40 | */
|
41 | export type Fields = Record<string, unknown>;
|
42 | /**
|
43 | * All possible field value types.
|
44 | */
|
45 | export type FieldValue = string | number | boolean | Fields;
|
46 | /**
|
47 | * Log line interface
|
48 | */
|
49 | export type LogLine = {
|
50 | name: string;
|
51 | hostname: string;
|
52 | pid: string;
|
53 | log: string;
|
54 | level: number;
|
55 | msg: string;
|
56 | time: string;
|
57 | v: number;
|
58 | };
|
59 | /**
|
60 | * A logging abstraction powered by {@link https://github.com/pinojs/pino | Pino} that provides both a default
|
61 | * logger configuration that will log to the default path, and a way to create custom loggers based on the same foundation.
|
62 | *
|
63 | * ```
|
64 | * // Gets the root sfdx logger
|
65 | * const logger = await Logger.root();
|
66 | *
|
67 | * // Creates a child logger of the root sfdx logger with custom fields applied
|
68 | * const childLogger = await Logger.child('myRootChild', {tag: 'value'});
|
69 | *
|
70 | * // Creates a custom logger unaffiliated with the root logger
|
71 | * const myCustomLogger = new Logger('myCustomLogger');
|
72 | *
|
73 | * // Creates a child of a custom logger unaffiliated with the root logger with custom fields applied
|
74 | * const myCustomChildLogger = myCustomLogger.child('myCustomChild', {tag: 'value'});
|
75 | *
|
76 | * // get a raw pino logger from the root instance of Logger
|
77 | * // you can use these to avoid constructing another Logger wrapper class and to get better type support
|
78 | * const logger = Logger.getRawRootLogger().child({name: 'foo', otherProp: 'bar'});
|
79 | * logger.info({some: 'stuff'}, 'a message');
|
80 | *
|
81 | *
|
82 | * // get a raw pino logger from the current instance
|
83 | * const childLogger = await Logger.child('myRootChild', {tag: 'value'});
|
84 | * const logger = childLogger.getRawLogger();
|
85 | * ```
|
86 | *
|
87 | * **See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_log_messages.htm
|
88 | */
|
89 | export declare class Logger {
|
90 | /**
|
91 | * The name of the root sfdx `Logger`.
|
92 | */
|
93 | static readonly ROOT_NAME = "sf";
|
94 | /**
|
95 | * The default `LoggerLevel` when constructing new `Logger` instances.
|
96 | */
|
97 | static readonly DEFAULT_LEVEL = LoggerLevel.WARN;
|
98 | /**
|
99 | * A list of all lower case `LoggerLevel` names.
|
100 | *
|
101 | * **See** {@link LoggerLevel}
|
102 | */
|
103 | static readonly LEVEL_NAMES: string[];
|
104 | private static rootLogger?;
|
105 | private pinoLogger;
|
106 | private memoryLogger?;
|
107 | /**
|
108 | * Constructs a new `Logger`.
|
109 | *
|
110 | * @param optionsOrName A set of `LoggerOptions` or name to use with the default options.
|
111 | *
|
112 | * **Throws** *{@link SfError}{ name: 'RedundantRootLoggerError' }* More than one attempt is made to construct the root
|
113 | * `Logger`.
|
114 | */
|
115 | constructor(optionsOrName: LoggerOptions | string);
|
116 | /**
|
117 | *
|
118 | * Gets the root logger. It's a singleton
|
119 | * See also getRawLogger if you don't need the root logger
|
120 | */
|
121 | static root(): Promise<Logger>;
|
122 | /**
|
123 | * Gets the root logger. It's a singleton
|
124 | */
|
125 | static getRoot(): Logger;
|
126 | /**
|
127 | * Destroys the root `Logger`.
|
128 | *
|
129 | * @ignore
|
130 | */
|
131 | static destroyRoot(): void;
|
132 | /**
|
133 | * Create a child of the root logger, inheriting this instance's configuration such as `level`, transports, etc.
|
134 | *
|
135 | * @param name The name of the child logger.
|
136 | * @param fields Additional fields included in all log lines.
|
137 | */
|
138 | static child(name: string, fields?: Fields): Promise<Logger>;
|
139 | /**
|
140 | * Create a child of the root logger, inheriting this instance's configuration such as `level`, transports, etc.
|
141 | *
|
142 | * @param name The name of the child logger.
|
143 | * @param fields Additional fields included in all log lines.
|
144 | */
|
145 | static childFromRoot(name: string, fields?: Fields): Logger;
|
146 | /**
|
147 | * Gets a numeric `LoggerLevel` value by string name.
|
148 | *
|
149 | * @param {string} levelName The level name to convert to a `LoggerLevel` enum value.
|
150 | *
|
151 | * **Throws** *{'UnrecognizedLoggerLevelNameError' }* The level name was not case-insensitively recognized as a valid `LoggerLevel` value.
SfError}{ name: |
152 | * { LoggerLevel}
|
153 | */
|
154 | static getLevelByName(levelName: string): LoggerLevelValue;
|
155 | /** get the bare (pino) logger instead of using the class hierarchy */
|
156 | static getRawRootLogger(): PinoLogger;
|
157 | /** get the bare (pino) logger instead of using the class hierarchy */
|
158 | getRawLogger(): PinoLogger;
|
159 | /**
|
160 | * Gets the name of this logger.
|
161 | */
|
162 | getName(): string;
|
163 | /**
|
164 | * Gets the current level of this logger.
|
165 | */
|
166 | getLevel(): LoggerLevelValue;
|
167 | /**
|
168 | * Set the logging level of all streams for this logger. If a specific `level` is not provided, this method will
|
169 | * attempt to read it from the environment variable `SFDX_LOG_LEVEL`, and if not found,
|
170 | * {@link Logger.DEFAULT_LOG_LEVEL} will be used instead. For convenience `this` object is returned.
|
171 | *
|
172 | * @param {LoggerLevelValue} [level] The logger level.
|
173 | *
|
174 | * **Throws** *{@link SfError}{ name: 'UnrecognizedLoggerLevelNameError' }* A value of `level` read from `SFDX_LOG_LEVEL`
|
175 | * was invalid.
|
176 | *
|
177 | * ```
|
178 | * // Sets the level from the environment or default value
|
179 | * logger.setLevel()
|
180 | *
|
181 | * // Set the level from the INFO enum
|
182 | * logger.setLevel(LoggerLevel.INFO)
|
183 | *
|
184 | * // Sets the level case-insensitively from a string value
|
185 | * logger.setLevel(Logger.getLevelByName('info'))
|
186 | * ```
|
187 | */
|
188 | setLevel(level?: LoggerLevelValue): Logger;
|
189 | /**
|
190 | * Compares the requested log level with the current log level. Returns true if
|
191 | * the requested log level is greater than or equal to the current log level.
|
192 | *
|
193 | * @param level The requested log level to compare against the currently set log level.
|
194 | */
|
195 | shouldLog(level: LoggerLevelValue): boolean;
|
196 | /**
|
197 | * Gets an array of log line objects. Each element is an object that corresponds to a log line.
|
198 | */
|
199 | getBufferedRecords(): LogLine[];
|
200 | /**
|
201 | * Reads a text blob of all the log lines contained in memory or the log file.
|
202 | */
|
203 | readLogContentsAsText(): string;
|
204 | /**
|
205 | * Create a child logger, typically to add a few log record fields. For convenience this object is returned.
|
206 | *
|
207 | * @param name The name of the child logger that is emitted w/ log line. Will be prefixed with the parent logger name and `:`
|
208 | * @param fields Additional fields included in all log lines for the child logger.
|
209 | */
|
210 | child(name: string, fields?: Fields): Logger;
|
211 | /**
|
212 | * Add a field to all log lines for this logger. For convenience `this` object is returned.
|
213 | *
|
214 | * @param name The name of the field to add.
|
215 | * @param value The value of the field to be logged.
|
216 | */
|
217 | addField(name: string, value: FieldValue): Logger;
|
218 | /**
|
219 | * Logs at `trace` level with filtering applied. For convenience `this` object is returned.
|
220 | *
|
221 | * @param args Any number of arguments to be logged.
|
222 | */
|
223 | trace(...args: any[]): Logger;
|
224 | /**
|
225 | * Logs at `debug` level with filtering applied. For convenience `this` object is returned.
|
226 | *
|
227 | * @param args Any number of arguments to be logged.
|
228 | */
|
229 | debug(...args: unknown[]): Logger;
|
230 | /**
|
231 | * Logs at `debug` level with filtering applied.
|
232 | *
|
233 | * @param cb A callback that returns on array objects to be logged.
|
234 | */
|
235 | debugCallback(cb: () => unknown[] | string): void;
|
236 | /**
|
237 | * Logs at `info` level with filtering applied. For convenience `this` object is returned.
|
238 | *
|
239 | * @param args Any number of arguments to be logged.
|
240 | */
|
241 | info(...args: unknown[]): Logger;
|
242 | /**
|
243 | * Logs at `warn` level with filtering applied. For convenience `this` object is returned.
|
244 | *
|
245 | * @param args Any number of arguments to be logged.
|
246 | */
|
247 | warn(...args: unknown[]): Logger;
|
248 | /**
|
249 | * Logs at `error` level with filtering applied. For convenience `this` object is returned.
|
250 | *
|
251 | * @param args Any number of arguments to be logged.
|
252 | */
|
253 | error(...args: unknown[]): Logger;
|
254 | /**
|
255 | * Logs at `fatal` level with filtering applied. For convenience `this` object is returned.
|
256 | *
|
257 | * @param args Any number of arguments to be logged.
|
258 | */
|
259 | fatal(...args: unknown[]): Logger;
|
260 | }
|
261 | export declare const computeLevel: (optionsLevel?: number | string) => string;
|