How to Enable Debug Logging in OpenFlux: Command-Line and Programmatic Methods

To enable debug logging in OpenFlux, pass the --debug flag when starting the application or call utils.EnableDebug() programmatically in your Go code.

OpenFlux uses a lightweight logging helper located in utils/logging.go to manage diagnostic output. When enabled, the logger provides detailed runtime information including timestamps, microseconds, and source file lines to help trace transport negotiations and packet handling throughout the p1neappleXpress/OpenFlux codebase.

Understanding the Debug Logging Architecture

The logging system centers around a global verbose flag and a debugLog logger instance maintained in utils/logging.go. When the verbose flag is false, calls to utils.Debugf are no-ops with negligible overhead. When enabled, the system instantiates a standard library logger configured with precise formatting flags.

The utils.EnableDebug() function performs three critical operations:

1. Sets the package-level verbose variable to true
2. Creates debugLog using log.New(output, "", log.LstdFlags|log.Lmicroseconds)
3. Configures the standard logger to include timestamps, microseconds, and source file lines (log.Lshortfile)

Enabling Debug Logging via Command Line

The command-line interface defined in main.go exposes a --debug flag that triggers the logging subsystem at startup.

debug := flag.Bool("debug", false, "Enable verbose debug logging")
...
if *debug {
    utils.EnableDebug()
}

To start OpenFlux with verbose logging enabled, append the --debug flag to your command:

# Client mode with debug output

./universal-bypass-tool --client --url "https://example.com/doc" --socks5 :1080 --debug

# Exit-node mode with debug output

./universal-bypass-tool --exit-node --url "https://example.com/doc" --debug

Enabling Debug Logging Programmatically

When embedding OpenFlux as a library in your Go application, import the utils package and invoke the activation function directly.

import "universal-bypass-tool/utils"

func main() {
    // Enable verbose logging
    utils.EnableDebug()
    
    // Initialize and start OpenFlux components...
}

This approach instantiates the logger immediately rather than waiting for command-line parsing, making it ideal for library consumers who need diagnostics during initialization.

Runtime Configuration with SetDebug

For applications requiring dynamic control, utils.SetDebug() allows you to toggle logging without restarting.

// Enable debugging at runtime
utils.SetDebug(true)

// ... execute operations with verbose output ...

// Disable debugging to suppress further output
utils.SetDebug(false)

When passed true, SetDebug() internally calls EnableDebug(). When passed false, it clears the verbose flag, causing subsequent utils.Debugf calls to return immediately without formatting or output operations.

Summary

• OpenFlux implements debug logging through utils/logging.go using a global verbose flag and conditional Debugf calls
• Pass --debug on the command line to enable logging at startup via the flag parsing logic in main.go
• Call utils.EnableDebug() programmatically to activate logging when using OpenFlux as a library
• Use utils.SetDebug(true|false) to toggle debug output dynamically at runtime without application restarts

Frequently Asked Questions

How do I disable debug logging after enabling it?

Call utils.SetDebug(false) to immediately suppress debug output. This clears the internal verbose flag in utils/logging.go, causing all subsequent utils.Debugf calls to return without formatting or writing messages.

What timestamp format does the debug logger use?

The logger configured in utils.EnableDebug() uses log.LstdFlags combined with log.Lmicroseconds, producing timestamps with microsecond precision. It also sets log.Lshortfile to include the source file name and line number in each log entry.

Is there a performance penalty when debug mode is disabled?

No. When the verbose flag is false, utils.Debugf calls are no-ops that return immediately without string formatting or I/O operations. The debugLog logger is only instantiated when EnableDebug() is explicitly called, ensuring zero overhead during normal operation.

Where are the debug log messages generated in the codebase?

Debug messages are emitted from various transport and tunnel implementation files, including transport/yandex/yandex.go and tunnel/tunnel.go, which call utils.Debugf to output diagnostic information when verbose logging is active.

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