Logger

The @talosjs/logger component is a multi-backend logging layer. Every logger implements the same ILogger interface (init, error, warn, info, debug, log, success), so you can write to the terminal in development and ship to Better Stack in production while the call sites stay the same. Each method takes a message, an optional structured data object, and per-call display options. error additionally accepts an IException and logs its name, status, and stack trace.

What you get

TerminalLogger, BetterstackLogger, and BetterstackExceptionLogger all implement ILogger, so swapping backends doesn’t touch your callers. The six levels (error, warn, info, debug, log, and success) map to the ELogLevel enum, each rendered with its own color and symbol in the terminal. Pass a typed data object alongside the message and the backend serializes it for you. error() takes either a string or an IException, recording the exception’s name, status, and structured stack trace when given one. Registration is a decorator, and the container resolves the logger.

How it works

You pick (or implement) a backend and register it. Calls go through the ILogger methods; the backend handles formatting, serialization, and transport.

Method	Purpose
`init()`	Set up the logger (open handles, configure transports). Returns `void` or `Promise<void>`.
`error(message, data?, options?)`	Log an error. `message` may be a `string` or an `IException`.
`warn(message, data?, options?)`	Log a warning.
`info(message, data?, options?)`	Log informational output.
`debug(message, data?, options?)`	Log debug detail.
`log(message, data?, options?)`	Log a general message.
`success(message, data?, options?)`	Log a success message.

Every method shares the same ELogLevel levels: ERROR, WARN, INFO, DEBUG, LOG, SUCCESS. The built-in backends differ in where logs go, not in how you call them:

Backend	Destination	Best for
`TerminalLogger`	`stdout` / `stderr`	Local development and CLI output
`BetterstackLogger`	Better Stack Logtail	Structured application logs
`BetterstackExceptionLogger`	Better Stack Logtail	Exception-focused logging

TerminalLogger accepts LoggerOptionsType per call (showArrow, showTimestamp, showLevel, and useSymbol) to control how each line is rendered. Error and ERROR-level lines go to stderr, and everything else goes to stdout.

Environment variables

Only the production backends need configuration. TerminalLogger needs none.

Variable	Backend	Required	Purpose
`BETTERSTACK_LOGGER_SOURCE_TOKEN`	`BetterstackLogger`	Yes	Better Stack source token. Missing throws `LoggerException` (`LOG_FAILED`).
`BETTERSTACK_LOGGER_INGESTING_HOST`	`BetterstackLogger`	No	Optional Better Stack ingest host override.
`BETTERSTACK_EXCEPTION_LOGGER_APPLICATION_TOKEN`	`BetterstackExceptionLogger`	Yes	Better Stack application token.
`BETTERSTACK_EXCEPTION_LOGGER_INGESTING_HOST`	`BetterstackExceptionLogger`	No	Optional Better Stack ingest host override.

BETTERSTACK_LOGGER_SOURCE_TOKEN=source_xxx
BETTERSTACK_LOGGER_INGESTING_HOST=https://s123.eu-nbg-2.betterstackdata.com

Decorator and usage

`@decorator.logger()`

Registers a logger class with the container. It accepts an optional scope (defaults to EContainerScope.Singleton). All built-in loggers are decorated, and you use it to register custom loggers that implement ILogger.

import { decorator } from "@talosjs/logger";
import type { ILogger } from "@talosjs/logger";

@decorator.logger()
export class AuditLogger implements ILogger {
  // ...implement init, error, warn, info, debug, log, success
}

Resolve a logger from the container and call its level methods:

import { TerminalLogger } from "@talosjs/logger";
import { container } from "@talosjs/container";

const logger = container.get(TerminalLogger);

logger.info("User signed in", { userId: "123", email: "john@example.com" });
logger.success("Payment captured", { orderId: "ord_456", amount: 4999 });
logger.warn("Rate limit approaching", { remaining: 5 });

// Control terminal rendering per call
logger.debug("Cache miss", { key: "user:123" }, { useSymbol: true, showTimestamp: false });

error() accepts a plain message or an IException. Given an exception, it records the name, status, and stack trace automatically:

import { TerminalLogger } from "@talosjs/logger";
import { container } from "@talosjs/container";

const logger = container.get(TerminalLogger);

try {
  await processPayment(order);
} catch (error) {
  // Logs the exception name, status, and structured stack trace
  logger.error(error as IException, { orderId: order.id });
}

Inject a logger where you need it:

import { inject } from "@talosjs/container";
import { TerminalLogger } from "@talosjs/logger";

export class PaymentService {
  constructor(@inject(TerminalLogger) private readonly logger: TerminalLogger) {}
}

Exceptions

The component throws LoggerException when a backend is misconfigured. It carries a machine-readable key, a human-readable message, a data object, and an InternalServerError status.

import { BetterstackLogger, LoggerException } from "@talosjs/logger";

try {
  const logger = container.get(BetterstackLogger);
} catch (error) {
  if (error instanceof LoggerException) {
    console.error(`Logger error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Logging well

Pick the backend per environment: TerminalLogger for local and dev, BetterstackLogger or BetterstackExceptionLogger for production, with the call sites identical either way. Pass structured data rather than interpolated strings, keeping the message stable and moving variable detail into the data object so logs stay searchable. Match the level to the meaning, reserving error for failures, warn for recoverable issues, success for completed operations, and debug for diagnostics. When something throws, log the IException itself instead of its message string, so the name, status, and stack trace are all captured. Keep data serializable, since backends serialize the values; avoid class instances, functions, and circular references. In custom backends, throw LoggerException with a constant key and put the variable detail in data.

CLI command

Scaffold a logger class and its test file with the generator. It writes the class under modules/<module>/src/loggers/<Name>Logger.ts and installs @talosjs/logger if it is missing.

# Interactive: prompts for the name
talos logger:create

# Provide the name
talos logger:create --name=Audit

# Target a module and overwrite
talos logger:create --name=Audit --module=auth --override

Option	Description	Default
`--name`	Logger class name. The `Logger` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

The generated class starts as an ILogger stub, ready for you to implement each level method:

import type { IException } from "@talosjs/exception";
import type { ILogger } from "@talosjs/logger";
import type { ScalarType } from "@talosjs/types";
import { decorator } from "@talosjs/logger";

@decorator.logger()
export class AuditLogger implements ILogger {
  public async init(): Promise<void> {
    // Initialize your logger here
  }

  public log(message: string, data?: Record<string, ScalarType>): void {
    // Handle general logging
  }

  public debug(message: string, data?: Record<string, ScalarType>): void {
    // Handle debug logging
  }

  public info(message: string, data?: Record<string, ScalarType>): void {
    // Handle info logging
  }

  public success(message: string, data?: Record<string, ScalarType>): void {
    // Handle success logging
  }

  public warn(message: string, data?: Record<string, ScalarType>): void {
    // Handle warning logging
  }

  public error(message: string | IException, data?: Record<string, ScalarType>): void {
    // Handle error logging
  }
}

See logger:create for the full command reference.

Use with Claude and Codex

The generator ships a matching logger:create skill. It runs the scaffold and then guides your AI agent through completing the logger: implementing init, log, debug, info, success, warn, and error against a real transport and wiring up its dependencies. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a logger that writes structured logs for the payments module.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a logger that writes structured logs for the payments module.

For example, the prompt above maps to logger:create --name=Payments --module=payments, then implements the ILogger methods against your chosen transport.

Getting Started

AI

Framework

Command Line

What you get

How it works

Environment variables

Decorator and usage

`@decorator.logger()`

Exceptions

Logging well

CLI command

Use with Claude and Codex

​What you get

​How it works

​Environment variables

​Decorator and usage

​@decorator.logger()

​Exceptions

​Logging well

​CLI command

​Use with Claude and Codex

What you get

How it works

Environment variables

Decorator and usage

`@decorator.logger()`

Exceptions

Logging well

CLI command

Use with Claude and Codex