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 date format.

{
  logging: {
    enabled: true,
    moduleTracking: {
      enabled: true,
      includes: ["my-module"],
      excludes: ["noisy-module"]
    },
    channelFilter: {
      "main": "info",
      "http": 10,
      "db:*": "warn"
    },
    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 per channel. Specify the level as a string name ("info", "debug") or a numeric value. The core silently drops messages below the threshold.

Keys are matched against channel names exactly. A key ending in * acts as a prefix wildcard — "db:*" matches every channel whose name starts with db:. Logs emitted from the top-level Logging.Error/Warn/Info/Debug/Trace helpers land on the channel named "main"; use that name (or a "*" wildcard) to tune their threshold.

Date Format

The dateFormat field accepts a date format string (e.g., "yyyy-MM-dd HH:mm:ss"). Supported tokens: yyyy, yy, MM, M, dd, d, HH, H, mm, m, ss, s, SSS.