docs: line number feature documentation

docs/api.md

@@ -19,6 +19,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.
 * `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.

docs/faq.md

@@ -42,3 +42,29 @@ Take a look at the [clustering](clustering.md) docs, they should help you out.
 ## NPM complains about nodemailer being deprecated, what should I do?
 
 Nodemailer version 4.0.1 (the not-deprecated version) requires a node version >= 6, but log4js supports node versions >= 4. So until I stop supporting node versions less than 6 I can't update the dependency. It's only an optional dependency anyway, so you're free to install nodemailer@4.0.1 if you want - as far as I know it should work, the API looks the same to me. If you know that the smtp appender definitely doesn't work with nodemailer v4, then please create an issue with some details about the problem.
+
+## I want line numbers in my logs!
+
+You need to enable call stack for the category, and use pattern layout to output the values. e.g.
+```javascript
+const log4js = require('log4js');
+log4js.configure({
+  appenders: {
+    out: {
+      type: 'stdout',
+      layout: {
+        type: 'pattern', pattern: '%d %p %c %f:%l %m%n'
+      }
+    }
+  },
+  categories: {
+    default: { appenders: ['out'], level: 'info', enableCallStack: true }
+  }
+});
+const logger = log4js.getLogger('thing');
+logger.info('this should give me a line number now');
+```
+Would output something like this:
+```bash
+2019-05-22T08:41:07.312 INFO thing index.js:16 this should give me a line number now
+```

docs/layouts.md

@@ -112,6 +112,10 @@ Fields can be any of:
 *  `%%` % - for when you want a literal `%` in your output
 *  `%n` newline
 *  `%z` process id (from `process.pid`)
+*  `%f` filename (requires `enableCallStack: true` on the category, see [configuration object](api.md))
+*  `%l` line number (requires `enableCallStack: true` on the category, see [configuration object](api.md))
+*  `%o` column postion (requires `enableCallStack: true` on the category, see [configuration object](api.md))
+*  `%s` call stack (requires `enableCallStack: true` on the category, see [configuration object](api.md))
 *  `%x{<tokenname>}` add dynamic tokens to your log. Tokens are specified in the tokens parameter.
 *  `%X{<tokenname>}` add values from the Logger context. Tokens are keys into the context values.
 *  `%[` start a coloured block (colour will be taken from the log level, similar to `colouredLayout`)