# Cologne
-![https://david-dm.org/rbdr/cologne.svg][dependencies-shield]
-![https://circleci.com/gh/rbdr/cologne.svg?style=shield][circle-ci-shield]
-
-Cologne is a logger multiplexer that works mainly with a JSON format. It
-can be instantiated with several loggers, or they can be changed after
+Cologne is a logger multiplexer that uses a JSON log format inspired in gelf.
+It can be instantiated with several loggers, or they can be changed after
the fact.
## Usage
-Install from npm or add to your package.json:
+Install from npm
```
-$ npm install cologne
+$ npm install --save cologne
```
-Create an instance:
+Create an instance
```javascript
-require('cologne');
+const { Cologne, Loggers, Formatters } = require('cologne');
-let co = new Cologne({
- from: "Special Worker Logger",
+const co = new Cologne({
+ from: 'Special Worker Logger',
loggers: [
- new Cologne.Logger.Console({
- formatter: new Cologne.Formatter.Token({
+ new Loggers.Console({
+ formatter: new Formatters.Token({
formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
})
})
This example would create a cologne instance with a console logger that
uses a Token formatter. (More on loggers and formatters below.);
-## Do I need anything special?
-
-Node 4.0+
-
## Quick API Reference
* **addLogger(logger)**: Adds a logger to the cologne instance.
Cologne loggers are any object that responds to the `#log()` method.
This methoud should be able to receive any number of arguments and
log them independently. Similar to how you can send multiple arguments
-to the JS console.
+to the browser console.
-`#log()` will receive any number of `Cologne Log Objects`. To see what
-this format includes, check further below.
+`#log()` will receive any number of `Cologne Log Objects`. For a detailed
+reference of this format, see further below.
-We include two loggers out of the box:
+Cologne includes two loggers out of the box:
-* `Cologne.Logger.Console` logs to the JS console
-* `Cologne.Logger.File` appends to a file
+* `Loggers.Console` logs to the JS console
+* `Loggers.File` appends to a file
-### Cologne.Logger.Console
+### Loggers.Console
-This logger communicates the Javascript console. It uses the log level
+This logger communicates with the Javascript console. It uses the log level
to trigger the appropriate method, so `error` logs would go to stderr
as expected when calling `console.error`.
This logger can be sent a `formatter`, which is an object that responds
-to the `#format()` method: it should get a cologne log object and respond
+to the `#format()` method: it should receive a cologne log object and respond
with a string.
```javascript
-new Cologne.Logger.Console({
- formatter : new Cologne.Formatter.Token({
+new Loggers.Console({
+ formatter : new Formatters.Token({
formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
})
});
```
-### Cologne.Logger.File
+### Loggers.File
This logger opens a writable stream to a file, to which it will append
everything. Like the Console logger it supports a `formatter` property
that will respond to the `#format()` method.
-It MUST include a `file` property on initialization, otherwise it won't
-know where to write and you'll get an exception and be sad.
+It MUST include a `file` property on initialization, otherwise it will throw
+an exception.
```javascript
-new Cologne.Logger.File({
+new Loggers.File({
file: '/var/log/server_log.log',
- formatter : new Cologne.Formatter.Token({
- formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
+ formatter : new Formatters.Token({
+ formatString: '[{{_ansi:_level}}{{_timestamp}}{{_ansi:reset}}]{{_from}}: {{message}}'
})
});
```
We're working on a socket logger. It's separate so you don't have to
install the socket dependencies if you don't want to.
-If you need to, you can roll your own. Check info on the interfaces
-below.
-
You can build your own logger easily for any method of transport you find
necessary (e.g. mail, database, twitter, etc). Any object that responds
to `#log()` is a valid logger:
```javascript
// A valid, very minimalistic logger
-let simpleLogger = {
- log : function () {
- for (let logObject of arguments) {
- this._doSomeMagic(logObject);
+const simpleLogger = {
+ log: function(...logs) {
+
+ for (const log of logs) {
+ this._doSomeMagic(logs);
}
},
- _doSomeMagic : function (logObject) {
- console.log(logObject + "... but magical!");
+ _doSomeMagic: function(log) {
+
+ console.log(log + "... but magical!");
}
};
## Formatters
Cologne doesn't need formatters to work, and in fact they're optional in
-the included workers. But if you would like to make your logs prettier,
+the included loggers. But if you would like to make your logs prettier,
then you can use one of the included formatters or roll your own.
Formatters are objects that respond to the `#format()` method. It will
receive a single cologne log object (see fields it includes below), and
-it should return a string. That's all there is to it.
+it should return a string.
We include some formatters so you can get running real quicklike:
-* `Cologne.Formatter.Simple` a simple predefined formatter
-* `Cologne.Formatter.Token` a formatter that lets you define format
+* `Formatters.Simple` a simple predefined formatter
+* `Formatters.Token` a formatter that lets you define format
strings that it will use to build your final log.
-### Cologne.Formatter.Simple
+### Formatters.Simple
This is the lazy formatter, it just outputs the string in the following
format:
* `colorize` <Boolean>: whether or not to add color. False by default.
By default we don't colorize the output, but if you enable the flag this
-formatter will add a bit of color in the level string. Red for bad,
-yellow for warn, blue for info, and white for everything else.
+formatter will add a bit of color in the level string. Red for error, crit,
+alert, and emerg; yellow for warn; blue for info; green for debug; and white
+for everything else.
#### Usage
```javascript
-new Cologne.Formatter.Simple({
+new Formatters.Simple({
colorize: true
});
```
// -> [2016-01-21T05:50:36.505Z][INFO] Server Logger: hello world
```
-### Cologne.Formatter.Token
+### Formatters.Token
The token formatter lets you build strings with simple tokens. When
instantiating, you can specify a `formatString` to interpolate
#### Usage
```javascript
-new Cologne.Formatter.Token({
+new Formatters.Token({
formatString: '[{{_timestamp}}]{{_from}}: {{message}}'
});
```
Here's an example of a logger that surrounds a log with sparkles:
```javascript
-var simpleFormatter = {
- format : function (logObject) {
- return '✨' + logObject.message + '✨';
+const sparkleFormatter = {
+ format: function(logObject) {
+
+ return `✨${logObject.message}✨`;
}
}
-logger.addLogger(new Cologne.Logger.Console({
- formatter: simpleFormatter
+logger.addLogger(new Loggers.Console({
+ formatter: sparkleFormatter
}));
```
## The Cologne Log Format
The cologne log format is a JSON based log format, based on the cobalt
-log format, which is inturn based on Graylog's GELF. However, where GELF
+log format, which is in turn based on Graylog's GELF. However, where GELF
treats all internal fields without a prefix, and all user fields with a
-prefix we do it backwards so it's easier to extend the object with
-metadata from existing objects. Besides, we'll probably write the
-default keys automatically so you shouldn't have to do that extra work.
+prefix, we do it backwards so it's easier to extend the object with
+metadata from existing objects.
You could try to build it on your own, but you can use `#buildLog()`
to build it without logging.
### Fields
-* **\_timestamp** : A timestamp in miliseconds with fractions of a second
- in the floating point area.
+* **\_timestamp** : A bigint timestamp in nanoseconds
* **\_cologneLog** <String> : This is how we know if the log is already
formatted and ready to go. This field is a string containing the
- version of cologne log format it's using. It's `1.0.0` right now.
+ version of cologne log format it's using. It's `2.0.0` right now.
* **\_from**: The sender of the log (Defaults to Generic Cologne Logger)
* **\_level**: The level of the log (Defaults to 6)
* **\_levelString**: The string corresponding to the log level (e.g. 7 ->
* Improve the API for buildLog
* More loggers & formatters (will not be distributed in core cologne)
* Improve tests
-
-[dependencies-shield]: https://david-dm.org/rbdr/cologne.svg
-[circle-ci-shield]: https://circleci.com/gh/rbdr/cologne.svg?style=shield
git.r.bdr.sh / rbdr / cologne / blobdiff