Skip to content

Commit 416086e

Browse files
committed
fix(package): upgrade dependencies and update readme
1 parent 6db94fd commit 416086e

File tree

3 files changed

+3654
-3524
lines changed

3 files changed

+3654
-3524
lines changed

README.md

Lines changed: 139 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,169 @@
1-
# json-logger-js
1+
# @emartech/json-logger
22

3-
Simple JSON logger middleware that combines the namespaces of [debug] and the
4-
machine readable JSON format of [bunyan].
3+
A tiny and fast logging library that outputs logs in JSON format.
4+
It has the same namespace based enabling/disabling mechanism as [debug]
5+
and has the same log levels as [bunyan].
56

6-
It has the same logging levels as [bunyan].
7+
### Installation
78

8-
## Example logging
9+
```bash
10+
npm install @emartech/json-logger
11+
```
12+
13+
### Usage
914

1015
```javascript
1116
process.env.DEBUG = 'redis';
1217
const mongoLogger = require('@emartech/json-logger')('mongo');
1318
const redisLogger = require('@emartech/json-logger')('redis');
1419

15-
// simple info logging with enabled namespace
1620
redisLogger.info('connected', { domain: 'yahoo' });
21+
// {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z","domain":"yahoo"}
1722

18-
// not enabled
1923
mongoLogger.info('connected', { domain: 'google' });
24+
// no output, because 'mongo' is not within namespaces (process.env.DEBUG)
2025

21-
// error objects
2226
redisLogger.fromError('query', new Error('Unauthorized'), { problem: 'missmatch' });
27+
// {"name":"redis","action":"query","level":50,"time":"2016-08-15T08:50:23.569Z","error_name":"Error","error_stack":"Error: Unauthorized\n at Object.<anonymous> (/home/blacksonic/workspace/bunyan-debug/example.js:15:32)\n at Module._compile (module.js:541:32)\n at Object.Module._extensions..js (module.js:550:10)\n at Module.load (module.js:458:32)\n at tryModuleLoad (module.js:417:12)\n at Function.Module._load (module.js:409:3)\n at Module.runMain (module.js:575:10)\n at run (bootstrap_node.js:352:7)\n at startup (bootstrap_node.js:144:9)\n at bootstrap_node.js:467:3","error_message":"Unauthorized","problem":"missmatch"}
2328
```
2429

25-
will output
30+
More examples can be found in the `examples` directory.
31+
32+
### API
33+
34+
##### JsonLogger(namespace)
35+
36+
The default export of the library acts as a factory method.
37+
Returns a logging instance with the given namespace.
38+
The `DEBUG` environment variable is then used to enable these instances based on comma-delimited names.
39+
Disabled instances output no logs.
40+
41+
```javascript
42+
process.env.DEBUG = 'redis,mysql';
43+
44+
const mongoLogger = require('@emartech/json-logger')('mongo');
45+
// mongo instance will be disabled
2646

47+
const redisLogger = require('@emartech/json-logger')('redis');
48+
// redis instance will be enabled
2749
```
28-
{"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z","domain":"yahoo"}
29-
{"name":"redis","action":"query","level":50,"time":"2016-08-15T08:50:23.569Z","error_name":"Error","error_stack":"Error: Unauthorized\n at Object.<anonymous> (/home/blacksonic/workspace/bunyan-debug/example.js:15:32)\n at Module._compile (module.js:541:32)\n at Object.Module._extensions..js (module.js:550:10)\n at Module.load (module.js:458:32)\n at tryModuleLoad (module.js:417:12)\n at Function.Module._load (module.js:409:3)\n at Module.runMain (module.js:575:10)\n at run (bootstrap_node.js:352:7)\n at startup (bootstrap_node.js:144:9)\n at bootstrap_node.js:467:3","error_message":"Unauthorized","problem":"missmatch"}
50+
51+
##### JsonLogger.prototype.info(action, data)
52+
53+
Prints the provided data to the console in JSON format.
54+
55+
```javascript
56+
const redisLogger = require('@emartech/json-logger')('redis');
57+
58+
redisLogger.info('connected', { domain: 'yahoo' });
59+
// {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z","domain":"yahoo"}
60+
61+
redisLogger.info('connected');
62+
// {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z"}
3063
```
3164

32-
Examples can be found in ```examples/index.js```.
65+
By default displays the namespace of the instance (`name`), the current time in ISO8601 format (`time`),
66+
the action passed to the log method and the log level associated with the method.
67+
The second argument is assigned to these basic fields and is displayed along with them.
68+
69+
##### JsonLogger.prototype.trace(action, data)
70+
71+
Same as info with trace log level.
72+
73+
##### JsonLogger.prototype.debug(action, data)
74+
75+
Same as info with debug log level.
76+
77+
##### JsonLogger.prototype.warn(action, data)
78+
79+
Same as info with warn log level.
80+
81+
##### JsonLogger.prototype.error(action, data)
82+
83+
Same as info with error log level.
84+
85+
##### JsonLogger.prototype.fatal(action, data)
86+
87+
Same as info with fatal log level.
88+
89+
##### JsonLogger.prototype.fromError(action, data)
90+
91+
Displays an error object which formatted to fit into one line.
92+
The displayed line contains the stack trace, the name and the message of the error.
93+
The log level defaults to error.
94+
95+
```javascript
96+
const redisLogger = require('@emartech/json-logger')('redis');
97+
98+
redisLogger.fromError('query', new Error('Unauthorized'), { problem: 'missmatch' });
99+
// {"name":"redis","action":"query","level":50,"time":"2016-08-15T08:50:23.569Z","error_name":"Error","error_stack":"Error: Unauthorized\n at Object.<anonymous> (/home/blacksonic/workspace/bunyan-debug/example.js:15:32)\n at Module._compile (module.js:541:32)\n at Object.Module._extensions..js (module.js:550:10)\n at Module.load (module.js:458:32)\n at tryModuleLoad (module.js:417:12)\n at Function.Module._load (module.js:409:3)\n at Module.runMain (module.js:575:10)\n at run (bootstrap_node.js:352:7)\n at startup (bootstrap_node.js:144:9)\n at bootstrap_node.js:467:3","error_message":"Unauthorized","problem":"missmatch"}
100+
```
101+
102+
##### JsonLogger.prototype.warnFromError(action, data)
103+
104+
Same as `fromError`, but with warn log level.
105+
106+
##### JsonLogger.prototype.timer()
107+
108+
Creates a new instance of timer that has the same methods as the logging instance (info, warn, error, fromError etc.)
109+
but also logs the elapsed time in milliseconds from the creation of the instance.
110+
The elapsed time will be logged into the `duration` field.
111+
112+
```javascript
113+
const redisLogger = require('@emartech/json-logger')('redis');
114+
115+
const timer = redisLogger.timer();
116+
117+
// heavy task
118+
119+
timer.info('completed');
120+
// {"name":"redis","action":"completed","level":30,"time":"2016-08-15T08:50:23.566Z","duration": 1500}
121+
```
122+
123+
##### JsonLogger.configure(options)
124+
125+
The separate steps of the logging process can be configured here.
126+
These modifications affect all the instances of the library.
127+
With transformers we can alter the data to be logged before passing to the formatter and then to the output.
128+
It is a perfect place to add the name of the machine is running on or the request id associated with the current thread stored on a continuation local storage.
129+
130+
```javascript
131+
const Logger = require('@emartech/json-logger');
132+
133+
Logger.configure({
134+
formatter: JSON.stringify,
135+
output: console.log,
136+
transformers: []
137+
});
138+
139+
```
140+
141+
### Log levels
142+
143+
- "fatal" (60): The service/app is going to stop or become unusable now.
144+
An operator should definitely look into this soon.
145+
- "error" (50): Fatal for a particular request, but the service/app continues
146+
servicing other requests. An operator should look at this soon(ish).
147+
- "warn" (40): A note on something that should probably be looked at by an
148+
operator eventually.
149+
- "info" (30): Detail on regular operation.
150+
- "debug" (20): Anything else, i.e. too verbose to be included in "info" level.
151+
- "trace" (10): Logging from external libraries used by your app or *very*
152+
detailed application logging.
33153

34154
### Logging request identifier automatically
35155

36-
The continuation local storage handling has moved to the `@emartech/cls-adapter` package.
37156
You need to use the middlewares of `@emartech/cls-adapter` and add its transformer to the loggers configure method.
38-
This way it will log the request identifier coming from the header field (`X-Request-Id`).
157+
This way it will log the request identifier coming from the header field (`X-Request-Id`) to every log line
158+
where the called function is originating from the route handler.
39159

40160
For automatting
41161

42162
```javascript
43163
const Koa = require('koa');
44164
const logFactory = require('@emartech/json-logger');
45165
const clsAdapter = require('@emartech/cls-adapter');
166+
const logger = logFactory('redis');
46167

47168
logFactory.configure({
48169
transformers: [
@@ -52,17 +173,11 @@ logFactory.configure({
52173

53174
const app = new Koa();
54175
app.use(clsAdapter.getKoaMiddleware());
55-
```
56176

57-
## Development
58-
59-
While developing JSON is not the most readable format. To solve this a little
60-
command line formatter is also included which is very familiar to [debug]'s
61-
output format.
62-
63-
```
64-
redis INFO +0ms action="connected" domain="yahoo"
65-
redis ERROR +2ms action="query" error_message="Unauthorized" error_name="Error" error_stack="Error: Unauthorized\n at Object.<anonymous> (/home/blacksonic/workspace/bunyan-debug/example.js:15:32)\n at Module._compile (module.js:541:32)\n at Object.Module._extensions..js (module.js:550:10)\n at Module.load (module.js:458:32)\n at tryModuleLoad (module.js:417:12)\n at Function.Module._load (module.js:409:3)\n at Module.runMain (module.js:575:10)\n at run (bootstrap_node.js:352:7)\n at startup (bootstrap_node.js:144:9)\n at bootstrap_node.js:467:3" problem="missmatch"
177+
app.use(async () => {
178+
logger.info('connected');
179+
// {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z","request_id":"d5caaa0e-b04e-4d94-bc88-3ed3b62dc94a"}
180+
})
66181
```
67182

68183
[debug]: https://github.com/visionmedia/debug

0 commit comments

Comments
 (0)