1 | # Ignition
|
2 | [![Build Status](https://travis-ci.org/TryGhost/Ignition.svg?branch=master)](https://travis-ci.org/TryGhost/Ignition)
|
3 |
|
4 | Basic configuration and tooling shared across applications
|
5 |
|
6 |
|
7 | ## Logging
|
8 | ```
|
9 | var logging = require('ghost-ignition').logging({
|
10 | domain: 'example.com,
|
11 | env: 'production',
|
12 | mode: 'long',
|
13 | level: 'info',
|
14 | transports: ['file'],
|
15 | rotation: {enabled: true, period: '1d', count: 10},
|
16 | path: '/var/log'
|
17 | });
|
18 |
|
19 | mode : long|short (default is `short`) - defines the output volume (helpful when logging requests)
|
20 | level : info|error|debug (default is `info`)
|
21 | transports : stdout|file|stderr (default is `['stdout']`)
|
22 | path : is used when file transport is enabled (default is `process.cwd()`)
|
23 |
|
24 | logging.info({req: req, res: res});
|
25 | logging.info('Info');
|
26 | logging.error(new Error());
|
27 | logging.warn('this', 'is', 'a', 'warning');
|
28 | logging.debug('this is a debug mode');
|
29 | ```
|
30 |
|
31 | ### env parameter
|
32 |
|
33 | Each config option, can be passed as an environment variable:
|
34 | E.g. `LEVEL=error` or `MODE=long`.
|
35 |
|
36 | There is also a special env var
|
37 |
|
38 | `LOIN=true`
|
39 |
|
40 | Which sets the LEVEL to info and the MODE to long, for maximum output.
|
41 |
|
42 | ### Logging into file
|
43 | We log JSON format into file. This is very easy to forward and easy to interprete.
|
44 | By default we create two log files:
|
45 | - errors log entries: contains only errors
|
46 | - all log entries: contains everything
|
47 |
|
48 | You can easily make the log files readable by calling:
|
49 | `cat your.log | bunyan`
|
50 |
|
51 | ### Loggly Stream
|
52 | You can send your logs to loggly by configuring the logger like this:
|
53 |
|
54 | ```
|
55 | var logging = require('ghost-ignition').logging({
|
56 | domain: 'example.com,
|
57 | env: 'production',
|
58 | mode: 'long',
|
59 | level: 'info',
|
60 | transports: ['file', 'loggly'],
|
61 | rotation: {enabled: true, period: '1d', count: 10},
|
62 | path: '/var/log',
|
63 | loggly: {
|
64 | token: 'your-token',
|
65 | subdomain: 'your-subdomain',
|
66 | match: 'regex as string to match specific properties only certain log entries'
|
67 | }
|
68 | });
|
69 |
|
70 | Example for match:
|
71 | match: 'level:critical'
|
72 | match: 'statusCode:500|statusCode:403'
|
73 | ```
|
74 |
|
75 | NOTE: The `loggly` stream will only send error logs. Furthermore, you can only match a string in the error object.
|
76 |
|
77 | ### Utils
|
78 |
|
79 | ```
|
80 | var errors = require('ghost-ignition');
|
81 |
|
82 | // you can pass any error and ignition will tell you if this is a custom ignition error
|
83 | errors.utils.isIgnitionError(err);
|
84 |
|
85 | // serialize an error to a specific format
|
86 | errors.utils.serialize(err, {format: 'jsonapi|oauth'});
|
87 |
|
88 | // deserialize specific format to error instance
|
89 | errors.utils.deserialize(err);
|
90 | ```
|
91 |
|
92 | ## Development
|
93 |
|
94 | ### Publish
|
95 |
|
96 | - `yarn ship`
|
97 |
|
98 | # Copyright & License
|
99 |
|
100 | Copyright (c) 2016-2019 Ghost Foundation - Released under the [MIT license](LICENSE).
|