chore: merged from master

docs/appenders.md

@@ -27,7 +27,6 @@ The following appenders are included with log4js. Some require extra dependencie
 * [hipchat](hipchat.md)
 * [logFaces-HTTP](logFaces-HTTP.md)
 * [logFaces-UDP](logFaces-UDP.md)
-* [loggly](loggly.md)
 * [logLevelFilter](logLevelFilter.md)
 * [logstashHTTP](logstashHTTP.md)
 * [logstashUDP](logstashUDP.md)
@@ -52,6 +51,17 @@ The following appenders are supported by log4js, but are no longer distributed w
 
 For example, if you were previously using the gelf appender (`type: 'gelf'`) then you should add `@log4js-node/gelf` to your dependencies and change the type to `type: '@log4js-node/gelf'`.
 
+## Optional Appenders
+
+The following appenders are supported by log4js, but will issue deprecation warnings from version 2.6 onwards - they will be removed from the log4js core in version 3. If you are using these appenders, you should alter your dependencies to include them explicitly.
+
+* [gelf](https://github.com/log4js-node/gelf)
+* [loggly](https://github.com/log4js-node/loggly)
+
+For example, if you were previously using the gelf appender (`type: 'gelf'`) then you should add `@log4js-node/gelf` to your dependencies and change the type to `type: '@log4js-node/gelf'`.
+
+To turn off the deprecation warnings, add `deprecationWarnings: false` to your log4js config. The core version of the appender will still work. But note that you will have to install the external appenders when version 3 is released as they will not be included at all.
+
 ## Other Appenders
 
 Log4js can load appenders from outside the core appenders. The `type` config value is used as a require path if no matching appender can be found. For example, the following configuration will attempt to load an appender from the module 'cheese/appender', passing the rest of the config for the appender to that module:

docs/index.md

@@ -13,7 +13,7 @@ There have been a few changes between log4js 1.x and 2.x (and 0.x too). You shou
 * [file appender](file.md), with configurable log rolling based on file size or [date](dateFile.md)
 * [SMTP appender](smtp.md)
 * [GELF appender](https://github.com/log4js-node/gelf)
-* [Loggly appender](loggly.md)
+* [Loggly appender](https://github.com/log4js-node/loggly)
 * [Logstash UDP appender](logstashUDP.md)
 * logFaces ([UDP](logFaces-UDP.md) and [HTTP](logFaces-HTTP.md)) appender
 * [TCP appender](tcp.md) (useful when you've got multiple servers but want to centralise logging)

docs/loggly.md

@@ -1,36 +0,0 @@
-# Loggly Appender
-
-Sends logging events to [Loggly](https://www.loggly.com), optionally adding tags. This appender uses [node-loggly](https://www.npmjs.com/package/loggly), and you will need to include that in your dependencies if you want to use this appender. Consult the docs for node-loggly, or loggly itself, if you want more information on the configuration options below.
-
-## Configuration
-
-* `type` - `loggly`
-* `token` - `string` - your really long input token
-* `subdomain` - `string` - your subdomain
-* `tags` - `Array<string>` (optional) - tags to include in every log message
-
-This appender will scan the msg from the logging event, and pull out any argument of the
-shape `{ tags: [] }` so that it's possible to add additional tags in a normal logging call. See the example below.
-
-## Example
-
-```javascript
-log4js.configure({
-  appenders: {
-    loggly: {
-      type: 'loggly',
-      token: 'somethinglong',
-      subdomain: 'your.subdomain',
-      tags: [ 'tag1' ]
-    }
-  },
-  categories: {
-    default: { appenders: ['loggly'], level: 'info' }
-  }
-});
-
-const logger = log4js.getLogger();
-logger.info({ tags: ['my-tag-1', 'my-tag-2'] }, 'Some message');
-```
-
-This will result in a log message being sent to loggly with the tags `tag1`, `my-tag-1`, `my-tag-2`.

lib/appenders/loggly.js

@@ -2,6 +2,10 @@
 
 'use strict';
 
+/**
+ * This appender has been deprecated.
+ * Updates and bug fixes should be made against https://github.com/log4js-node/loggly
+ */
 const debug = require('debug')('log4js:loggly');
 const loggly = require('loggly');
 const os = require('os');
@@ -105,6 +109,9 @@ function logglyAppender(config, layout) {
     }
   };
 
+  // trigger a deprecation warning, with a pointer to the replacement lib
+  app.deprecated = '@log4js-node/loggly';
+
   return app;
 }