Logging

@strata-js/util-logging is a structured logging utility that wraps pino. It changes pino's default behavior to match the console.* API -- when you pass multiple arguments, they are serialized and appended to the log message instead of being added as separate JSON fields.

This package is also re-exported from @strata-js/strata, so if you're already using Strata you don't need to install it separately.

Installation

npm install @strata-js/util-logging

For pretty-printed output during development, also install pino-pretty as a dev dependency:

npm install -D pino-pretty

Usage

import { logging } from '@strata-js/util-logging';

const logger = logging.getLogger('myService');

logger.info('Server started on port', 8080);
// [12:00:00 PM] INFO (myService): Server started on port 8080

logger.error('Request failed', { status: 500, path: '/api/users' });
// [12:00:01 PM] ERROR (myService): Request failed {"status":500,"path":"/api/users"}

If you're using Strata, the logging module is available directly:

import { logging } from '@strata-js/strata';

const logger = logging.getLogger('myService');

API

getLogger(name)

logging.getLogger(name : string) : BasicLogger

Returns a logger instance for the given name. If a logger with that name already exists, the same instance is returned.

Parameter	Type	Description
name	string	A name for the logger, typically your module or service name. Appears in log output.

setConfig(config)

logging.setConfig(config : LoggerConfig) : void

Updates the logging configuration. The new config applies to loggers created after this call. Loggers that have already produced output are not affected.

TIP

Call setConfig() early in your application startup, before creating any loggers, to ensure all loggers pick up the configuration.

LoggerConfig

Option	Type	Default	Description
level	string	'debug'	Minimum log level. Messages below this level are suppressed.
prettyPrint	boolean	true	Enable pretty-printed output via pino-pretty. Only takes effect if pino-pretty is installed.

BasicLogger

The logger object returned by getLogger(). Each method accepts any number of arguments -- objects are serialized to JSON and all arguments are joined with spaces into the final message string.

interface BasicLogger
{
    trace(...args : unknown[]) : void;
    debug(...args : unknown[]) : void;
    info(...args : unknown[]) : void;
    warn(...args : unknown[]) : void;
    error(...args : unknown[]) : void;
    fatal(...args : unknown[]) : void;
    silent(...args : unknown[]) : void;
}

Log Levels

Levels are listed from most verbose to least verbose. Setting a level means that level and everything above it will be logged.

Level	Description
trace	Fine-grained diagnostic information.
debug	General debugging information. The default level.
info	Normal operational messages.
warn	Something unexpected, but the application can continue.
error	An error occurred. The operation failed but the application continues.
fatal	A critical error. The application is likely about to crash.
silent	Suppresses all output. Calling logger.silent() is a no-op.

Examples

Configuration

import { logging } from '@strata-js/util-logging';

// Production: JSON output, info level
logging.setConfig({ level: 'info', prettyPrint: false });

const logger = logging.getLogger('myService');

// {"level":30,"time":1622349751673,"name":"myService","msg":"Request processed in 42ms"}
logger.info('Request processed in 42ms');

Disabling Logging

Set the level to silent to suppress all log output:

import { logging } from '@strata-js/util-logging';

logging.setConfig({ level: 'silent' });

const logger = logging.getLogger('myService');
logger.error('This will not appear');

Multiple Loggers

Create separate loggers for different parts of your application:

import { logging } from '@strata-js/util-logging';

const dbLogger = logging.getLogger('database');
const httpLogger = logging.getLogger('http');

dbLogger.info('Connected to PostgreSQL');
httpLogger.info('Listening on port', 8080);

Logging Objects and Errors

Arguments are automatically serialized. Errors include their stack trace.

const logger = logging.getLogger('myService');

// Objects are JSON-serialized
logger.info('User created', { id: 42, name: 'Alice' });
// [12:00:00 PM] INFO (myService): User created {"id":42,"name":"Alice"}

// Errors include the stack trace
try
{
    await riskyOperation();
}
catch(err)
{
    logger.error('Operation failed', err);
    // [12:00:01 PM] ERROR (myService): Operation failed Error: something broke
    //     at riskyOperation (/app/src/index.ts:42:11)
    //     ...
}

Pretty Print vs JSON

With prettyPrint: true (the default, requires pino-pretty installed):

[12:00:00 PM] INFO (myService): Server started on port 8080

With prettyPrint: false:

{"level":30,"time":1622349751673,"name":"myService","msg":"Server started on port 8080"}

Use pretty printing during development and JSON output in production for structured log aggregation.