# @travetto/log

> Logging framework that integrates at the console.log level.

Latest version **8.0.3** (published 2026-09-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install @travetto/log
pnpm add @travetto/log
yarn add @travetto/log
bun add @travetto/log
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 8.0.3 |
| Published | 2026-09-12 |
| First published | 2017-10-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 23.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 23 |
| Author | Travetto Framework |
| Maintainers | arcsine |
| Keywords | logging, travetto, typescript |

## Links

- npm: https://www.npmjs.com/package/@travetto/log
- Repository: https://github.com/travetto/travetto
- Homepage: https://travetto.io
- Issues: https://github.com/travetto/travetto/issues
- npm.io page: https://npm.io/package/@travetto/log

## Dependencies (3)

- [@travetto/di](https://npm.io/package/@travetto/di.md) ^8.0.1
- [@travetto/config](https://npm.io/package/@travetto/config.md) ^8.0.3
- [@travetto/terminal](https://npm.io/package/@travetto/terminal.md) ^8.0.1

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 8.0.3 (latest) — 2026-09-12
- 8.1.0-rc.4 (rc) — 2026-11-10
- 8.0.0-alpha.27 (alpha) — 2026-08-24
- 1.1.0-rc.0 (next) — 2020-09-20
- 1.0.0-beta.2 (beta) — 2019-08-29
- 8.1.0-rc.3 — 2026-11-08
- 8.1.0-rc.2 — 2026-11-03
- 8.1.0-rc.1 — 2026-11-01
- 8.1.0-rc.0 — 2026-10-31
- 8.0.2 — 2026-09-11
- 8.0.1 — 2026-09-05
- 8.0.0 — 2026-09-05
- 8.0.0-alpha.26 — 2026-08-24
- 8.0.0-alpha.25 — 2026-07-26
- 8.0.0-alpha.24 — 2026-07-25
- … 357 more at https://npm.io/package/@travetto/log/versions

## README

<!-- This file was generated by @travetto/doc and should not be modified directly -->
<!-- Please modify https://github.com/travetto/travetto/tree/main/module/log/DOC.tsx and execute "npx trv doc" to rebuild -->
# Logging

## Logging framework that integrates at the console.log level.

**Install: @travetto/log**
```bash
npm install @travetto/log

# or

yarn add @travetto/log
```

This module provides logging functionality, building upon [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/runtime/src/console.ts#L44) in the [Runtime](https://github.com/travetto/travetto/tree/main/module/runtime#readme "Runtime for travetto applications.") module. This is all ultimately built upon [console](https://nodejs.org/api/console.html) operations. The logging infrastructure is built upon the [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support.") system, and so new loggers can be created that rely upon dependency injected services and sources.

## Extending the Common Logger
By default, the system ships with the [CommonLogger](https://github.com/travetto/travetto/tree/main/module/log/src/common.ts#L13), and by default will leverage the [LineLogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/formatter/line.ts#L39) and the [ConsoleLogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/appender/console.ts#L7). The configuration [CommonLoggerConfig](https://github.com/travetto/travetto/tree/main/module/log/src/common.ts#L13) provides two configuration variables that allows for switching out [LineLogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/formatter/line.ts#L39) for the [JsonLogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/formatter/json.ts#L17), depending on the value of `CommonLoggerConfig.format`. Additionally the [ConsoleLogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/appender/console.ts#L7) can be swapped out for the [FileLogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/appender/file.ts#L11) depending on the value of `CommonLoggerConfig.output`.

**Code: Standard Logging Config**
```typescript
export class CommonLoggerConfig {
  @EnvVar('TRV_LOG_FORMAT')
  format: 'line' | 'json' = 'line';

  @EnvVar('TRV_LOG_OUTPUT')
  output: 'console' | 'file' | string = 'console';
}
```

In addition to these simple overrides, the [CommonLogger](https://github.com/travetto/travetto/tree/main/module/log/src/common.ts#L13) can be extended by providing an implementation of either a [LogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L36) or [LogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L28), with the declared symbol of `LogCommonSymbol`.

**Code: Sample Common Formatter**
```typescript
import { Injectable } from '@travetto/di';
import { LogCommonSymbol, type LogEvent, type LogFormatter } from '@travetto/log';

@Injectable(LogCommonSymbol)
export class SampleFormatter implements LogFormatter {
  format(event: LogEvent): string {
    return `${event.timestamp} [${event.level}]#[${event.scope ?? 'unknown'}] ${event.message ?? 'NO MESSAGE'} ${(event.args ?? []).join(' ')}`;
  }
}
```

As you can see, implementing [LogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L36)/[LogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L28) with the appropriate symbol is all that is necessary to customize the general logging functionality.

## Creating a Logger
The default pattern for logging is to create a [Logger](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L44) which simply consumes a logging event. The method is not asynchronous as ensuring the ordering of append calls will be the responsibility of the logger. The default logger uses `console.log` and that is synchronous by default.

**Code: Logger Shape**
```typescript
export interface Logger {
  log(event: LogEvent): unknown;
}
```

**Code: Log Event**
```typescript
export interface LogEvent extends ConsoleEvent {
  /**
   * Log message
   */
  message?: string;
}
```

**Code: Console Event**
```typescript
export interface ConsoleEvent {
  /** Time of event */
  timestamp: Date;
  /** The level of the console event */
  level: 'info' | 'warn' | 'debug' | 'error';
  /** The line number the console event was triggered from */
  line: number;
  /** The module name for the source file */
  module: string;
  /** The module path  for the source file*/
  modulePath: string;
  /** The computed scope for the console. statement.  */
  scope?: string;
  /** Arguments passed to the console call*/
  args: unknown[];
}
```

The [LogEvent](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L9) is an extension of the [ConsoleEvent](https://github.com/travetto/travetto/tree/main/module/runtime/src/console.ts#L10) with the addition of two fields:
   *  `message` - This is the primary argument passed to the console statement, if it happens to be a string, otherwise the field is left empty
   *  `context` - This is the final argument passed to the console statement, if it happens to be a simple object. This is useful for external loggers that allow for searching/querying by complex data

**Code: Custom Logger**
```typescript
import { Injectable } from '@travetto/di';
import type { LogEvent, Logger } from '@travetto/log';
import { JSONUtil } from '@travetto/runtime';

@Injectable()
export class CustomLogger implements Logger {
  log(event: LogEvent): void {
    const headers = new Headers();
    headers.set('Content-Type', 'application/json');
    const body = JSONUtil.toUTF8(event);
    fetch('http://localhost:8080/log', { method: 'POST', headers, body });
  }
}
```

## Creating a Decorator
In addition to being able to control the entire logging experience, there are also scenarios in which the caller may want to only add information to the log event, without affecting control of the formatting or appending. The [LogDecorator](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L20) is an interface that provides a contract that allows transforming the [LogEvent](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L9) data. A common scenario for this would be to add additional metadata data (e.g. server name, ip, code revision, CPU usage, memory usage, etc) into the log messages.

**Code: Log Decorator Shape**
```typescript
export interface LogDecorator {
  decorate(event: LogEvent): LogEvent;
}
```

**Code: Custom Logger**
```typescript
import os from 'node:os';

import { Injectable } from '@travetto/di';
import type { LogDecorator, LogEvent } from '@travetto/log';

@Injectable()
export class CustomDecorator implements LogDecorator {
  decorate(event: LogEvent): LogEvent {
    event.args.push({
      memory: process.memoryUsage,
      hostname: os.hostname()
    });
    return event;
  }
}
```

## Logging to External Systems
By default the logging functionality logs messages directly to the console, relying on the `util.inspect` method, as is the standard behavior. When building distributed systems, with multiple separate logs, it is useful to rely on structured logging for common consumption. The framework supports logging as [JSON](https://www.json.org), which is easily consumable by services like [elasticsearch](https://elastic.co) or [AWS Cloudwatch](https://aws.amazon.com/cloudwatch/) if running as a lambda or in a docker container. 

The main caveat that comes with this, is that not all objects can be converted to JSON (specifically circular dependencies, and unsupported types). That end, the framework recommends logging with the following format, `message: string`   `context: Record<string, Primitive>`. Here context can be recursive, but the general idea is to only pass in known data structures that will not break the [JSON](https://www.json.org) production.

## Environment Configuration

**Code: Standard Logging Config**
```typescript
export class CommonLoggerConfig {
  @EnvVar('TRV_LOG_FORMAT')
  format: 'line' | 'json' = 'line';

  @EnvVar('TRV_LOG_OUTPUT')
  output: 'console' | 'file' | string = 'console';
}
```

The following environment variables have control over the default logging config:
   *  `TRV_LOG_FORMAT` - This determines whether or not the output is standard text lines, or is it output as a single line of [JSON](https://www.json.org)
   *  `TRV_LOG_OUTPUT` - This determines whether or not the logging goes to the console or if it is written to a file
   *  `TRV_LOG_PLAIN` - Allows for an override of whether or not to log colored output, this defaults to values provided by the [Terminal](https://github.com/travetto/travetto/tree/main/module/terminal#readme "General terminal support") in response to `FORCE_COLOR` and `NO_COLOR`
   *  `TRV_LOG_TIME` - This represents what level of time logging is desired, the default is `ms` which is millisecond output. A value of `s` allows for second level logging, and `false` will disable the output. When ingesting the content into another logging, its generally desirable to suppress the initial time output as most other loggers will append as needed.

---
_Source: https://npm.io/package/@travetto/log · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._