From 1f9c58644457dd22cb7c517ab31b5d647baf89d9 Mon Sep 17 00:00:00 2001 From: Cuong Manh Le Date: Tue, 16 Dec 2025 15:40:57 +0700 Subject: [PATCH] docs: add documentation for runtime internal logging --- docs/runtime-internal-logging.md | 46 ++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/runtime-internal-logging.md diff --git a/docs/runtime-internal-logging.md b/docs/runtime-internal-logging.md new file mode 100644 index 0000000..982632c --- /dev/null +++ b/docs/runtime-internal-logging.md @@ -0,0 +1,46 @@ +# Runtime Internal Logging + +When no logging is configured (i.e., `log_path` is not set), ctrld automatically enables an internal logging system. This system stores logs in memory to provide troubleshooting information when problems occur. + +## Purpose + +The runtime internal logging system is designed primarily for **ctrld developers**, not end users. It captures detailed diagnostic information that can be useful for troubleshooting issues when they arise, especially in production environments where explicit logging may not be configured. + +## When It's Enabled + +Internal logging is automatically enabled when: + +- ctrld is running in Control D mode (i.e., `--cd` flag is provided) +- No log file is configured (i.e., `log_path` is empty or not set) + +If a log file is explicitly configured via `log_path`, internal logging will **not** be enabled, as the configured log file serves the logging purpose. + +## How It Works + +The internal logging system: + +- Stores logs in **in-memory buffers** (not written to disk) +- Captures logs at **debug level** for normal operations and **warn level** for warnings +- Maintains separate buffers for normal logs and warning logs +- Automatically manages buffer size to prevent unbounded memory growth +- Preserves initialization logs even when buffers overflow + +## Configuration + +**Important**: The `log_level` configuration option does **not** affect the internal logging system. Internal logging always operates at debug level for normal logs and warn level for warnings, regardless of the `log_level` setting in the configuration file. + +The `log_level` setting only affects: +- Console output (when running interactively) +- File-based logging (when `log_path` is configured) + +## Accessing Internal Logs + +Internal logs can be accessed through the control server API endpoints. This functionality is intended for developers and support personnel who need to diagnose issues. + +## Notes + +- Internal logging is **not** a replacement for proper log file configuration in production environments +- For production deployments, it is recommended to configure `log_path` to enable persistent file-based logging +- Internal logs are stored in memory and will be lost if the process terminates unexpectedly +- The internal logging system is automatically disabled when explicit logging is configured +