jsout

jsout

A DevOps friendly, small, and simple logger for Typescript/Javascript projects.

Structured Logs 🔒

• Supports both human-readable CLI output and JSON output for log aggregation into services like sumologic, New Relic, DataDog, etc.

Defensive & Devops Friendly 🛡

• Logs are enabled in production mode by default
• Transport should be handled outside of the process via STDOUT and STDERR, not inside (this is the job of DevOps)
• Configuration should also be handled outside of the code, not inside (also the job of DevOps)
• Doesn't allow for fancy configurations that are easy to get wrong. Logging should be easy and simple.

Simple & Easy to Use 😃

• Automatic Error serialization
• Out-of-the-box Typescript support
• Only 2 tiny dependencies, written in clean Typescript
• Nice human readable output

Flexible & Powerful 💪

• Easily set configuration using simple CLI overrides
• Simple and well-defined enough to build custom tooling around, such as custom error handling and logging pipelines.

Installation

npm i jsout

Example Usage

import {logger} from 'jsout';

logger.info('test message');
logger.fatal('oops!', new Error(), {foo: 'bar'})
logger.error('', new Error('test')); //infers "test" as message

## Express.js HTTP Request Logger

See [jsout-express](https://github.com/mhweiner/jsout-express)

Configuration

Configuration is set through the CLI environment variables (aka process.env variables in node.js). For example, here is a recommended setup for local development:

LOG=debug LOG_FORMAT=human LOG_VERBOSITY=terse node /path/to/yourApp.js

process.env.LOG

Sets the log level. Any logs lower than this log level are ignored.

Possible values: "trace", "debug", "info", "warn", "error", "fatal"

Default: "info" (recommended for production)

process.env.LOG_FORMAT

Set the format for the output to either be human-readable (great for local development in the console), or JSON formatted (great for data aggregation on a server).

Possible values: "human", "json"

Default: "json" (recommended for production)

process.env.LOG_VERBOSITY

If verbose, extra metadata is appended to log.context. Example:

{
  "date": "2021-12-19T06:17:38.147Z",
  "pid": 71971,
  "ppid": 71970,
  "nodeVersion": "v16.13.0"
}

Possible values: "terse", "verbose"

Default: "verbose" (recommended for production)

API

For all of the following, please note:

• error should be an actual Error object with stack traces. This is not enforced.
• context should by any information not necessarily directly related to the error, ie. server request information, app component, configurations, etc. This is where the verbose metadata is appended (this will override anything in the context object).
• data any object that might be useful to debug the error, or any pertinant information relating to the log message

logger.trace(message?: string, data?: any, context?: any)

Emits a log to stdout with a level of TRACE (10)

logger.debug(message?: string, data?: any, context?: any)

Emits a log to stdout with a level of DEBUG (20)

logger.info(message?: string, data?: any, context?: any)

Emits a log to stdout with a level of INFO (30)

logger.warn(message?: string, error?: any, data?: any, context?: any)

Emits a log to stderr with a level of WARN (40)

logger.error(message?: string, error?: any, data?: any, context?: any)

Emits a log to stderr with a level of ERROR (50)

logger.fatal(message?: string, error?: any, data?: any, context?: any)

Emits a log to stderr with a level of FATAL (60)

Contribution

Please contribute to this project! Issue a PR against master and request review.

• Please test your work thoroughly.
• Make sure all tests pass with appropriate coverage.

How to build locally

npm i

Running tests

npm test