95 lines
4.6 KiB
Markdown
95 lines
4.6 KiB
Markdown
# UCommandIt JSON Logger
|
|
|
|
### json logger based on [pino](getpino.io).
|
|
|
|
## How to by Example
|
|
|
|
see [example](./example/example.js) for explanation of options and use in a es6 class allowing logging in any method of the class
|
|
|
|
```javascript
|
|
// pretty: {translateTime:true, colorize:true, levelFirst:true } // options for pino pretty printer
|
|
// env:'', // 'dev' or 'pro' -- can be use to set/override UCI_ENV environment variable
|
|
// enForce: false, // only used with .env. if true will override UCI_ENV if it is set, otherwise no
|
|
// level:'info', // info is default level, set level to lowest visible
|
|
// clear: false, // true for log files will clear the current log file on restart
|
|
// logFileName:'test', // if not supplied log filename will be generated from timestamp
|
|
// below properties are optional and are passed to child logger instance and will be part of json log entry
|
|
// libraryName: 'UCI', // will be logged as name: can be used to identify logs of related packages, can be set via UCI_LOG_NAME env variable
|
|
appName:'uci-example-logger', //will be used for logging directory name if supplied and will be logged as well
|
|
package: '@uci/logger', // name of package with scope per package.json
|
|
// repo: // will use scope-name from package prop if not supplied
|
|
id: opts.id, // can pass a unique if for easy later search/filtering
|
|
// file: 'example/example.js', // path (to repo root) of actual file running this logger, default is ./src/<package without scope>.js
|
|
class: 'LogTest', // The class that created this logger if any
|
|
// one can pass through additional props to log for every log
|
|
// should not use any keys above or
|
|
// level,time,msg,pid,hostname
|
|
// logPath,instanceCreatedHR,instanceCreated as keys will be merged
|
|
// NOTE: more props can be added at run time by passing an object of props
|
|
additional: {anotherprop:'test'} // should do not use any keys above or 'level,logPath,package,instanceCreatedHR,instanceCreated' as keys will be merged
|
|
```
|
|
|
|
to run the example clone repo and then `npm install` from root
|
|
|
|
then
|
|
|
|
`npm run [script]`
|
|
|
|
available scripts for example file
|
|
|
|
"dev": "UCI_ENV=dev ./node_modules/.bin/nodemon -r esm example/example",
|
|
"dev:verbose": "UCI_LOG_PRETTY='verbose' npm run dev",
|
|
"dev:terse": "UCI_LOG_PRETTY='terse' npm run dev",
|
|
"dev:filter:line": "UCI_LOG_PRETTY='{\"filter\":[\"line\"]}' npm run dev",
|
|
"dev:include": "UCI_LOG_PRETTY='{\"include\":\"package,appName\"}' npm run dev",
|
|
"dev:trace": "UCI_LOG_LEVEL=trace npm run dev",
|
|
"dev:warn": "UCI_LOG_LEVEL=warn npm run dev",
|
|
"dev:info:only": "UCI_LOG_SEARCH='level==`30`' npm run dev",
|
|
"dev:fatal:only": "UCI_LOG_SEARCH='level==`60`' npm run dev",
|
|
"dev:json": "UCI_LOG_LEVEL=trace UCI_LOG_JSON=true npm run dev",
|
|
"dev:colada": "npm run dev:json | ./node_modules/.bin/pino-colada ",
|
|
"pro": "UCI_ENV='pro' node -r esm example/example",
|
|
"pro:path": "UCI_LOG_PATH=./example/example.log npm run pro"
|
|
|
|
## Environment Variables
|
|
|
|
- `UCI_ENV='dev'|'pro'|'node'`, `dev` outputs to console, `pro` outputs to file, `node` will follow whatever `NODE_ENV` is set to.
|
|
- `UCI_LOG_PATH=<some file path>` force logging to go to some particular file, also setable via options, see above
|
|
- `UCI_LOG_JSON=true` will not pretty output to console but rather as raw json. Useful for piping to a json log processor such as pino-colada
|
|
- `UCI_LOG_LEVEL='trace'|'debug'|'info'|'warn'|'error'|fatal'` `warn` is default, can set at runtime with `.lvlset(level)`
|
|
- `UCI_LOG_PRETTY`={} the pretty option for pino pretty, also setable via options, see above
|
|
- `UCI_LOG_SEARCH='key == `\``value`\``'` will filter pretty/dev logs. _note:_ ALL search values regardless of type MUST be escaped with ``
|
|
|
|
## Usage
|
|
|
|
standalone (not in a class constructor as in example)
|
|
lilke this.
|
|
|
|
import logger from '../src/logger'
|
|
opts = {} // see above
|
|
let log = logger(opts)
|
|
|
|
once you have created a Logger as a `global` in your module you can log per http://getpino.io/#/docs/api?id=logger
|
|
|
|
like so
|
|
```javascript
|
|
log.trace('this is a trace level logged message')
|
|
log.debug('this is a debug level logged message')
|
|
log.info({runtimeprop:'somevalue', msg:'this is a info level logged message'})
|
|
log.warn('this is a warn level logged message')
|
|
log.error('this is a error level logged message')
|
|
log.fatal('this is a fatal level logged message')
|
|
```
|
|
|
|
|
|
you can change visible levels on the fly http://getpino.io/#/docs/api?id=level
|
|
|
|
like so
|
|
|
|
`log.level('debug')` or in the options, see above
|
|
|
|
|
|
## More Help
|
|
|
|
this package/model being a simple extension of the pino json logger check their documentation http://getpino.io/#/
|