Skip to content
This repository has been archived by the owner on May 19, 2022. It is now read-only.
/ ratlog.js Public archive

πŸ€ Ratlog JavaScript library - Application Logging for Rats, Humans and Machines

License

Notifications You must be signed in to change notification settings

ratlog/ratlog.js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

83 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ€ Ratlog JavaScript library

Application Logging for Rats, Humans and Machines

Status: Deprecated. These days I highly recommend using modern observability tooling such as OpenTelemetry.

Build Status npm GitHub last commit GitHub issues

Ratlog.js is a JavaScript logging library that supports the Ratlog logging format.

The output is opinionated to be readable by rats, humans and machines.

The provided API is designed to be as simple to use as possible while providing you with all Ratlog semantics. Each log line can consist of a message, tags and fields which provides you enough context to quickly understand what's happening in your system.

For an introduction, see this article. To learn more about the design and ideas behind the Ratlog spec, checkout ratlog-spec.

The Ratlog JavaScript provides Ratlog semantics and the Ratlog format but they can be used independent from each other:

If you only want to make use of the API semantics, you can create a logger using ratlog.logger() and use JSON or any other format as output. This way you can combine Ratlog's logging semantics with your logging framework or service of choice.

For more have a look at the API Documentation.

Getting started

Install the ratlog NPM package:

npm i ratlog

Starting logging:

const ratlog = require('ratlog')
const log = ratlog(process.stdout)

log('hello world')
// => hello world

// Add fields
log('counting', { count: 1 })
// => counting | count: 1

// Add fields and a tag
log('counting', { count: -1 }, 'negative')
// => [negative] counting | count: -1

// Create another logger bound to a tag
const warn = log.tag('warning')

warn('disk space low')
// => [warning] disk space low

// Combine and nest tags any way you like
const critical = warn.tag('critical')

critical('shutting down all servers')
// => [warning|critical] shutting down all servers


// Create a mock logger while testing
const logHandler = jest.fn()
const testLog = ratlog(logHandler)
testLog('hi', 'info')
expect(logHandler).toBeCalledWith('[info] hi\n')

There are more examples to learn how you can use tags to provide context in your logs about different components of your system.


Thanks to @wmhilton for pointing this out:

You can color tags by combining Ratlog with chalk:

const warn = log.tag(chalk.red('warning'))
log('Normal log')
warn('Warning log')

colored log tags

Requirements

Node >= 8.0.0

Development and Contributing

Feel free to open an issue to ask questions or give feedback and make suggestions.

To contribute code, run npm i to setup your dev environment and before submitting a Pull Request, make sure npm t is passing.

Releasing

If you have access to npm and want to release a version:

  • Update package.json and commit
  • git tag and git push --tags
  • Run npm publish locally

License

MIT