TheThing/node-bunyan-lite
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Wiki Activity

docs: update notes on log levels

Browse source 
Hopefully helps clarify questions like #340 and #305.
This commit is contained in:
Trent Mick 2016-01-31 17:35:43 -08:00
parent cc7606a60d
commit b0b9bed17b
1 changed files with 27 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
README.md
View file

@ -350,7 +350,7 @@ in production.**
# Levels
The log levels in bunyan are as follows. The level descriptions are best
practice *opinions*.
practice *opinions* of the author.
- "fatal" (60): The service/app is going to stop or become unusable now.
An operator should definitely look into this soon.
@ -363,17 +363,19 @@ practice *opinions*.
- "trace" (10): Logging from external libraries used by your app or *very*
detailed application logging.
Suggestions: Use "debug" sparingly. Information that will be useful to debug
errors *post mortem* should usually be included in "info" messages if it's
generally relevant or else with the corresponding "error" event. Don't rely
on spewing mostly irrelevant debug messages all the time and sifting through
them when an error occurs.
Setting a logger instance (or one of its streams) to a particular level implies
that all log records *at that level and above* are logged. E.g. a logger set to
level "info" will log records at level info and above (warn, error, fatal).
Integers are used for the actual level values (10 for "trace", ..., 60 for
"fatal") and constants are defined for the (bunyan.TRACE ... bunyan.DEBUG).
The lowercase level names are aliases supported in the API.
While using log level *names* is preferred, the actual level values are integers
internally (10 for "trace", ..., 60 for "fatal"). Constants are defined for
the levels: `bunyan.TRACE` ... `bunyan.FATAL`. The lowercase level names are
aliases supported in the API, e.g. `log.level("info")`. There is one exception:
DTrace integration uses the level names. The fired DTrace probes are named
'bunyan-$levelName'.
Here is the API for changing levels in an existing logger:
Here is the API for querying and changing levels on an existing logger.
Recall that a logger instance has an array of output "streams":
```js
log.level() -> INFO // gets current level (lowest level of all streams)
@ -390,6 +392,21 @@ log.levels(0, "info") // can use "info" et al aliases
log.levels("foo", WARN) // set stream named "foo" to WARN
```
## Level suggestions
Trent's biased suggestions for server apps: Use "debug" sparingly. Information
that will be useful to debug errors *post mortem* should usually be included in
"info" messages if it's generally relevant or else with the corresponding
"error" event. Don't rely on spewing mostly irrelevant debug messages all the
time and sifting through them when an error occurs.
Trent's biased suggestions for node.js libraries: IMHO, libraries should only
ever log at `trace`-level. Fine control over log output should be up to the
app using a library. Having a library that spews log output at higher levels
gets in the way of the a clear story in the *app* logs.
# Log Record Fields
This section will describe *rules* for the Bunyan log format: field names,