parent
6103afadba
commit
5c33681374
1 changed files with 54 additions and 19 deletions
73
README.md
73
README.md
|
@ -264,15 +264,21 @@ include the unique request id (as "req\_id"). Handy.
|
||||||
|
|
||||||
## Serializers
|
## Serializers
|
||||||
|
|
||||||
Bunyan has a concept of **"serializers" to produce a JSON-able object from a
|
Bunyan has a concept of **"serializer" functions to produce a JSON-able object
|
||||||
JavaScript object**, so you can easily do the following:
|
from a JavaScript object**, so you can easily do the following:
|
||||||
|
|
||||||
```js
|
```js
|
||||||
log.info({req: <request object>}, 'something about handling this request');
|
log.info({req: <request object>}, 'something about handling this request');
|
||||||
```
|
```
|
||||||
|
|
||||||
Serializers is a mapping of log record field name, "req" in this example, to
|
and have the `req` entry in the log record be just a reasonable subset of
|
||||||
a serializer function. That looks like this:
|
`<request object>` fields (or computed data about those fields).
|
||||||
|
|
||||||
|
|
||||||
|
A logger instance can have a `serializers` mapping of log record field name
|
||||||
|
("req" in this example) to a serializer function. When creating the log
|
||||||
|
record, Bunyan will call the serializer function for fields of that name.
|
||||||
|
An example:
|
||||||
|
|
||||||
```js
|
```js
|
||||||
function reqSerializer(req) {
|
function reqSerializer(req) {
|
||||||
|
@ -280,7 +286,7 @@ function reqSerializer(req) {
|
||||||
method: req.method,
|
method: req.method,
|
||||||
url: req.url,
|
url: req.url,
|
||||||
headers: req.headers
|
headers: req.headers
|
||||||
}
|
};
|
||||||
}
|
}
|
||||||
var log = bunyan.createLogger({
|
var log = bunyan.createLogger({
|
||||||
name: 'myapp',
|
name: 'myapp',
|
||||||
|
@ -290,30 +296,59 @@ var log = bunyan.createLogger({
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
Or this:
|
|
||||||
|
Typically serializers are added to a logger at creation time via
|
||||||
|
`bunyan.createLogger({..., serializers: <serializers>})`. However, serializers
|
||||||
|
can be added after creation via `<logger>.addSerializers(...)`, e.g.:
|
||||||
|
|
||||||
```js
|
```js
|
||||||
var log = bunyan.createLogger({
|
var log = bunyan.createLogger({name: 'myapp'});
|
||||||
name: 'myapp',
|
log.addSerializers({req: reqSerializer});
|
||||||
serializers: {req: bunyan.stdSerializers.req}
|
|
||||||
});
|
|
||||||
```
|
```
|
||||||
|
|
||||||
because Bunyan includes a small set of standard serializers. To use all the
|
|
||||||
standard serializers you can use:
|
|
||||||
|
|
||||||
```js
|
|
||||||
var log = bunyan.createLogger({
|
|
||||||
...
|
|
||||||
serializers: bunyan.stdSerializers
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
**Note**: Your own serializers should never throw, otherwise you'll get an
|
**Note**: Your own serializers should never throw, otherwise you'll get an
|
||||||
ugly message on stderr from Bunyan (along with the traceback) and the field
|
ugly message on stderr from Bunyan (along with the traceback) and the field
|
||||||
in your log record will be replaced with a short error message.
|
in your log record will be replaced with a short error message.
|
||||||
|
|
||||||
|
|
||||||
|
### Standard Serializers
|
||||||
|
|
||||||
|
Bunyan includes a small set of "standard serializers", exported as
|
||||||
|
`bunyan.stdSerializers`. Their use is completely optional. Example using
|
||||||
|
all of them:
|
||||||
|
|
||||||
|
```js
|
||||||
|
var log = bunyan.createLogger({
|
||||||
|
name: 'myapp',
|
||||||
|
serializers: bunyan.stdSerializers
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
or particular ones:
|
||||||
|
|
||||||
|
```js
|
||||||
|
var log = bunyan.createLogger({
|
||||||
|
name: 'myapp',
|
||||||
|
serializers: {err: bunyan.stdSerializers.err}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
Standard serializers are:
|
||||||
|
|
||||||
|
| Field | Description |
|
||||||
|
| ----- | ----------- |
|
||||||
|
| err | Used for serializing JavaScript error objects, including traversing an error's cause chain for error objects with a `.cause()` -- e.g. as from [verror](https://github.com/davepacheco/node-verror). |
|
||||||
|
| req | Common fields from a node.js HTTP request object. |
|
||||||
|
| res | Common fields from a node.js HTTP response object. |
|
||||||
|
|
||||||
|
Note that the `req` and `res` serializers intentionally do not include the
|
||||||
|
request/response *body*, as that can be prohibitively large. If helpful, the
|
||||||
|
[restify framework's audit logger plugin](https://github.com/restify/node-restify/blob/ac13902ad9716dcb20aaa62295403983075b1841/lib/plugins/audit.js#L38-L87)
|
||||||
|
has its own req/res serializers that include more information (optionally
|
||||||
|
including the body).
|
||||||
|
|
||||||
|
|
||||||
## src
|
## src
|
||||||
|
|
||||||
The **source file, line and function of the log call site** can be added to
|
The **source file, line and function of the log call site** can be added to
|
||||||
|
|
Loading…
Reference in a new issue