Merge pull request freqtrade#11505 from freqtrade/feat/log_from_config

allow loading logging from config

Author: xmatthias

build_helpers/schema.json

@@ -542,6 +542,10 @@
       "description": "Edge configuration.",
       "$ref": "#/definitions/edge"
     },
+    "log_config": {
+      "description": "Logging configuration.",
+      "$ref": "#/definitions/logging"
+    },
     "freqai": {
       "description": "FreqAI configuration.",
       "$ref": "#/definitions/freqai"
@@ -1281,6 +1285,30 @@
         "allowed_risk"
       ]
     },
+    "logging": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "number",
+          "const": 1
+        },
+        "formatters": {
+          "type": "object"
+        },
+        "handlers": {
+          "type": "object"
+        },
+        "root": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "version",
+        "formatters",
+        "handlers",
+        "root"
+      ]
+    },
     "external_message_consumer": {
       "description": "Configuration for external message consumer.",
       "type": "object",

docs/advanced-setup.md

@@ -188,30 +188,111 @@ as the watchdog.
 
 ## Advanced Logging
 
-On many Linux systems the bot can be configured to send its log messages to `syslog` or `journald` system services. Logging to a remote `syslog` server is also available on Windows. The special values for the `--logfile` command line option can be used for this.
+Freqtrade uses the default logging module provided by python.
+Python allows for extensive [logging configuration](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig) in this regards - way more than what can be covered here.
+
+Default logging (Colored terminal output) is setup by default if no `log_config` is provided.
+Using `--logfile logfile.log` will enable the RotatingFileHandler.
+If you're not content with the log format - or with the default settings provided for the RotatingFileHandler, you can customize logging to your liking.
+
+The default configuration looks roughly like the below - with the file handler being provided - but not enabled.
+
+``` json hl_lines="5-7 13-16 27"
+{
+  "log_config": {
+      "version": 1,
+      "formatters": {
+          "basic": {
+              "format": "%(message)s"
+          },
+          "standard": {
+              "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+          }
+      },
+      "handlers": {
+          "console": {
+              "class": "freqtrade.loggers.ft_rich_handler.FtRichHandler",
+              "formatter": "basic"
+          },
+          "file": {
+              "class": "logging.handlers.RotatingFileHandler",
+              "formatter": "standard",
+              // "filename": "someRandomLogFile.log",
+              "maxBytes": 10485760,
+              "backupCount": 10
+          }
+      },
+      "root": {
+          "handlers": [
+              "console",
+              // "file"
+          ],
+          "level": "INFO",
+      }
+  }
+}
+```
 
-### Logging to syslog
+!!! Note "highlighted lines"
+    Highlighted lines in the above code-block define the Rich handler and belong together.
+    The formatter "standard" and "file" will belong to the FileHandler.
 
-To send Freqtrade log messages to a local or remote `syslog` service use the `--logfile` command line option with the value in the following format:
+Each handler must use one of the defined formatters (by name) - and it's class must be available and a valid logging class.
+To actually use a handler - it must be in the "handlers" section inside the "root" segment.
+If this section is left out, freqtrade will provide no output (in the non-configured handler, anyway).
 
-* `--logfile syslog:<syslog_address>` -- send log messages to `syslog` service using the `<syslog_address>` as the syslog address.
+!!! Tip "Explicit log configuration"
+    We recommend to extract the logging configuration from your main configuration, and provide it to your bot via [multiple configuration files](configuration.md#multiple-configuration-files) functionality. This will avoid unnecessary code duplication.
 
-The syslog address can be either a Unix domain socket (socket filename) or a UDP socket specification, consisting of IP address and UDP port, separated by the `:` character.
+---
+
+On many Linux systems the bot can be configured to send its log messages to `syslog` or `journald` system services. Logging to a remote `syslog` server is also available on Windows. The special values for the `--logfile` command line option can be used for this.
 
-So, the following are the examples of possible usages:
+### Logging to syslog
+
+To send Freqtrade log messages to a local or remote `syslog` service use the `"log_config"` setup option to configure logging.
+
+``` json
+{
+  // ...
+  "log_config": {
+    "version": 1,
+    "formatters": {
+      "syslog_fmt": {
+        "format": "%(name)s - %(levelname)s - %(message)s"
+      }
+    },
+    "handlers": {
+      // Other handlers? 
+      "syslog": {
+         "class": "logging.handlers.SysLogHandler",
+          "formatter": "syslog_fmt",
+          // Use one of the other options above as address instead? 
+          "address": "/dev/log"
+      }
+    },
+    "root": {
+      "handlers": [
+        // other handlers
+        "syslog",
+        
+      ]
+    }
+
+  }
+}
+```
+
+[Additional log-handlers](#advanced-logging) may need to be configured to for example also have log output in the console.
 
-* `--logfile syslog:/dev/log` -- log to syslog (rsyslog) using the `/dev/log` socket, suitable for most systems.
-* `--logfile syslog` -- same as above, the shortcut for `/dev/log`.
-* `--logfile syslog:/var/run/syslog` -- log to syslog (rsyslog) using the `/var/run/syslog` socket. Use this on MacOS.
-* `--logfile syslog:localhost:514` -- log to local syslog using UDP socket, if it listens on port 514.
-* `--logfile syslog:<ip>:514` -- log to remote syslog at IP address and port 514. This may be used on Windows for remote logging to an external syslog server.
+#### Syslog usage
 
 Log messages are send to `syslog` with the `user` facility. So you can see them with the following commands:
 
-* `tail -f /var/log/user`, or 
+* `tail -f /var/log/user`, or
 * install a comprehensive graphical viewer (for instance, 'Log File Viewer' for Ubuntu).
 
-On many systems `syslog` (`rsyslog`) fetches data from `journald` (and vice versa), so both `--logfile syslog` or `--logfile journald` can be used and the messages be viewed with both `journalctl` and a syslog viewer utility. You can combine this in any way which suites you better.
+On many systems `syslog` (`rsyslog`) fetches data from `journald` (and vice versa), so both syslog or journald can be used and the messages be viewed with both `journalctl` and a syslog viewer utility. You can combine this in any way which suites you better.
 
 For `rsyslog` the messages from the bot can be redirected into a separate dedicated log file. To achieve this, add
 
@@ -228,13 +309,69 @@ For `syslog` (`rsyslog`), the reduction mode can be switched on. This will reduc
 $RepeatedMsgReduction on
 ```
 
+#### Syslog addressing
+
+The syslog address can be either a Unix domain socket (socket filename) or a UDP socket specification, consisting of IP address and UDP port, separated by the `:` character.
+
+
+So, the following are the examples of possible addresses:
+
+* `"address": "/dev/log"` -- log to syslog (rsyslog) using the `/dev/log` socket, suitable for most systems.
+* `"address": "/var/run/syslog"` -- log to syslog (rsyslog) using the `/var/run/syslog` socket. Use this on MacOS.
+* `"address": "localhost:514"` -- log to local syslog using UDP socket, if it listens on port 514.
+* `"address": "<ip>:514"` -- log to remote syslog at IP address and port 514. This may be used on Windows for remote logging to an external syslog server.
+
+
+??? Info "Deprecated - configure syslog via command line"
+
+  `--logfile syslog:<syslog_address>` -- send log messages to `syslog` service using the `<syslog_address>` as the syslog address.
+
+  The syslog address can be either a Unix domain socket (socket filename) or a UDP socket specification, consisting of IP address and UDP port, separated by the `:` character.
+
+  So, the following are the examples of possible usages:
+
+  * `--logfile syslog:/dev/log` -- log to syslog (rsyslog) using the `/dev/log` socket, suitable for most systems.
+  * `--logfile syslog` -- same as above, the shortcut for `/dev/log`.
+  * `--logfile syslog:/var/run/syslog` -- log to syslog (rsyslog) using the `/var/run/syslog` socket. Use this on MacOS.
+  * `--logfile syslog:localhost:514` -- log to local syslog using UDP socket, if it listens on port 514.
+  * `--logfile syslog:<ip>:514` -- log to remote syslog at IP address and port 514. This may be used on Windows for remote logging to an external syslog server.
+
 ### Logging to journald
 
 This needs the `cysystemd` python package installed as dependency (`pip install cysystemd`), which is not available on Windows. Hence, the whole journald logging functionality is not available for a bot running on Windows.
 
-To send Freqtrade log messages to `journald` system service use the `--logfile` command line option with the value in the following format:
+To send Freqtrade log messages to `journald` system service, add the following configuration snippet to your configuration.
+
+``` json
+{
+  // ...
+  "log_config": {
+    "version": 1,
+    "formatters": {
+      "journald_fmt": {
+        "format": "%(name)s - %(levelname)s - %(message)s"
+      }
+    },
+    "handlers": {
+      // Other handlers? 
+      "journald": {
+         "class": "cysystemd.journal.JournaldLogHandler",
+          "formatter": "journald_fmt",
+      }
+    },
+    "root": {
+      "handlers": [
+        // .. 
+        "journald",
+        
+      ]
+    }
+
+  }
+}
+```
 
-* `--logfile journald` -- send log messages to `journald`.
+[Additional log-handlers](#advanced-logging) may need to be configured to for example also have log output in the console.
 
 Log messages are send to `journald` with the `user` facility. So you can see them with the following commands:
 
@@ -244,3 +381,51 @@ Log messages are send to `journald` with the `user` facility. So you can see the
 There are many other options in the `journalctl` utility to filter the messages, see manual pages for this utility.
 
 On many systems `syslog` (`rsyslog`) fetches data from `journald` (and vice versa), so both `--logfile syslog` or `--logfile journald` can be used and the messages be viewed with both `journalctl` and a syslog viewer utility. You can combine this in any way which suites you better.
+
+??? Info "Deprecated - configure journald via command line"
+    To send Freqtrade log messages to `journald` system service use the `--logfile` command line option with the value in the following format:
+
+    `--logfile journald` -- send log messages to `journald`.
+
+### Log format as JSON
+
+You can also configure the default output stream to use JSON format instead.
+The "fmt_dict" attribute defines the keys for the json output - as well as the [python logging LogRecord attributes](https://docs.python.org/3/library/logging.html#logrecord-attributes).
+
+The below configuration will change the default output to JSON. The same formatter could however also be used in combination with the `RotatingFileHandler`.
+We recommend to keep one format in human readable form.
+
+``` json
+{
+  // ...
+  "log_config": {
+    "version": 1,
+    "formatters": {
+       "json": {
+          "()": "freqtrade.loggers.json_formatter.JsonFormatter",
+          "fmt_dict": {
+              "timestamp": "asctime",
+              "level": "levelname",
+              "logger": "name",
+              "message": "message"
+          }
+      }
+    },
+    "handlers": {
+      // Other handlers? 
+      "jsonStream": {
+          "class": "logging.StreamHandler",
+          "formatter": "json"
+      }
+    },
+    "root": {
+      "handlers": [
+        // .. 
+        "jsonStream",
+        
+      ]
+    }
+
+  }
+}
+```

docs/configuration.md

@@ -282,6 +282,7 @@ Mandatory parameters are marked as **Required**, which means that they are requi
 | `dataformat_ohlcv` | Data format to use to store historical candle (OHLCV) data. <br> *Defaults to `feather`*. <br> **Datatype:** String
 | `dataformat_trades` | Data format to use to store historical trades data. <br> *Defaults to `feather`*. <br> **Datatype:** String
 | `reduce_df_footprint` | Recast all numeric columns to float32/int32, with the objective of reducing ram/disk usage (and decreasing train/inference timing in FreqAI). (Currently only affects FreqAI use-cases) <br> **Datatype:** Boolean. <br> Default: `False`.
+| `log_config` | Dictionary containing the log config for python logging. [more info](advanced-setup.md#advanced-logging) <br> **Datatype:** dict. <br> Default: `FtRichHandler`
 
 ### Parameters in the strategy
 

docs/deprecated.md

@@ -88,3 +88,8 @@ Setting protections from the configuration via `"protections": [],` has been rem
 Using hdf5 as data storage has been deprecated in 2024.12 and was removed in 2025.1. We recommend switching to the feather data format.
 
 Please use the [`convert-data` subcommand](data-download.md#sub-command-convert-data) to convert your existing data to one of the supported formats before updating.
+
+## Configuring advanced logging via config
+
+Configuring syslog and journald via `--logfile systemd` and `--logfile journald` respectively has been deprecated in 2025.3.
+Please use configuration based [log setup](advanced-setup.md#advanced-logging) instead.

freqtrade/configuration/config_schema.py

@@ -425,6 +425,10 @@
             "description": "Edge configuration.",
             "$ref": "#/definitions/edge",
         },
+        "log_config": {
+            "description": "Logging configuration.",
+            "$ref": "#/definitions/logging",
+        },
         "freqai": {
             "description": "FreqAI configuration.",
             "$ref": "#/definitions/freqai",
@@ -883,6 +887,28 @@
             },
             "required": ["process_throttle_secs", "allowed_risk"],
         },
+        "logging": {
+            "type": "object",
+            "properties": {
+                "version": {"type": "number", "const": 1},
+                "formatters": {
+                    "type": "object",
+                    # In theory the below, but can be more flexible
+                    # based on logging.config documentation
+                    # "additionalProperties": {
+                    #     "type": "object",
+                    #     "properties": {
+                    #         "format": {"type": "string"},
+                    #         "datefmt": {"type": "string"},
+                    #     },
+                    #     "required": ["format"],
+                    # },
+                },
+                "handlers": {"type": "object"},
+                "root": {"type": "object"},
+            },
+            "required": ["version", "formatters", "handlers", "root"],
+        },
         "external_message_consumer": {
             "description": "Configuration for external message consumer.",
             "type": "object",