|
| 1 | +# @imqueue/async-logger |
| 2 | + |
| 3 | +Configurable async logger over winston for @imqueue services. |
| 4 | + |
| 5 | +## Install |
| 6 | + |
| 7 | +~~~bash |
| 8 | +npm i --save @imqueue/async-logger |
| 9 | +~~~ |
| 10 | + |
| 11 | +## Usage |
| 12 | + |
| 13 | +There are two actual ways of using async logger. |
| 14 | + |
| 15 | +1. Rely on singleton instance produced by this library, which is configured by |
| 16 | + environment variables (see Configuration section below) |
| 17 | + |
| 18 | + In this case as simple as |
| 19 | + ~~~typescript |
| 20 | + import logger from '@imqueue/async-async-logger'; |
| 21 | + |
| 22 | + serviceOptions.logger = logger; |
| 23 | + ~~~ |
| 24 | + |
| 25 | +2. Instantiate and configure async logger programmatically: |
| 26 | + ~~~typescript |
| 27 | + import { Logger } from '@imqueue/async-async-logger'; |
| 28 | + |
| 29 | + const { name, version } = require('./package.json'); |
| 30 | + |
| 31 | + const logger = new Logger({ |
| 32 | + transports: [{ |
| 33 | + type: 'http', |
| 34 | + options: { |
| 35 | + ssl: true, |
| 36 | + port: 443, |
| 37 | + path: '/v1/input/<YOUR_API_KEY>', |
| 38 | + host: 'http-intake.logs.datadoghq.com', |
| 39 | + headers: { |
| 40 | + 'Content-Type': 'application/json', |
| 41 | + }, |
| 42 | + }, |
| 43 | + enabled: true, |
| 44 | + }], |
| 45 | + metadata: { |
| 46 | + ddsource: `${ name } ${ version }`, |
| 47 | + ddtags: 'env: dev', |
| 48 | + hostname: 'localhost' |
| 49 | + }, |
| 50 | + }); |
| 51 | + |
| 52 | + serviceOptions.logger = logger; |
| 53 | + ~~~ |
| 54 | + |
| 55 | +## Configuration |
| 56 | + |
| 57 | +Logger can be configured via environment variables. It can be easily integrated |
| 58 | +with any remote services. Here we will example configuration based on assumption |
| 59 | +to connect with Datadog remote service. |
| 60 | + |
| 61 | +So, basically there are two basic configuration options available: |
| 62 | + |
| 63 | +~~~bash |
| 64 | +export LOGGER_TRANSPORTS='[]' |
| 65 | +export LOGGER_METADATA='{}' |
| 66 | +~~~ |
| 67 | + |
| 68 | +Both of them are simply JSON strings referring to replicate corresponding |
| 69 | +winston logger settings. Both of them can accept string tags `%name`, `%version` |
| 70 | +for dynamic setting of these values from a current service package, if needed. |
| 71 | + |
| 72 | +1. To configure HTTP transport follow to pass such object to `LOGGER_TRANSPORTS` |
| 73 | +array: |
| 74 | + |
| 75 | +~~~json |
| 76 | +{ |
| 77 | + "type": string, |
| 78 | + "options": { |
| 79 | + "ssl": boolean, |
| 80 | + "port": number, |
| 81 | + "path": string, |
| 82 | + "host": string, |
| 83 | + "headers": object |
| 84 | + }, |
| 85 | + "enabled": boolean |
| 86 | +} |
| 87 | +~~~ |
| 88 | + |
| 89 | +2. To configure File transport |
| 90 | + |
| 91 | +~~~json |
| 92 | +{ |
| 93 | + "type": string, |
| 94 | + "options": { |
| 95 | + "filename": string, |
| 96 | + "dirname": string, |
| 97 | + "options": object, |
| 98 | + "maxsize": number, |
| 99 | + "zippedArchive": boolean, |
| 100 | + "maxFiles": number, |
| 101 | + "eol": string, |
| 102 | + "tailable": boolean |
| 103 | + }, |
| 104 | + "enabled": boolean |
| 105 | +} |
| 106 | +~~~ |
| 107 | + |
| 108 | +EXAMPLE FOR DATADOG: |
| 109 | + |
| 110 | +~~~bash |
| 111 | +export LOGGER_TRANSPORTS='[{"type":"http","options":{"ssl":true,"port":443,"path":"/v1/input/[DATADOG_API_KEY]","host":"http-intake.logs.datadoghq.com","headers":{"Content-Type":"application/json"}}, "enabled": true }]' |
| 112 | +~~~ |
| 113 | + |
| 114 | +where DATADOG_API_KEY should be replaced with an actual API key. |
| 115 | + |
| 116 | +3. To configure metadata consider the following `LOGGER_METADATA` object: |
| 117 | + |
| 118 | +~~~json |
| 119 | +{ |
| 120 | + "ddsource": string, |
| 121 | + "ddtags": string, |
| 122 | + "hostname": string |
| 123 | +} |
| 124 | +~~~ |
| 125 | + |
| 126 | +EXAMPLE FOR DATADOG: |
| 127 | + |
| 128 | +~~~bash |
| 129 | +export LOGGER_METADATA='{"ddsource":"%name %version","ddtags":"env: dev","hostname":"localhost"}' |
| 130 | +~~~ |
| 131 | + |
| 132 | +### Lets See It Human-Readable: |
| 133 | + |
| 134 | +~~~bash |
| 135 | +# example of transports config |
| 136 | +export LOGGER_TRANSPORTS='[{ |
| 137 | + "type": "http", |
| 138 | + "options": { |
| 139 | + "ssl": true, |
| 140 | + "port": 443, |
| 141 | + "path": "/v1/input/<YOUR_API_KEY>", |
| 142 | + "host": "http-intake.logs.datadoghq.com", |
| 143 | + "headers": { |
| 144 | + "Content-Type": "application/json" |
| 145 | + } |
| 146 | + }, |
| 147 | + "enabled": true |
| 148 | +}, { |
| 149 | + "type": "file", |
| 150 | + "options": { |
| 151 | + "filename": "logs.log", |
| 152 | + "dirname": "/home/usr/logs", |
| 153 | + "options": object, |
| 154 | + "zippedArchive": false, |
| 155 | + } |
| 156 | + "enabled": true |
| 157 | +}]' |
| 158 | +# example of metadata for datadog |
| 159 | +export LOGGER_METADATA='{ |
| 160 | + "ddsource": "%name %version", |
| 161 | + "ddtags": "env: dev", |
| 162 | + "hostname": "localhost" |
| 163 | +}'; |
| 164 | +~~~ |
| 165 | + |
| 166 | +## Contributing |
| 167 | + |
| 168 | +Any contributions are greatly appreciated. Feel free to fork, propose PRs, open |
| 169 | +issues, do whatever you think may be helpful to this project. PRs which passes |
| 170 | +all tests and do not brake tslint rules are first-class candidates to be |
| 171 | +accepted! |
| 172 | + |
| 173 | +## License |
| 174 | + |
| 175 | +[ISC](https://github.com/imqueue/pg-pubsub/blob/master/LICENSE) |
| 176 | + |
| 177 | +Happy Coding! |
0 commit comments