Logging

Severity Levels

Antelopejs defines five severity levels, each with a numeric value. Higher values indicate more critical messages. You can filter logs by setting a minimum level per channel in your project configuration.

Global Logging Functions

The Logging namespace provides functions for each severity level. These functions write to the main channel and are the quickest way to emit log messages from any module.

import { Logging } from "@antelopejs/interface-core/logging";

Logging.Error("Something failed:", error);
Logging.Warn("Deprecated feature used");
Logging.Info("Server started on port", 3000);
Logging.Debug("Request payload:", data);
Logging.Trace("Entering function processUser");

Each function accepts any number of arguments, similar to console.log. The core automatically attributes each log entry to the module that produced it.

Custom Channels

Named channels organize logs by category. Create a channel with Logging.Channel and use it the same way as the global functions. Channels let you filter and format logs independently in the project configuration.

import { Logging } from "@antelopejs/interface-core/logging";

const httpLog = new Logging.Channel("http");

httpLog.Info("GET /api/users - 200");
httpLog.Error("POST /api/users - 500:", error);
httpLog.Debug("Request headers:", headers);

A channel name can be any string. Choose names that reflect the subsystem producing the logs — http, database, auth, scheduler, and so on. Each channel can have its own minimum severity level in the configuration.

Writing to Custom Levels

Use Logging.Write() to log at an arbitrary numeric level. Custom levels are useful when the five built-in levels are not granular enough for your use case.

import { Logging } from "@antelopejs/interface-core/logging";

Logging.Write(25, "custom-channel", "Custom level message");

The first argument is the numeric level, the second is the channel name, and the remaining arguments form the log message. The message appears only if the channel's minimum level is at or below the specified value.

Log Configuration

Configure logging behavior in your antelope.config.ts under the logging key. The configuration controls which modules and channels produce visible output, the minimum severity threshold, and the output format.

{
  logging: {
    enabled: true,
    moduleTracking: {
      enabled: true,
      includes: ["my-module"],
      excludes: ["noisy-module"]
    },
    channelFilter: {
      "default": "info",
      "http": 10
    },
    formatter: {
      "default": "{{chalk.gray(DATE)}} {{chalk.blue(LEVEL_NAME)}} {{ARGS}}"
    },
    dateFormat: "yyyy-MM-dd HH:mm:ss"
  }
}

Module Tracking

Module tracking controls which modules produce visible log output. When enabled is true, the core tags each log entry with its originating module. Use includes to show logs only from specific modules, or excludes to hide logs from noisy modules.

Channel Filtering

The channelFilter field sets the minimum severity level for each channel. Specify the level as a string name ("info", "debug") or a numeric value. The core silently drops messages below the threshold.

Formatting

The formatter field defines output templates per channel. Templates use {{expression}} syntax with the following variables:

The chalk library is available inside template expressions for colored terminal output. The dateFormat field accepts a date format string (e.g., "yyyy-MM-dd HH:mm:ss").