# 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

```ts
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:

```ts
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:

```ts
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:

```ts
// 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:

```ts
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:

```ts
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](./7.configuration.md) - Project configuration with logging settings
- [Proxies](./2.proxies.md) - Understand the `EventProxy` that powers the logging transport