What Are the Logging Levels Available in Amnezia-Client?

The amnezia-client application supports five distinct logging levels—Trace, Debug, Info, Warning, and Error—defined in the client/mozilla/shared/loglevel.h header and implemented across the logging subsystem.

Amnezia VPN is an open-source VPN client available in the amnezia-vpn/amnezia-client repository. Understanding the logging levels available in amnezia-client is essential for debugging connection issues, monitoring application behavior, and configuring appropriate verbosity for production or development environments.

The Five Log Severity Levels

The logging system uses a severity-based enumeration where lower numeric values represent finer granularity. According to the source code in client/mozilla/shared/loglevel.h, the available logging levels in amnezia-client are ordered as follows:

• Trace (0) – Detailed execution tracing for deep debugging scenarios
• Debug (1) – General diagnostic messages that trace application flow
• Info (2) – Standard operational messages about normal application state
• Warning (3) – Unexpected conditions that do not prevent continued execution
• Error (4) – Critical failures indicating serious problems requiring attention

Implementation in Source Files

The logging architecture spans three key files that define, expose, and implement the severity levels.

Level Definitions in loglevel.h

The enumeration resides in client/mozilla/shared/loglevel.h, where the LogLevel type assigns numeric values from 0 (most verbose) to 4 (least verbose). This header serves as the central authority for severity constants used throughout the codebase.

Logger Interface in logger.h

The public API is declared in common/logger/logger.h, which exposes the Logger class with dedicated methods for each severity level: trace(), debug(), info(), warning(), and error(). These methods return stream objects that accept log messages.

Output Implementation in logger.cpp

The concrete implementation lives in common/logger/logger.cpp. This file maps each LogLevel to human-readable string prefixes (such as [DEBUG] or [ERROR]) and manages output routing—directing messages to stdout or stderr based on severity.

Using Logging Levels in Practice

The following example demonstrates how to instantiate a logger and emit messages at each available level:

#include "common/logger/logger.h"
#include "client/mozilla/shared/loglevel.h"

int main() {
    // Initialize the central logger (normally handled by the application)
    Logger logger("Main");

    // Emit a trace message – only visible when configured to Trace level
    logger.trace() << "Entering function X";

    // Debug message for development diagnostics
    logger.debug() << "Variable y = " << y;

    // Informational message about normal operation
    logger.info() << "Connection established";

    // Warning for unexpected but recoverable situations
    logger.warning() << "Latency higher than expected";

    // Error for critical failures
    logger.error() << "Failed to open VPN tunnel";

    return 0;
}

You can also implement runtime filtering by checking the current level before logging:

// Example: configuration-read level
LogLevel currentLevel = LogLevel::Info;

// Only log debug messages when level is Debug or more verbose (lower number)
if (currentLevel <= LogLevel::Debug) {
    logger.debug() << "This debug data appears only when level ≤ Debug";
}

Summary

• Amnezia-client defines five logging levels: Trace (0), Debug (1), Info (2), Warning (3), and Error (4).
• Levels are declared in client/mozilla/shared/loglevel.h and implemented in common/logger/logger.cpp.
• The Logger class provides methods trace(), debug(), info(), warning(), and error() for emitting messages.
• Lower numeric values indicate finer granularity, with Trace being the most verbose and Error the least.
• The implementation maps levels to prefixed strings like [DEBUG] and routes output to appropriate streams.

Frequently Asked Questions

How do I change the logging level in amnezia-client?

Logging level configuration is typically controlled via application settings or command-line flags that set the active threshold. The logger compares the configured level against the message level in common/logger/logger.cpp, emitting only messages that meet or exceed the current severity threshold.

What is the difference between Trace and Debug levels?

Trace (0) provides fine-grained execution flow details suitable for deep debugging of complex state transitions, while Debug (1) offers higher-level diagnostic information about application logic. Trace generates significantly more output and is rarely enabled in production builds.

Where does the amnezia-client logger output messages?

According to the implementation in common/logger/logger.cpp, log messages are written to stdout or stderr depending on severity, with Error-level messages typically directed to stderr. The output includes formatted prefixes such as [INFO] or [ERROR] to indicate the severity level.

Can I use the logger from custom modules?

Yes. Include common/logger/logger.h and instantiate a Logger object with a module identifier string. The class is designed for reuse across the entire amnezia-client codebase, as demonstrated in the header's public interface definition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}