refactor: Put log options in log section in config (#2440)

2025-11-30 00:25:52 +00:00 · 2025-08-18 15:22:33 +01:00
parent 8b1cab46e7
commit 4232359dce
27 changed files with 166 additions and 152 deletions
--- a/docs/config-description.md
+++ b/docs/config-description.md
@@ -415,7 +415,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The value must be one of the following: `sync`, `async`, `none`.
 - **Description**: The strategy used for Cache loading.

-### log_channels.[].channel
+### log.channels.[].channel

 - **Required**: False
 - **Type**: string
@@ -423,7 +423,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The value must be one of the following: `General`, `WebServer`, `Backend`, `RPC`, `ETL`, `Subscriptions`, `Performance`, `Migration`.
 - **Description**: The name of the log channel.

-### log_channels.[].log_level
+### log.channels.[].level

 - **Required**: False
 - **Type**: string
@@ -431,7 +431,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The value must be one of the following: `trace`, `debug`, `info`, `warning`, `error`, `fatal`.
 - **Description**: The log level for the specific log channel.

-### log_level
+### log.level

 - **Required**: True
 - **Type**: string
@@ -439,7 +439,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The value must be one of the following: `trace`, `debug`, `info`, `warning`, `error`, `fatal`.
 - **Description**: The general logging level of Clio. This level is applied to all log channels that do not have an explicitly defined logging level.

-### spdlog_format
+### log.format

 - **Required**: True
 - **Type**: string
@@ -447,7 +447,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: None
 - **Description**: The format string for log messages using spdlog format patterns. Documentation can be found at: <https://github.com/gabime/spdlog/wiki/Custom-formatting>.

-### spdlog_async
+### log.is_async

 - **Required**: True
 - **Type**: boolean
@@ -455,7 +455,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: None
 - **Description**: Whether spdlog is asynchronous or not.

-### log_to_console
+### log.enable_console

 - **Required**: True
 - **Type**: boolean
@@ -463,7 +463,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: None
 - **Description**: Enables or disables logging to the console.

-### log_directory
+### log.directory

 - **Required**: False
 - **Type**: string
@@ -471,7 +471,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: None
 - **Description**: The directory path for the log files.

-### log_rotation_size
+### log.rotation_size

 - **Required**: True
 - **Type**: int
@@ -479,7 +479,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The minimum value is `1`. The maximum value is `4294967295`.
 - **Description**: The log rotation size in megabytes. When the log file reaches this particular size, a new log file starts.

-### log_directory_max_files
+### log.directory_max_files

 - **Required**: True
 - **Type**: int
@@ -487,7 +487,7 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The minimum value is `1`. The maximum value is `4294967295`.
 - **Description**: The maximum number of log files in the directory.

-### log_tag_style
+### log.tag_style

 - **Required**: True
 - **Type**: string
--- a/docs/examples/config/example-config.json
+++ b/docs/examples/config/example-config.json
@@ -80,34 +80,52 @@
  },
  // Time in seconds for graceful shutdown. Defaults to 10 seconds. Not fully implemented yet.
  "graceful_period": 10.0,
-  // Overrides log level on a per logging channel.
-  // Defaults to global "log_level" for each unspecified channel.
-  "log_channels": [
-    {
-      "channel": "Backend",
-      "log_level": "fatal"
-    },
-    {
-      "channel": "WebServer",
-      "log_level": "info"
-    },
-    {
-      "channel": "Subscriptions",
-      "log_level": "info"
-    },
-    {
-      "channel": "RPC",
-      "log_level": "error"
-    },
-    {
-      "channel": "ETL",
-      "log_level": "debug"
-    },
-    {
-      "channel": "Performance",
-      "log_level": "trace"
-    }
-  ],
+  "log": {
+    // Overrides log level on a per logging channel.
+    // Defaults to global "log.level" for each unspecified channel.
+    "channels": [
+      {
+        "channel": "Backend",
+        "level": "fatal"
+      },
+      {
+        "channel": "WebServer",
+        "level": "info"
+      },
+      {
+        "channel": "Subscriptions",
+        "level": "info"
+      },
+      {
+        "channel": "RPC",
+        "level": "error"
+      },
+      {
+        "channel": "ETL",
+        "level": "debug"
+      },
+      {
+        "channel": "Performance",
+        "level": "trace"
+      }
+    ],
+    // The general logging level of Clio. This level is applied to all log channels that do not have an explicitly defined logging level.
+    "level": "info",
+    // Log format using spdlog format patterns (this is the default format)
+    "format": "%Y-%m-%d %H:%M:%S.%f %^%3!l:%n%$ - %v",
+    // Whether spdlog is asynchronous or not.
+    "is_async": true,
+    // Enables or disables logging to the console.
+    "enable_console": true,
+    // Clio logs to file in the specified directory only if "log.directory" is set
+    // "directory": "./clio_log",
+    // The log rotation size in megabytes. When the log file reaches this particular size, a new log file starts.
+    "rotation_size": 2048,
+    // The maximum number of log files in the directory.
+    "directory_max_files": 25,
+    // Log tags style to use
+    "tag_style": "uint"
+  },
  "cache": {
    // Configure this to use either "num_diffs", "num_cursors_from_diff", or "num_cursors_from_account". By default, Clio uses "num_diffs".
    "num_diffs": 32, // Generate the cursors from the latest ledger diff, then use the cursors to partition the ledger to load concurrently. The cursors number is affected by the busyness of the network.
@@ -121,17 +139,6 @@
    "enabled": true,
    "compress_reply": true
  },
-  "log_level": "info",
-  // Log format using spdlog format patterns (this is the default format)
-  "spdlog_format": "%Y-%m-%d %H:%M:%S.%f %^%3!l:%n%$ - %v",
-  // Whether spdlog is asynchronous or not.
-  "spdlog_async": true,
-  "log_to_console": true,
-  // Clio logs to file in the specified directory only if "log_directory" is set
-  // "log_directory": "./clio_log",
-  "log_rotation_size": 2048,
-  "log_directory_max_files": 25,
-  "log_tag_style": "uint",
  "extractor_threads": 8,
  "read_only": false,
  // "start_sequence": [integer] the ledger index to start from,
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -1,12 +1,13 @@
 # Logging

-Clio provides several logging options, which all are configurable via the config file. These are detailed in the following sections.
+Clio provides several logging options, which all are configurable via the config file under the `log` section.
+These are detailed in the following sections.

-## `log_level`
+## `log.level`

 The minimum level of severity at which the log message will be outputted by default. Severity options are `trace`, `debug`, `info`, `warning`, `error`, `fatal`. Defaults to `info`.

-## `spdlog_format`
+## `log.format`

 The format of log lines produced by Clio using spdlog format patterns. Defaults to `"%Y-%m-%d %H:%M:%S.%f %^%3!l:%n%$ - %v"`.

@@ -26,52 +27,52 @@ Some additional variables that might be useful:

 For more information about spdlog format patterns, see: <https://github.com/gabime/spdlog/wiki/Custom-formatting>

-## `spdlog_async`
+## `log.is_async`

 Whether spdlog is asynchronous or not.

-## `log_channels`
+## `log.channels`

 An array of JSON objects, each overriding properties for a logging `channel`.

 > [!IMPORTANT]
-> At the time of writing, only `log_level` can be overridden using this mechanism.
+> At the time of writing, only `log.level` can be overridden using this mechanism.

 Each object is of this format:

 ```json
 {
  "channel": "Backend",
-  "log_level": "fatal"
+  "level": "fatal"
 }
 ```

-If no override is present for a given channel, that channel will log at the severity specified by the global `log_level`.
+If no override is present for a given channel, that channel will log at the severity specified by the global `log.level`.

 The log channels that can be overridden are: `Backend`, `WebServer`, `Subscriptions`, `RPC`, `ETL` and `Performance`.

 > [!NOTE]
 > See [example-config.json](../docs/examples/config/example-config.json) for more details.

-## `log_to_console`
+## `log.enable_console`

 Enable or disable log output to console. Options are `true`/`false`. This option defaults to `true`.

-## `log_directory`
+## `log.directory`

 Path to the directory where log files are stored. If such directory doesn't exist, Clio will create it.

 If the option is not specified, the logs are not written to a file.

-## `log_rotation_size`
+## `log.rotation_size`

 The max size of the log file in **megabytes** before it will rotate into a smaller file. Defaults to 2GB.

-## `log_directory_max_files`
+## `log.directory_max_files`

 The max number of log files in the directory before old log files will be deleted to free up space. Defaults to 25.

-## `log_tag_style`
+## `log.tag_style`

 Tag implementation to use. Must be one of: