From 4ffbcae8b23f7ce5effeb4045c44b265ef2b416c Mon Sep 17 00:00:00 2001 From: Zachary Haber Date: Fri, 17 Jun 2022 14:49:40 -0500 Subject: [PATCH] chore: update docs --- docs/api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api.md b/docs/api.md index 45b7656..6c3b7da 100644 --- a/docs/api.md +++ b/docs/api.md @@ -21,7 +21,7 @@ Properties: - `categories` (object) - a map of named categories (string) to category definitions (object). You must define the `default` category which is used for all log events that do not match a specific category. Category definitions have two properties: - `appenders` (array of strings) - the list of appender names to be used for this category. A category must have at least one appender. - `level` (string, case insensitive) - the minimum log level that this category will send to the appenders. For example, if set to 'error' then the appenders will only receive log events of level 'error', 'fatal', 'mark' - log events of 'info', 'warn', 'debug', or 'trace' will be ignored. - - `enableCallStack` (boolean, optional, defaults to `false`) - setting this to `true` will make log events for this category use the call stack to generate line numbers and file names in the event. See [pattern layout](layouts.md) for how to output these values in your appenders. + - `enableCallStack` (boolean, optional, defaults to `false`) - setting this to `true` will make log events for this category use the call stack to generate line numbers and file names in the event. See [pattern layout](layouts.md) for how to output these values in your appenders. If you log an Error object as the first parameter, that Error will be used to generate the line numbers and file name instead. - `pm2` (boolean) (optional) - set this to true if you're running your app using [pm2](http://pm2.keymetrics.io), otherwise logs will not work (you'll also need to install pm2-intercom as pm2 module: `pm2 install pm2-intercom`) - `pm2InstanceVar` (string) (optional, defaults to 'NODE_APP_INSTANCE') - set this if you're using pm2 and have changed the default name of the NODE_APP_INSTANCE variable. - `disableClustering` (boolean) (optional) - set this to true if you liked the way log4js used to just ignore clustered environments, or you're having trouble with PM2 logging. Each worker process will do its own logging. Be careful with this if you're logging to files, weirdness can occur. @@ -35,12 +35,13 @@ This function takes a single optional string argument to denote the category to - `addContext(,)` - where `` is a string, `` can be anything. This stores a key-value pair that is added to all log events generated by the logger. Uses would be to add ids for tracking a user through your application. Currently only the `logFaces` appenders make use of the context values. - `removeContext()` - removes a previously defined key-value pair from the context. - `clearContext()` - removes all context pairs from the logger. -- `setParseCallStackFunction(function)` - Allow to override the default way to parse the callstack data for the layout pattern, a generic javascript Error object is passed to the function. Must return an object with properties : `functionName` / `fileName` / `lineNumber` / `columnNumber` / `callStack`. Can for example be used if all of your log call are made from one "debug" class and you would to "erase" this class from the callstack to only show the function which called your "debug" class. +- `setParseCallStackFunction(function | undefined)` - Allow to override the default way to parse the callstack data for the layout pattern, a generic javascript Error object is passed to the function. Must return an object with properties : `functionName` / `fileName` / `lineNumber` / `columnNumber` / `callStack`. Can for example be used if all of your log call are made from one "debug" class and you would to "erase" this class from the callstack to only show the function which called your "debug" class. If you pass `undefined` as the argument, it will be reset to the default parser. The `Logger` object has the following properties: - `level` - where `level` is a log4js level or a string that matches a level (e.g. 'info', 'INFO', etc). This allows overriding the configured level for this logger. Changing this value applies to all loggers of the same category. - `useCallStack` - where `useCallStack` is a boolean to indicate if log events for this category use the call stack to generate line numbers and file names in the event. This allows overriding the configured useCallStack for this logger. Changing this value applies to all loggers of the same category. +- `callStackLinesToSkip` - where `callStackLinesToSkip` is a number (0 by default) that allows you to customize how many lines of the call stack should be skipped when parsing the Error stack. For example, if you call the logger from within a dedicated logging function, you can use `callStackLinesToSkip = 1` to ignore that function when looking at stack traces. ## Shutdown - `log4js.shutdown([callback])`