From 90fdcaacc5d00d3f599c26d392b3059eb61db243 Mon Sep 17 00:00:00 2001
From: rnd-debug <silverfoxix@yahoo.fr>
Date: Sun, 3 May 2020 11:03:17 +0200
Subject: [PATCH 1/2] docs: adding doc about categories

---
 docs/categories.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/categories.md

diff --git a/docs/categories.md b/docs/categories.md
new file mode 100644
index 0000000..1e7aac9
--- /dev/null
+++ b/docs/categories.md
@@ -0,0 +1,48 @@
+# Categories
+Categories are groups of log events. The category for log events is defined when you get a _Logger_ from log4js (`log4js.getLogger('somecategory')`). Log events with the same _category_ will go to the same _appenders_.
+
+## Default configuration
+When defining your appenders through a configuration, at least one category must be defined.
+
+```javascript
+const log4js = require('log4js');
+log4js.configure({
+  appenders: {
+    out: { type: 'stdout' },
+  },
+  categories: {
+    default: { appenders: [ 'out' ], level: 'trace' }
+  }
+});
+```
+
+## Categories inheritance
+Log4js supports a hierarchy for categories, using dots to separate layers - for example, log events in the category 'myapp.submodule' will use the level for 'myapp' if none is defined for 'myapp.submodule', and also any appenders defined for 'myapp'. 
+This behaviour can be disabled by setting inherit=false on the sub-category. 
+
+```javascript
+const log4js = require('log4js');
+log4js.configure({
+  appenders: {
+    console: { type: 'console' },
+    app: { type: 'file', filename: 'application.log' }
+  },
+  categories: {
+    default: { appenders: [ 'console' ], level: 'trace' },
+    catA: { appenders: ['console'], level: 'error' },
+    'catA.catB': { appenders: ['app'], level: 'trace' },
+  }
+});
+
+const loggerA = log4js.getLogger('catA');
+loggerA.error('This will be written to console with log level ERROR');
+loggerA.trace('This will not be written');
+const loggerAB = log4js.getLogger('catA.catB');
+loggerAB.error('This will be written with log level ERROR to console and to a file');
+loggerAB.trace('This will be written with log level TRACE to console and to a file');
+```
+Two categories are defined:
+- Log events with category 'catA' will go to appender 'console' only.
+- Log events with category 'catA.catB' will go to appenders 'console' and 'app'. 
+
+Appenders will see and log an event only if the category level is less than or equal to the event's level.

From 6a6cbdb3838a42511a698cdef330c704ee022066 Mon Sep 17 00:00:00 2001
From: rnd-debug <silverfoxix@yahoo.fr>
Date: Sun, 3 May 2020 11:11:27 +0200
Subject: [PATCH 2/2] docs: improving default example in categories.md

---
 docs/categories.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/categories.md b/docs/categories.md
index 1e7aac9..8372a4f 100644
--- a/docs/categories.md
+++ b/docs/categories.md
@@ -9,11 +9,18 @@ const log4js = require('log4js');
 log4js.configure({
   appenders: {
     out: { type: 'stdout' },
+    app: { type: 'file', filename: 'application.log' }
   },
   categories: {
-    default: { appenders: [ 'out' ], level: 'trace' }
+    default: { appenders: [ 'out' ], level: 'trace' },
+    app: { appenders: ['app'], level: 'trace' }
   }
 });
+
+const logger = log4js.getLogger();
+logger.trace('This will use the default category and go to stdout');
+const logToFile = log4js.getLogger('app');
+logToFile.trace('This will go to a file');
 ```
 
 ## Categories inheritance