Logging & Error Handling System

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/errors.ts
• packages/core/src/logger.ts
• packages/core/ARCHITECTURE.md
• CONTRIBUTING.md
• AGENTS.md
• packages/core/src/tests/errors.test.ts
• packages/core/src/app-observability.ts

The Logging & Error Handling System provides a unified framework for observability and fault management across the OneBots gateway. It ensures consistent tracking of runtime events and standardized responses to system failures. This system integrates directly into the BaseApp core to serve adapters, protocols, and management modules.

Sources: packages/core/ARCHITECTURE.md:1-5, AGENTS.md:30-40

Logging Architecture

The logging system utilizes a structured approach to record runtime information. It replaces standard console output with a multi-level, prefix-aware logger instance derived from log4js.

Logger Instances

Developers access logging capabilities through this.logger within classes extending core components. The application generates these instances via this.app.getLogger(name) or this.app.getEnhancedLogger(name).

• Application Logs: Prefixed with [onebots].
• Adapter Logs: Prefixed with [onebots:<platform>] (e.g., [onebots:qq]).
• Account Logs: Named after the specific account_id.
• Protocol Logs: Formatted as <name>/<version>.

Sources: CONTRIBUTING.md:120-135, AGENTS.md:175-185

Log Levels

The system supports seven distinct log levels to categorize the importance and verbosity of information.

Level	Usage Description
trace	Fine-grained informational events
debug	Fine-grained events useful to debug an application
info	Informational messages highlighting progress
warn	Potentially harmful situations
error	Error events that might still allow the application to run
fatal	Very severe error events that will lead the application to abort
mark	High-priority custom markers

Sources: CONTRIBUTING.md:136-140

Enhanced Logging and Performance

The EnhancedLogger class provides utility methods for performance monitoring. The start(operation) method initiates a timer that returns a callback to stop the timer and log the total elapsed duration.

The diagram shows the lifecycle of a performance measurement operation using the Enhanced Logger.

Sources: packages/core/ARCHITECTURE.md:40-60, CONTRIBUTING.md:141-145

Error Handling System

The system defines a hierarchy of error types to distinguish between different failure modes. It uses the OneBotsError base class to provide structured context, timestamps, and severity levels.

Error Classification

Errors are categorized to facilitate automated recovery strategies or user notifications.

Category	Description	Severity
NETWORK	Connection failures or timeouts	MEDIUM
CONFIG	Invalid or missing configuration	HIGH
VALIDATION	Data integrity or schema failures	MEDIUM
RESOURCE	Missing files, memory, or permissions	HIGH
PROTOCOL	Communication protocol violations	MEDIUM
ADAPTER	Platform-specific integration failures	HIGH
RUNTIME	Unexpected execution state	HIGH

Sources: packages/core/src/tests/errors.test.ts:70-90, packages/core/ARCHITECTURE.md:10-25

Error Handling Flow

The ErrorHandler utility manages the lifecycle of an error by wrapping unknown exceptions and determining recoverability.

The flowchart illustrates how the system intercepts, wraps, and processes errors based on their type and severity.

Sources: packages/core/src/tests/errors.test.ts:100-140, CONTRIBUTING.md:165-175

Specialized Error Types

The framework provides specific classes for common failure scenarios. For example, UnsupportedCapabilityError carries structured context about a platform's missing features.

// Example of structured error context
throw new UnsupportedCapabilityError({
    platform: "teams",
    capability: "get_message",
    reason: "platform_unsupported",
});

Sources: packages/core/src/tests/errors.test.ts:85-98

Implementation Standards

To maintain system stability and traceability, developers must follow specific implementation rules.

1. Unified Naming: Catch block variables must be named error.
2. No Silent Failures: All caught exceptions must log at least an error level message.
3. Mandatory Wrapping: Use ErrorHandler.wrap(error) before propagating unknown errors.
4. No Console Usage: Prohibit console.log and console.error during runtime; use this.logger instead.
5. Context Injection: Include contextual data (e.g., user_id, platform) in error objects to aid debugging.

Sources: CONTRIBUTING.md:155-165, AGENTS.md:190-200

Observability Integration

Logging and error states feed into the observability endpoints. The system tracks account status (Online/Offline) and protocol readiness, exposing them via the /metrics and /ready endpoints.

• Readiness Snapshot: Checks if all protocols and adapters are in a functional state.
• Metrics: Exports error counts and performance data in Prometheus format.

Sources: packages/core/src/app-observability.ts:85-120, packages/core/src/app-observability.ts:200-220

The Logging & Error Handling System centralizes diagnostic information to reduce recovery time and improve the maintenance of multi-platform bot integrations. Standardized error types allow the core to manage complex recovery logic while providing developers with clear debugging paths.