Package detail

A Syslog-compatible, simple, structured logging tool for Node.js projects. Sponsored by Aeroview.

Features

😃 Built for developer happiness & productivity

• Automatic Error serialization
• Automatically removes noisy internal stack traces such as node:internal/...
• Colorized, formatted human-readable output for local development
• Supports Error.cause for error chaining/traces across layers of your application

🔒 Syslog Compatible Structured Logs

• JSON output for log aggregation into services like Aeroview and CloudWatch
• Standardized Syslog log levels and output

🛡 Defensive & DevOps Friendly

• Production settings by default for safety
• Transport handled outside of the process via stdout and stderr
• Easy to use and simple configuration
• Only 1 small dependency. Fast & reliable TypeScript codebase
• Excellent test coverage (>90%)

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.

We recommend using the following settings for local development:

LOG=debug LOG_FORMAT=cli node /path/to/app.js

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:

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: cli, json

Default: json (recommended for production)

Logger API

Log levels are based on the syslog levels:

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: 4xx HTTP responses, unexpected behavior, or potential issues.
• 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.critical(message?: string, error?: any, data?: any)
• logger.fatal(message?: string, error?: any, data?: any)

Error (3)

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

Warning (4)

• logger.warn(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:

1. Decoupling Logging from the Application: By emitting logs to STDOUT and STDERR, the application separates the concern of logging from its core functionality. This approach allows the application to focus solely on its primary tasks, while a separate process or system manages the logging. This decoupling enhances modularity and simplifies the application’s architecture.

2. Reliability and Robustness: Handling logs within the application can introduce additional points of failure. If the process being monitored crashes, the logs may be lost, making it difficult to diagnose the issue. If the logging mechanism fails, it could potentially impact the application’s performance or even cause crashes. Emitting logs to STDOUT and STDERR ensures that the application remains unaffected by logging failures, as these standard streams are managed by the underlying operating system or container runtime.

3. Scalability and Flexibility: Emitting logs to standard streams allows for greater scalability and flexibility. Logs can be easily redirected, aggregated, and processed by external tools or services designed specifically for log management. This approach supports various logging strategies without requiring changes to the application code, enabling seamless integration with diverse logging infrastructures.

4. Simplified Deployment and Management: Emitting logs to STDOUT and STDERR simplifies deployment and management processes. Applications do not need to be configured with complex logging libraries or dependencies, reducing the risk of configuration errors and simplifying the deployment pipeline. This also aligns well with containerized environments (e.g., Docker), where standard streams are commonly used for log collection and monitoring.

Contributing

• ⭐ Star this repo if you like it!
• 🐛 Open an issue for bugs or suggestions.
• 🤝 Submit a PR to main — all tests must pass.

Related Projects

• autorel: Automate semantic releases based on conventional commits.
• hoare: A fast, defensive test runner for JS/TS.
• brek: Typed config loader for dynamic, secret-based configs.
• pgsmith: A SQL builder for parameterized queries in PostgreSQL.