Core

Logging

Overview

The @antelopejs/interface-core/logging module provides a structured logging system with multiple severity levels and named channels. Log entries are emitted as events through an EventProxy, allowing any part of the application to listen for and process log output.

Import

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

Severity levels

The Logging.Level enum defines the available severity levels:

Level	Value	Purpose
`ERROR`	40	Critical errors that may cause failure
`WARN`	30	Issues that do not prevent operation
`INFO`	20	General status updates and information
`DEBUG`	10	Detailed information for debugging
`TRACE`	0	Highly detailed tracing information
`NO_PREFIX`	-1	Messages displayed without a level prefix

Log to the main channel

The Logging namespace exposes convenience functions that write to the "main" channel:

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

Logging.Error("Database connection failed", error);
Logging.Warn("Cache miss for key:", cacheKey);
Logging.Info("Server started on port", port);
Logging.Debug("Request payload:", payload);
Logging.Trace("Entering function processItem");

Each function accepts any number of arguments of any type.

Use named channels

For categorized logging, create a Logging.Channel instance with a channel name:

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

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

dbLog.Info("Connected to", dbHost);
dbLog.Error("Query failed:", query, error);

httpLog.Info("GET /api/users", statusCode);
httpLog.Debug("Response headers:", headers);

Channels provide the same methods as the main logging functions: Error, Warn, Info, Debug, and Trace.

Write at a custom level

Use the Write function for logs at a custom severity level:

// Static function on the Logging namespace
Logging.Write(25, "custom-channel", "Custom level message");

// Instance method on a channel
const channel = new Logging.Channel("metrics");
channel.Write(15, "Custom level within the metrics channel");

Log entry structure

Each log entry emitted through the event system has the following structure:

interface Log {
  time: number;      // Timestamp in milliseconds since epoch
  channel: string;   // Channel name (e.g., "main", "database")
  levelId: number;   // Numeric severity level
  args: any[];       // The logged values
}

Listen for log events

The logging system uses an EventProxy as its transport. Import the listener to register custom log handlers:

import eventLog from "@antelopejs/interface-core/logging/listener";

eventLog.register((log) => {
  const date = new Date(log.time).toISOString();
  const level = log.levelId >= 40 ? "ERROR" : log.levelId >= 30 ? "WARN" : "INFO";
  console.log(`[${date}] [${level}] [${log.channel}]`, ...log.args);
});

The listener is module-aware. Handlers registered by a module are automatically removed when that module is unloaded.

Next steps

Configuration - Project configuration with logging settings
Proxies - Understand the EventProxy that powers the logging transport

Modules

Configuration