This package has been deprecated

Author message:

Ogma has been merged into the @ogma/ namepsace. Please use @ogma/logger for the same functionality

ogma
TypeScript icon, indicating that this package has built-in type declarations

2.1.1 • Public • Published

Quality Gate Status Commitizen friendly Actions Status Version Coffee

Ogma

Beautifully simple logging.

Why

Really just because I wanted to. Feel free to use whatever logger you want, Winston, pino, bunyan, or anything else. This is just how I wanted my logs to look.

Okay, but why Ogma?

Name of the Celtic god of Wisdom and Eloquence. As I think these logs both look pretty and tell good information, I figured I would go with the name

Use

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 show; if 'WARN' is set as the logLevel, only 'WARN', 'ERROR', and 'FATAL' logs will be shown. The only exclusion to this rule if 'OFF', which prints nothing through Ogma.

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

There is also the printError method on the Ogma class thta 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.

Note: INFO is also aliased as LOG so ogma.log() works just like ogma.info(), but the log level will stay as "INFO" in both cases. The same goes for "VERBOSE" and "FINE" with "FINE" being the log level printed (for the sake of being concise). Lastly, 'ALL' can be used for all logs. This is the same as setting logLevel to 'SILLY'.

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, SomeClass.name, 'NestJS') and Ogma will print

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

Note: If colors are enabled, application will print in Yellow and context will print in Cyan.

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

[ISOString Date] [Application] PID [Context] [LogLevel]| message

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

Ogma Options

name type use
logLevel one of the above log levels (default: INFO) for determining this instance of Ogma's log level
color boolean (default: true) determine if color should attempt to be used. NOTE: Color will not be used if the current terminal does not support it
stream NodeJS.WriteStream OR NodeJS.WritableStream (default: process.stdout) the output mechanism used to know how to write logs
json boolean (default: false) print the logs in a JSON format
context string optional a context for the Ogma class to work with.
application string optional an application name for Ogma to print

Using Files instead of a console

Note: Ogma will try to use colors if they are available, but will otherwise ignore the color option if stream.hasColors() return false.

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';
 
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.

Note: if you log an object, the message property will be removed and the object will be a part of the raw JSON format. If you want the object to show up under the message property, you can add JSON.stringify(obj).replace(/\"/g, ''). Just be aware that circular objects will still be problematic unless you add a circular replacer.

Applying color to Text

No console logging package is complete without color, and because of that Ogma exports some utility methods for wrapping text in color, so long as your terminal of choice supports 3/4-bit color. You can find the the color reference in the screenshot below.

To make use of the utility functions you'll need to import the color method and pass in your string to the desired color like so:

import { color } from 'ogma';
 
color.blue('This will be blue');
// returns '\u001b[34mThis will be blue\u001b[0m'

This will wrap the string "This will be blue" in the expected escape sequence and color value as well as reset the color afterwards so no other strings are affected.

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] 34760 [INFO] | hello
 
# ogma.log({a: () => 'hello', b: {c: 'nested'}, d: this}); 
[2019-12-11T22:56:02.502Z] 34760 [INFO] |
{
  "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]"
  }
}

Example from Command Line

Command Line Function

Ogma comes with a built in command line function to rehydrate your json formatted logs back into the human readable format. The command takes one to two arguments, a log file relative to wear the command is run from, and an optional flag to force the cli to print out with color. Find the table below to learn more about the arguments.

argument required default description
file yes none The log file to be "hydrated". This file should contain newline separated Ogma formatted JSON logs.
--color no terminal's TTY argument you can pass --color or --color=true to force colors to be used. --color=false will force the command to not print the logs back out in color. Depending on the terminal you are using, colors may not be used by default.

The arguments can be passed in any order for ease of use.

Example

An example of the command's usage could be like so:

ogma production.log --color

or if you have a TTY enabled command prompt

ogma production.log

As this prints out to process.stdout it is possible to pipe this output to another file using the > operator. Like so:

ogma production.log > production.hydrated.log

Benchmarks

While Ogma may not boast as being as fast as pino, it is still quick with what it does. You can check out some of the benchmarks here.

Package Sidebar

Install

npm i ogma

Weekly Downloads

11

Version

2.1.1

License

MIT

Unpacked Size

60.7 kB

Total Files

54

Last publish

Collaborators

  • jmcdo29