docs(tcp): added docs for tcp appenders

docs/appenders.md

@@ -35,13 +35,15 @@ The following appenders are included with log4js. Some require extra dependencie
 * [mailgun](mailgun.md)
 * [multiFile](multiFile.md)
 * [multiprocess](multiprocess.md)
+* [rabbitmq](rabbitmq.md)
 * [recording](recording.md)
 * [redis](redis.md)
 * [slack](slack.md)
 * [smtp](smtp.md)
 * [stderr](stderr.md)
 * [stdout](stdout.md)
-* [rabbitmq](rabbitmq.md)
+* [tcp](tcp.md)
+* [tcp-server](tcp-server.md)
 
 ## Other Appenders
 

docs/index.md

@@ -16,7 +16,7 @@ There have been a few changes between log4js 1.x and 2.x (and 0.x too). You shou
 * [Loggly appender](loggly.md)
 * [Logstash UDP appender](logstashUDP.md)
 * logFaces ([UDP](logFaces-UDP.md) and [HTTP](logFaces-HTTP.md)) appender
-* [multiprocess appender](multiprocess.md) (useful when you've got multiple servers but want to centralise logging)
+* [TCP appender](tcp.md) (useful when you've got multiple servers but want to centralise logging)
 * a [logger for connect/express](connect-logger.md) servers
 * configurable log message [layout/patterns](layouts.md)
 * different log levels for different log categories (make some parts of your app log as DEBUG, others only ERRORS, etc.)
@@ -38,6 +38,9 @@ logger.level = 'debug'; // default level is OFF - which means no logs at all.
 logger.debug("Some debug messages");
 ```
 
+## Clustering
+If you use node's cluster, or passenger, or pm2, then you should read this [clustering guide](clustering.md)
+
 ## Note for library makers
 
 If you're writing a library and would like to include support for log4js, without introducing a dependency headache for your users, take a look at [log4js-api](https://github.com/log4js-node/log4js-api).

docs/multiprocess.md

@@ -1,8 +1,11 @@
 # Multiprocess Appender
 
+*You probably want to use the [tcp server](tcp-server.md) or [tcp appender](tcp.md) instead of this - they are more flexible*
+
+*Note that if you're just using node core's `cluster` module then you don't need to use this appender - log4js will handle logging within the cluster transparently.*
+
 The multiprocess appender sends log events to a master server over TCP sockets. It can be used as a simple way to centralise logging when you have multiple servers or processes. It uses the node.js core networking modules, and so does not require any extra dependencies. Remember to call `log4js.shutdown` when your application terminates, so that the sockets get closed cleanly.
 
-Note that if you're just using node core's `cluster` module then you don't need to use this appender - log4js will handle logging within the cluster transparently.
 
 ## Configuration
 

docs/tcp-server.md

@@ -0,0 +1,23 @@
+# TCP Server Appender
+
+Strictly speaking, this is not an appender - but it is configured as one. The TCP server listens for log messages on a port, taking JSON-encoded log events and then forwarding them to the other appenders. It can be used as a simple way to centralise logging when you have multiple servers or processes. It uses the node.js core networking modules, and so does not require any extra dependencies. Remember to call `log4js.shutdown` when your application terminates, so that the sockets get closed cleanly. It is designed to work with the [tcp appender](tcp.md), but could work with anything that sends correctly formatted JSON log events.
+
+## Configuration
+
+* `type` - `tcp-server`
+* `port` - `integer` (optional, defaults to `5000`) - the port to listen on
+* `host` - `string` (optional, defaults to `localhost`) - the host/IP address to listen on
+
+## Example (master)
+```javascript
+log4js.configure({
+  appenders: {
+    file: { type: 'file', filename: 'all-the-logs.log' },
+    server: { type: 'tcp-server', host: '0.0.0.0' }
+  },
+  categories: {
+    default: { appenders: ['file'], level: 'info' }
+  }
+});
+```
+This creates a log server listening on port 5000, on all IP addresses the host has assigned to it. Note that the appender is not included in the appenders listed for the categories. All events received on the socket will be forwarded to the other appenders, as if they had originated on the same server.

docs/tcp.md

@@ -0,0 +1,22 @@
+# TCP Appender
+
+The TCP appender sends log events to a master server over TCP sockets. It can be used as a simple way to centralise logging when you have multiple servers or processes. It uses the node.js core networking modules, and so does not require any extra dependencies. Remember to call `log4js.shutdown` when your application terminates, so that the sockets get closed cleanly. It's designed to work with the [tcp-server](tcp-server.md), but it doesn't necessarily have to, just make sure whatever is listening at the other end is expecting JSON objects as strings.
+
+## Configuration
+
+* `type` - `tcp`
+* `port` - `integer` (optional, defaults to `5000`) - the port to send to
+* `host` - `string` (optional, defaults to `localhost`) - the host/IP address to send to
+
+## Example
+```javascript
+log4js.configure({
+  appenders: {
+    network: { type: 'tcp', host: 'log.server' }
+  },
+  categories: {
+    default: { appenders: ['network'], level: 'error' }
+  }
+});
+```
+This will send all error messages to `log.server:5000`.