chore: deprecated the gelf appender

docs/appenders.md

@@ -24,7 +24,6 @@ The following appenders are included with log4js. Some require extra dependencie
 * [dateFile](dateFile.md)
 * [file](file.md)
 * [fileSync](fileSync.md)
-* [gelf](gelf.md)
 * [hipchat](hipchat.md)
 * [logFaces-HTTP](logFaces-HTTP.md)
 * [logFaces-UDP](logFaces-UDP.md)
@@ -43,6 +42,16 @@ The following appenders are included with log4js. Some require extra dependencie
 * [stdout](stdout.md)
 * [rabbitmq](rabbitmq.md)
 
+## 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)
+
+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/gelf.md

@@ -1,53 +0,0 @@
-# GELF appender
-
-The GELF appender supports sending log messages over UDP to a [GELF](http://docs.graylog.org/en/2.2/pages/gelf.html) compatible server such as [Graylog](https://www.graylog.org). It uses node's core UDP support and does not require any other dependencies. If you use this appender, remember to call `log4js.shutdown` when your application terminates, so that all messages will have been sent to the server and the UDP socket can be closed. The appender supports passing custom fields to the server in both the config, and in individual log messages (see examples below).
-
-## Configuration
-
-* `type` - `gelf`
-* `host` - `string` (defaults to `localhost`) - the gelf server hostname
-* `port` - `integer` (defaults to `12201`) - the port the gelf server is listening on
-* `hostname` - `string` (defaults to `OS.hostname()`) - the hostname used to identify the origin of the log messages.
-* `facility` - `string` (optional)
-* `customFields` - `object` (optional) - fields to be added to each log message; custom fields must start with an underscore.
-
-## Example (default config)
-```javascript
-log4js.configure({
-  appenders: {
-    gelf: { type: 'gelf' }
-  },
-  categories: {
-    default: { appenders: ['gelf'], level: 'info' }
-  }
-});
-```
-This will send log messages to a server at `localhost:12201`.
-
-## Example (custom fields in config)
-```javascript
-log4js.configure({
-  appenders: {
-    gelf: { type: 'gelf', host: 'gelf.server', customFields: { '_something': 'yep' } }
-  },
-  categories: {
-    default: { appenders: ['gelf'], level: 'info' }
-  }
-});
-```
-This will result in all log messages having the custom field `_something` set to 'yep'.
-
-# Example (custom fields in log message)
-```javascript
-log4js.configure({
-  appenders: {
-    gelf: { type: 'gelf', customFields: { '_thing': 'isathing' } }
-  },
-  categories: {
-    default: { appenders: ['gelf'], level: 'info' }
-  }
-});
-const logger = log4js.getLogger();
-logger.error({ GELF: true, _thing2: 'alsoathing' }, 'oh no, something went wrong');
-```
-This will result in a log message with the custom fields `_thing` and `_thing2`. Note that log message custom fields will override config custom fields.

docs/index.md

@@ -12,7 +12,7 @@ There have been a few changes between log4js 1.x and 2.x (and 0.x too). You shou
 * coloured console logging to [stdout](stdout.md) or [stderr](stderr.md)
 * [file appender](file.md), with configurable log rolling based on file size or [date](dateFile.md)
 * [SMTP appender](smtp.md)
-* [GELF appender](gelf.md)
+* [GELF appender](https://github.com/log4js-node/gelf)
 * [Loggly appender](loggly.md)
 * [Logstash UDP appender](logstashUDP.md)
 * logFaces ([UDP](logFaces-UDP.md) and [HTTP](logFaces-HTTP.md)) appender

lib/appenders/gelf.js

@@ -131,6 +131,9 @@ function gelfAppender(layout, config, levels) {
     }
   };
 
+  // trigger a deprecation warning, with a pointer to the replacement lib
+  app.deprecated = '@log4js-node/gelf';
+
   return app;
 }
 

lib/configuration.js

@@ -85,12 +85,22 @@ class Configuration {
       debug(`pm2 enabled ? ${this.pm2}`);
       debug(`pm2InstanceVar = ${this.pm2InstanceVar}`);
       debug(`process.env[${this.pm2InstanceVar}] = ${process.env[this.pm2InstanceVar]}`);
-      return appenderModule.configure(
+
+      const appender = appenderModule.configure(
         config,
         layouts,
         this.configuredAppenders.get.bind(this.configuredAppenders),
         this.configuredLevels
       );
+
+      if (appender.deprecated && this.deprecationWarnings) {
+        console.error(`Appender "${name}" uses a deprecated type "${config.type}", ` + // eslint-disable-line
+          'which will be removed in log4js v3. ' +
+          `You should change it to use "${appender.deprecated}". ` +
+          'To turn off this warning add "deprecationWarnings: false" to your config.');
+      }
+
+      return appender;
     }
     return () => {};
   }
@@ -204,6 +214,10 @@ class Configuration {
     this.throwExceptionIf(not(anObject(candidate.categories)), 'must have a property "categories" of type object.');
 
     this.disableClustering = this.candidate.disableClustering || !cluster;
+    this.deprecationWarnings = true;
+    if ('deprecationWarnings' in this.candidate) {
+      this.deprecationWarnings = this.candidate.deprecationWarnings;
+    }
 
     this.pm2 = this.candidate.pm2;
     this.pm2InstanceVar = this.candidate.pm2InstanceVar || 'NODE_APP_INSTANCE';

test/tap/configuration-validation-test.js

@@ -6,7 +6,7 @@ const util = require('util');
 const path = require('path');
 const sandbox = require('sandboxed-module');
 
-function testAppender(label) {
+function testAppender(label, deprecated) {
   return {
     configure: function (config, layouts, findAppender) {
       return {
@@ -15,7 +15,8 @@ function testAppender(label) {
         label: label,
         config: config,
         layouts: layouts,
-        findAppender: findAppender
+        findAppender: findAppender,
+        deprecated: deprecated
       };
     }
   };
@@ -324,5 +325,89 @@ test('log4js configuration validation', (batch) => {
     t.end();
   });
 
+  batch.test('should display deprecation warning if needed', (t) => {
+    let deprecationMessage;
+    const SandboxedConfiguration = sandbox.require(
+      '../../lib/configuration',
+      {
+        singleOnly: true,
+        requires: {
+          './appenders/gelf': testAppender('gelf', '@some/lib')
+        },
+        globals: {
+          console: {
+            error: (msg) => {
+              deprecationMessage = msg;
+            }
+          }
+        }
+      }
+    );
+
+    const config = new SandboxedConfiguration({
+      appenders: { thing: { type: 'gelf' } },
+      categories: { default: { appenders: ['thing'], level: 'debug' } }
+    });
+
+    t.test('should output warning on console.error', (assert) => {
+      assert.equal(
+        deprecationMessage,
+        'Appender "thing" uses a deprecated type "gelf", which will be removed in log4js v3. ' +
+        'You should change it to use "@some/lib". ' +
+        'To turn off this warning add "deprecationWarnings: false" to your config.'
+      );
+      assert.end();
+    });
+
+    t.test('should still return an appender', (assert) => {
+      const thing = config.appenders.get('thing');
+      assert.ok(thing.configureCalled);
+      assert.equal(thing.type, 'gelf');
+      assert.end();
+    });
+
+    t.end();
+  });
+
+  batch.test('should not display deprecation warning if turned off', (t) => {
+    let deprecationMessage;
+    const SandboxedConfiguration = sandbox.require(
+      '../../lib/configuration',
+      {
+        singleOnly: true,
+        requires: {
+          './appenders/gelf': testAppender('gelf', '@some/lib')
+        },
+        globals: {
+          console: {
+            error: (msg) => {
+              deprecationMessage = msg;
+            }
+          }
+        }
+      }
+    );
+
+    const config = new SandboxedConfiguration({
+      appenders: { thing: { type: 'gelf' } },
+      categories: { default: { appenders: ['thing'], level: 'debug' } },
+      deprecationWarnings: false
+    });
+
+    t.test('should not output warning on console.error', (assert) => {
+      assert.notOk(deprecationMessage);
+      assert.end();
+    });
+
+    t.test('should still return an appender', (assert) => {
+      const thing = config.appenders.get('thing');
+      assert.ok(thing.configureCalled);
+      assert.equal(thing.type, 'gelf');
+      assert.end();
+    });
+
+    t.end();
+  });
+
   batch.end();
 });