Package Exports

jsout
jsout/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (jsout) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

A Syslog-compatible, small, and simple logger for Typescript/Javascript Node.js projects. Sponsored by Aeroview.

🔒 Structured Logs

Supports both human-readable CLI output and JSON output for log aggregation into services like Sumo Logic, New Relic, Datadog, and Aeroview.

✅ Syslog Compatible

Standardized Syslog log levels and output format make it easy to integrate with existing logging pipelines and 3rd party services.

🛡 Defensive & Devops Friendly

Logs are enabled in production mode by default, avoding the mistake of forgetting to enable logs in production which could be disastrous.
Transport should be handled outside of the process via STDOUT and STDERR
Simple configurations makes it hard to mess up
Minimal dependencies, fast, and reliable TypeScript codebase

😃 Simple & Easy to Use

Automatic Error serialization
Out-of-the-box Typescript support
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 plugins, 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

Plugins

Express Request Logger

Configuration

Configuration is set through environment variables. By default, the logger is set to info level and json format, which is recommended for production.

You can override these settings by setting the following environment variables before running your application.

For example, here are the recommended settings when running your application locally:

LOG=debug LOG_FORMAT=human ts-node /path/to/app.ts

`LOG`

Sets the log level. Log levels are based on the syslog levels. Values can be either the number or the string representation of the log level. Logs with a level less than the specified level will not be emitted.

For example, if the log level is set to info, logs with a level of debug will not be emitted.

Possible values:

2, 3, 4, 5, 6, 7

"crit", "critical" "err", "error", "warning", "warn", "notice", "info", "debug"

Default: "info" (recommended for production)

`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)

Logger API

Log levels are based on the syslog levels:

Level	Severity	Example
0	Emergency	^{System is unusable. Should not be used by typical applications.}
1	Alert	^{Action must be taken immediately to prevent system failure. For example, a process is down. Should not be used by typical applications.}
2	Critical/Fatal	^{Critical conditions. For example, a hard disk is full, or process is crashing. Unrecoverable errors.}
3	Error	^{Error conditions. For example, a failed request resulting in a 500 HTTP response.}
4	Warning	^{Warning conditions. For example, a process is using too much memory. Fully recoverable, not immediate issue.}
5	Notice	^{Normal but significant events that do not indicate a problem. Ie, a process is starting.}
6	Informational	^{General informational messages about normal operations.}
7	Debug	^{Debugging messages.}

These might be too granular for most applications, so here's what we recommend:

Emergency & Alert: Reserved for infra-level logs. Should not be used by typical user applications.
Fatal: Unrecoverable errors, such as a process crashing.
Error: Recoverable errors, such as a failed request.
Warning: Warnings, such as a process using too much memory.
Info: Anything else that might be useful to debug the application. However, beware of logging sensitive information and overloading logs with too much information. This can get expensive and slow down your application.

For those functions that accept error objects, the error object is automatically serialized into a JSON object. error should be an instance of Error with a stack trace, but this is not enforced.

data is an object, containing any contextual information that might be useful to debug the error, or any pertinant information relating to the log message.

Emergency (0)

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

Alert (1)

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

Critical/Fatal (2)

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

Error (3)

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

Warning (4)

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

Notice (5)

logger.notice(message?: string, data?: any)

Info (6)

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

Debug (7)

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

Low-Level API

log

log(input: LogInput)

The low-level API for logging. This is used by all the logger functions. For LogInput type, see log.ts. You can use this function to build custom logging functions.

Example:

import {log} from 'jsout';

log({
    level: 6,
    message: 'test message',
    data: {foo: 'bar'},
    options: {
        level: 'info',
        format: 'json',
    }
})

Why should logs use `STDOUT` and `STDERR`?

Logs should be emitted to STDOUT and STDERR for a few reasons:

Separation of Concerns: Logs should be handled by a separate process, not the application itself. This allows for better error handling and logging, and prevents the application from crashing due to logging errors.
Standardization: STDOUT and STDERR are standard streams that are used by many logging tools and services. By emitting logs to these streams, you can easily integrate with existing logging pipelines and services.
Reliability: By emitting logs to STDOUT and STDERR, you can ensure that logs are captured and processed even if the application crashes or exits unexpectedly.

Support, Feedback, and Contributions

Star this repo if you like it!
Submit an issue with your problem, feature request or bug report
Issue a PR against main and request review. Make sure all tests pass and coverage is good.
Write about jsout in your blog, tweet about it, or share it with your friends!

Together we can make software more reliable and easier to maintain!

jsout