7
7
8
8
A Lightweight logger that combines debug namespacing capabilities with winston levels and multioutput
9
9
10
- - [ Installation] ( #installation )
11
- - [ Usage] ( #usage )
12
- - [ Using context ID] ( #using-context-id )
13
- - [ Using namespaces] ( #using-namespaces )
14
- - [ Outputs] ( #outputs )
15
- - [ Metadata] ( #metadata )
16
- - [ TypeScript] ( #typescript )
10
+ - [ Installation] ( #installation )
11
+ - [ Usage] ( #usage )
12
+ - [ Using context ID] ( #using-context-id )
13
+ - [ Using namespaces] ( #using-namespaces )
14
+ - [ Outputs] ( #outputs )
15
+ - [ Metadata] ( #metadata )
16
+ - [ TypeScript] ( #typescript )
17
17
18
18
## Installation
19
19
20
20
Using npm:
21
21
22
- ``` sh
22
+ ``` sh
23
23
npm install @ekino/logger
24
24
```
25
25
26
26
Or yarn:
27
27
28
- ``` sh
28
+ ``` sh
29
29
yarn add @ekino/logger
30
30
```
31
31
@@ -40,12 +40,12 @@ A log instance is bounded to a namespace. To use it, instantiate a logger with a
40
40
41
41
This logger define 5 log levels: error, warn, info, debug, trace.
42
42
When you set a level, all levels above it are enabled too.
43
- Log level can be set by calling ` setLevel ` function.
43
+ Log level can be set by calling ` setLevel ` function.
44
44
45
45
For example, enabling ` info ` will enable ` info ` , ` warn ` and ` error ` but not ` debug ` or ` trace ` .
46
46
The "special" log level ` none ` means no log and can only be used to set a namespace level.
47
47
48
- ``` js
48
+ ``` js
49
49
{ trace: 0 , debug: 1 , info: 2 , warn: 3 , error: 4 }
50
50
```
51
51
@@ -69,7 +69,7 @@ logger.debug('sample message', {
69
69
})
70
70
```
71
71
72
- output:
72
+ output:
73
73
74
74
![ Example] ( docs/images/example_usage1.gif )
75
75
@@ -79,15 +79,15 @@ One of the main complexity working with node is ability to follow all logs attac
79
79
This is not mandatory, but based on our experience, we recommend as a best practice to add a unique identifier that will be passed all along functions calls.
80
80
When you log something, you can provide this id as a first parameter and logger will log it. If not provided, it's auto generated.
81
81
82
- The signature of the function with contextId is:
82
+ The signature of the function with contextId is:
83
83
84
84
``` js
85
85
my_log .the_level (contextId, message, data)
86
86
```
87
87
88
88
Example app.js
89
89
90
- ``` javascript
90
+ ``` javascript
91
91
const { setNamespaces , setLevel , createLogger } = require (' @ekino/logger' )
92
92
93
93
setNamespaces (' root:*' )
@@ -99,25 +99,25 @@ logger.debug('ctxId', 'log with predefined context ID', {
99
99
})
100
100
```
101
101
102
- output:
102
+ output:
103
103
104
104
![ Example] ( docs/images/example_usage2.gif )
105
105
106
106
### Using namespaces
107
107
108
108
Logger relies on namespaces. When you want to log something, you should define a namespace that is bound to it.
109
109
When you debug, this gives you the flexibility to enable only the namespaces you need to output.
110
- As a good practice, we recommend setting a namespace by folder / file.
110
+ As a good practice, we recommend setting a namespace by folder / file.
111
111
For example for a file in modules/login/dao you could define 'modules:login: dao '.
112
112
Warning, "=" can't be part of the namespace as it's a reserved symbol.
113
113
114
114
You can also define a level per namespace. If no level is defined, the default global level is used.
115
115
To disable logs of a namespace, you can specify a level ` none `
116
- A namespace ':* ' means eveything after ':' will be enabled. Namespaces are parsed as regexp.
116
+ A namespace ':\ * ' means eveything after ':' will be enabled. Namespaces are parsed as regexp.
117
117
118
- To define namespace level, you should suffix namespace with "=the_level"
119
- For example let's say you need to enable all info logs but for debug purpose you need to lower the level
120
- of the namespace database to ` debug ` . You could then use:
118
+ To define namespace level, you should suffix namespace with "=the_level"
119
+ For example let's say you need to enable all info logs but for debug purpose you need to lower the level
120
+ of the namespace database to ` debug ` . You could then use:
121
121
122
122
``` js
123
123
const { setLevel , setNamespaces } = require (' @ekino/logger' )
@@ -173,11 +173,11 @@ setOutput(outputs.json)
173
173
const logger = createLogger (' namespace:subNamespace' )
174
174
logger .debug (' ctxId' , ' Will be logged' , {
175
175
someData: ' someValue' ,
176
- someData2: ' someValue'
176
+ someData2: ' someValue' ,
177
177
})
178
178
```
179
179
180
- output:
180
+ output:
181
181
182
182
![ Example] ( docs/images/example_usage3.gif )
183
183
@@ -187,27 +187,27 @@ Pretty will output a yaml like content.
187
187
188
188
``` js
189
189
const { setNamespaces , setLevel , setOutput , outputs , createLogger } = require (' @ekino/logger' )
190
-
190
+
191
191
setNamespaces (' namespace:*' )
192
192
setLevel (' debug' )
193
193
setOutput (outputs .pretty )
194
194
195
195
const logger = createLogger (' namespace:subNamespace' )
196
196
logger .debug (' ctxId' , ' Will be logged' , {
197
197
someData: ' someValue' ,
198
- someData2: ' someValue'
198
+ someData2: ' someValue' ,
199
199
})
200
200
```
201
201
202
- output:
202
+ output:
203
203
204
204
![ Example] ( docs/images/example_pretty.gif )
205
205
206
206
#### Output function
207
207
208
208
An output, is a function that will receive log data and should transform and store it
209
209
210
- Log data follow the format:
210
+ Log data follow the format:
211
211
212
212
```
213
213
{
@@ -223,22 +223,22 @@ Log data follow the format:
223
223
224
224
``` js
225
225
const { setNamespaces , setLevel , setOutput , outputs , outputUtils , createLogger } = require (' @ekino/logger' )
226
-
226
+
227
227
setNamespaces (' namespace:*' )
228
228
setLevel (' debug' )
229
229
230
230
const consoleAdapter = (log ) => {
231
231
console .log (outputUtils .stringify (log))
232
232
}
233
233
234
- // This will output in stdout with the pretty output
234
+ // This will output in stdout with the pretty output
235
235
// and in the same will log through native console.log() function (usually to stdout too)
236
236
setOutput ([outputs .pretty , consoleAdapter])
237
237
238
238
const logger = createLogger (' namespace:subNamespace' )
239
239
logger .debug (' ctxId' , ' Will be logged' , {
240
240
someData: ' someValue' ,
241
- someData2: ' someValue'
241
+ someData2: ' someValue' ,
242
242
})
243
243
```
244
244
@@ -258,12 +258,12 @@ const consoleAdapter = (log) => {
258
258
### Log data
259
259
260
260
Most of the time, a log message is not enough to guess context.
261
- You can append arbitrary data to your logs.
261
+ You can append arbitrary data to your logs.
262
262
If you're using some kind of log collector, you'll then be able to extract those values and inject them in elasticsearch for example.
263
263
264
264
``` js
265
265
const { setOutput , setNamespaces , setLevel , createLogger } = require (' @ekino/logger' )
266
-
266
+
267
267
setOutput (' pretty' )
268
268
setNamespaces (' namespace:*' )
269
269
setLevel (' info' )
@@ -272,7 +272,7 @@ const logger = createLogger('namespace:subNamespace')
272
272
logger .warn (' message' , { someData: ' someValue' })
273
273
```
274
274
275
- output:
275
+ output:
276
276
277
277
![ Example] ( docs/images/example_data.gif )
278
278
@@ -293,7 +293,7 @@ const logger = createLogger('namespace')
293
293
logger .warn (' message' , { someData: ' someValue' })
294
294
```
295
295
296
- output:
296
+ output:
297
297
298
298
![ Example] ( docs/images/example_context.gif )
299
299
0 commit comments