From 1e952ffd56631875aaf8757d20d93da6dda0833e Mon Sep 17 00:00:00 2001
From: Gareth Jones <gareth.jones@shinetech.com>
Date: Mon, 12 Feb 2018 07:42:29 +1100
Subject: [PATCH] docs(clustering): added clustering info

---
 docs/clustering.md | 28 ++++++++++++++++++++++++++++
 docs/faq.md        | 18 ++----------------
 2 files changed, 30 insertions(+), 16 deletions(-)
 create mode 100644 docs/clustering.md

diff --git a/docs/clustering.md b/docs/clustering.md
new file mode 100644
index 0000000..31cb9e7
--- /dev/null
+++ b/docs/clustering.md
@@ -0,0 +1,28 @@
+# Clustering / Multi-process Logging
+
+If you're running log4js in an application that uses [node's core cluster](https://nodejs.org/dist/latest-v8.x/docs/api/cluster.html) then log4js will transparently handle making sure the processes don't try to log at the same time. All logging is done on the master process, with the worker processes sending their log messages to the master via `process.send`. This ensures that you don't get multiple processes trying to write to the same file (or rotate the log files) at the same time.
+
+This can cause problems in some rare circumstances, if you're experiencing weird logging problems, then use the `disableClustering: true` option in your log4js configuration to have every process behave as if it were the master process. Be careful if you're logging to files.
+
+## I'm using PM2, but I'm not getting any logs!
+To get log4js working with [PM2](http://pm2.keymetrics.io), you'll need to install the [pm2-intercom](https://www.npmjs.com/package/pm2-intercom) module.
+```bash
+pm2 install pm2-intercom
+```
+Then add the value `pm2: true` to your log4js configuration. If you're also using `node-config`, then you'll probably have renamed your `NODE_APP_INSTANCE` environment variable. If so, you'll also need to add `pm2InstanceVar: '<NEW_APP_INSTANCE_ID>'` where `<NEW_APP_INSTANCE_ID>` should be replaced with the new name you gave the instance environment variable.
+```javascript
+log4js.configure({
+  appenders: { out: { type: 'stdout'}},
+  categories: { default: { appenders: ['out'], level: 'info'}},
+  pm2: true,
+  pm2InstanceVar: 'INSTANCE_ID'
+});
+```
+
+## I'm using Passenger, but I'm not getting any logs!
+
+[Passenger](https://www.phusionpassenger.com/library/) replaces the node.js core cluster module with a non-functional stub, so you won't see any output using log4js. To fix this, add `disableClustering: true` to your configuration. Again, be careful if you're logging to files.
+
+## I'm not using clustering/pm2/passenger but I do have multiple processes that I'd like to all log to the same place
+
+Ok, you probably want to look at the [tcp-server](tcp-server.md) and [tcp appender](tcp.md) documentation.
diff --git a/docs/faq.md b/docs/faq.md
index 2e33348..a7348dc 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -35,23 +35,9 @@ const logger = log4js.getLogger('console');
 console.log = logger.info.bind(logger); // do the same for others - console.debug, etc.
 ```
 
-## I'm using PM2, but I'm not getting any logs!
-To get log4js working with PM2, you'll need to install the [pm2-intercom](https://www.npmjs.com/package/pm2-intercom) module.
-```bash
-pm2 install pm2-intercom
-```
-Then add the value `pm2: true` to your log4js configuration. If you're also using `node-config`, then you'll probably have renamed your `NODE_APP_INSTANCE` environment variable. If so, you'll also need to add `pm2InstanceVar: '<NEW_APP_INSTANCE_ID>'` where `<NEW_APP_INSTANCE_ID>` should be replaced with the new name you gave the instance environment variable.
-```javascript
-log4js.configure({
-  appenders: { out: { type: 'stdout'}},
-  categories: { default: { appenders: ['out'], level: 'info'}},
-  pm2: true,
-  pm2InstanceVar: 'INSTANCE_ID'
-});
-```
+## I'm using pm2/passenger/some other third thing and I'm not getting any logs!
 
-## FFS, why did you mess with the PM2 stuff? It was working fine for me!
-You can turn off the clustering support, with the `disableClustering: true` option in your config. This will make log4js behave more like it did before version 2.x. Each worker process will log its own output, instead of sending it all to the master process. Be careful if you're logging to files though, this could result in weird behaviour.
+Take a look at the [clustering](clustering.md) docs, they should help you out.
 
 ## NPM complains about nodemailer being deprecated, what should I do?