Interfaces

Logging Interface

Explore the Logging interface that provides structured logging capabilities across your Antelopejs application.

Key Features

The Logging interface provides a structured, standardized way to log information across your Antelopejs application. It offers multiple severity levels, channel-based categorization, and an event-based architecture for capturing and processing log entries.

Severity levels: Predefined levels (ERROR, WARN, INFO, DEBUG, TRACE) for categorizing log importance
Channels: Separate logging channels for different components or concerns
Event-based: Uses the EventProxy system for flexible log processing
Standardized API: Consistent logging interface across the entire application

Usage

Importing the Logging Interface

import { Logging } from '@ajs/logging/beta';

Using Standard Logging Methods

The standard logging methods (Error, Warn, Info, Debug, Trace) write to the default main channel:

// Log an error
Logging.Error('Failed to connect to database', error);

// Log a warning
Logging.Warn('Connection pool running low', { available: 2, total: 10 });

// Log general information
Logging.Info('User logged in', { userId: 'user123' });

// Log debug information
Logging.Debug('Processing request', request);

// Log highly detailed trace information
Logging.Trace('Function called with arguments', args);

Creating Custom Channels

For better organization and filtering, create dedicated channels for different components:

const DatabaseLogger = new Logging.Channel('database');

DatabaseLogger.Info('Connection established');
DatabaseLogger.Debug('Query executed', { query, duration: 15 });
DatabaseLogger.Error('Query failed', error);

Log Levels

The Logging interface provides five standard severity levels:

Level	Value	Description	Use Case
ERROR	40	Critical errors that may cause application failure	Failed database connections, API errors, crashes
WARN	30	Important issues that don't prevent functioning	Degraded performance, retries, deprecated feature use
INFO	20	General application information and status updates	User actions, business events, normal operations
DEBUG	10	Detailed information useful for debugging	Variable values, control flow, decision points
TRACE	0	Highly detailed tracing information	Function entry/exit, loop iterations, detailed flow

Channels

Built-in Channels

AntelopeJS core uses several built-in channels for framework operations:

Channel	Description
`main`	Default channel for general logs
`loader.git`	Git module loader operations
`loader.package`	NPM package loader operations
`loader.local`	Local module loader operations
`loader.common`	Common loader functionality

You can monitor these channels to debug framework behavior:

ajs project run --verbose=loader.git,loader.package,loader.local

Filtering Logs by Channel

Channels can be filtered using the --verbose command-line flag or through configuration.

Command-line filtering:

Enable verbose logging for specific channels:

ajs project run --verbose=api.request,database.query

Enable verbose logging for all API-related channels:

ajs project run --verbose=api.*

Configuration-based filtering:

In your antelope.json:

{
  "logging": {
    "enabled": true,
    "channelFilter": {
      "main": "INFO",
      "api.*": "DEBUG",
      "database.connection": "INFO",
      "database.query": "TRACE",
      "loader.*": "WARN"
    }
  }
}

The command line options do not create git diffs, while the configuration does. Use configuration-based filtering for persistent logging.

Listening to Log Events

You can capture and process logs using the event system:

import eventLog from '@ajs/logging/beta/listener';

// Register a log listener
eventLog.register((log) => {
  const { time, channel, levelId, args } = log;

  // Example: Send to console
  const timestamp = new Date(time).toISOString();
  const level = getLevelName(levelId);

  if (levelId >= Logging.Level.WARN) {
    sendToExternalService({ timestamp, level, channel, message: args });
  }
});

// Helper function to get level name
function getLevelName(levelId: number): string {
  const levelNames = new Map([
    [Logging.Level.ERROR, 'ERROR'],
    [Logging.Level.WARN, 'WARN'],
    [Logging.Level.INFO, 'INFO'],
    [Logging.Level.DEBUG, 'DEBUG'],
    [Logging.Level.TRACE, 'TRACE']
  ]);
  return levelNames.get(levelId) ?? 'UNKNOWN';
}

Module Management

Learn about the module management system provided by the Antelope core interface that controls the lifecycle of modules in Antelopejs.

Proxy System

Learn about the powerful proxy system from the core interface which enable module-aware communication in Antelopejs.