Logger

Logging

To use Ogma, first you’ll need to instantiate an instance of the Ogma class. You can pass in options to override the default if you would like as well. (options defined below). Ogma has eight different logging levels:

• OFF: No logs are displayed through Ogma. console.log will still work
• SILLY: For when you just want to type fun stuff but don’t really want people to see it (usually). Colored with Magenta
• VERBOSE: great for long strings of errors and things going on. Colored with Green
• DEBUG: Just like the name implies, debugging! Colored with Blue
• INFO: For normal logging, nothing special here. Colored with Cyan.
• WARN: For errors about things that may be a problem. Colored with Yellow.
• ERROR: For errors about things that are a problem. Colored with Red.
• FATAL: Yeah, you should call someone at 3AM if this log ever shows up. Colored with Red.

When discussing log levels, Ogma will print at the level provided and anything under the level as shown above, so if ‘SILLY’ is set, all logs will be shown; if ‘WARN’ is set as the logLevel, only ‘WARN’, ‘ERROR’, and ‘FATAL’ logs will be shown. The only exclusion to this rule is ‘OFF’, which prints nothing through Ogma.

When colors are enabled, the color mentioned above will be the color the level string is printed in.

printError

There is also the printError method on the Ogma class that takes care of printing the error’s name under the ERROR level, the message under the WARN level, and the stack trace under the VERBOSE level.

Adding Context and Application Name

If for tracing purposes you’d like to add a context to the log, or an application name, you can pass the context to the method related to the logLevel (such as ogma.debug('debug message, { context: SomeClass.name, application: 'NestJS' }) and Ogma will print

[2019-12-19T23:01:23.900Z] [DEBUG] [hostname] [NestJS] 34760 [SomeClass] debug message

When application and context are both present, Ogma will print your logs in a form as follows

[ISOString Date] [logLevel] [hostname] [Application] PID [Context] message

Examples can be seen below. The JSON structure follows the same form with log level and message being the last two properties.

Printing Multiple Values

To get ogma to automatically print multiple values for you, rather than having to call ogma.log on each value, you can pass an array of value and the { each: true } option to ogma. This will cause ogma to print each value of the array as if you had called ogma.log on each one.

This option is also available globally, so you can set it on the instantiation of your ogma instance and no worry about it on each call.

Ogma Options

Using Files instead of a console

If you want to use a file to hold your logs instead of a console/terminal/bash you can pass in a stream of your own to the options like so:

import { createWriteStream } from 'fs';
import { Ogma } from '@ogma/logger';

const fileWriter = new Ogma({
  stream: createWriteStream('./server.log')
  }
});

fileWriter.log('Logging to File');

JSON Logging

If the json option is passed as true then regardless of color Ogma will print your message along with system information in a single line JSON object (i.e. no newline characters). View the sample below to get a better idea of Ogma’s output. Ogma will add an ool property to the JSON logs or Ogma Original Level. This is in case there is a custom levelMap passed and allows the CLI to still transform the output back into Ogma’s standard format.

Applying color to Text

As of version 2, it is suggested to use the separate @ogma/styler package. This package is what Ogma uses under the hood to do the basic coloring, and will provide a cleaner and more verbose API.

Using the non-JSON mode, color is attempted to be applied by default. This is determined by checking the current environment (if there is a global process variable) and if there is, what stdout.getColorDepth() returns. If a custom stream is passed instead, a getColorDepth method can be added to the stream object which should return a 1, 4, 8, or 24. If no getColorDepth() is present, but the color option is true, Ogma will set the method to return 4 for you. If you want to disable colors completely, you can either set color to be false or you can set the NO_COLOR environment variable.

Using a Mixin

There may be times, like with OpenTelemetry or with adding a correlation id, that you need to add dynamic values to each log. Rather than making a new wrapper around the Ogma instance, Ogma provides an optional mixin property that can be used to add extra data to each log without being in verbose mode. This property is a function, that takes in the current log level and the Ogma instance, and should return an object of any shape.

Example of what the logs look like

I said the logs were beautiful, and to me they absolutely are. Each log is matched with a timestamp in ISO format, the log level, a pipe character, and then the message, for easier searching if needed. If a JSON is passed to Ogma, a new line will separate the JSON and the original log line, but the timestamp and level will not be duplicated. Ogma also will print '[Function]' if a function is found or '[Circular]' is a circular reference is found.

# ogma.log('hello')
[2019-12-11T22:54:58.462Z] [INFO]  [hostname] 34760 hello

# ogma.log({a: () => 'hello', b: {c: 'nested'}, d: this});
[2019-12-11T22:56:02.502Z] [INFO]  [hostname] 34760
{
  "a": "[Function]",
  "b": {
    "c": "nested"
  },
  "d": {
    "global": "[Circular]",
    "clearInterval": "[Function]",
    "clearTimeout": "[Function]",
    "setInterval": "[Function]",
    "setTimeout": "[Function]",
    "queueMicrotask": "[Function]",
    "clearImmediate": "[Function]",
    "setImmediate": "[Function]",
    "__extends": "[Function]",
    "__assign": "[Function]",
    "__rest": "[Function]",
    "__decorate": "[Function]",
    "__param": "[Function]",
    "__metadata": "[Function]",
    "__awaiter": "[Function]",
    "__generator": "[Function]",
    "__exportStar": "[Function]",
    "__values": "[Function]",
    "__read": "[Function]",
    "__spread": "[Function]",
    "__spreadArrays": "[Function]",
    "__await": "[Function]",
    "__asyncGenerator": "[Function]",
    "__asyncDelegator": "[Function]",
    "__asyncValues": "[Function]",
    "__makeTemplateObject": "[Function]",
    "__importStar": "[Function]",
    "__importDefault": "[Function]"
  }
}

Standard String Logging

JSON Logging