From 73d0d807a9d9526a1fc1dab1c65bcaf0fc471d50 Mon Sep 17 00:00:00 2001 From: Larry Hynes Date: Thu, 16 Jun 2016 22:38:14 +0100 Subject: [PATCH] [Doc] Correct configuration/logging.md --- doc/markdown/configuration/logging.md | 34 ++++++++++++--------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/doc/markdown/configuration/logging.md b/doc/markdown/configuration/logging.md index 1d42ac91a..b7c6c44b2 100644 --- a/doc/markdown/configuration/logging.md +++ b/doc/markdown/configuration/logging.md @@ -1,41 +1,40 @@ -# Rspamd logging settings +# rspamd logging settings ## Introduction -Rspamd has a number of logging variants. First of all there are three types of logs that are supported by rspamd: console logging (just output log messages to console), file logging (output log messages to file) and logging via syslog. Also it is possible to filter logging to specific level: +rspamd has a number of logging options. Firstly, there are three types of log output that are supported: console logging (just output log messages to console), file logging (output log messages to file) and logging via syslog. It is also possible to restrict logging to a specific level: * `error` - log only critical errors * `warning` - log errors and warnings * `info` - log all non-debug messages -* `debug` - log all including debug messages (huge amount of logging) +* `debug` - log all including debug messages (huge amount of logging) -Also it is possible to turn on debug messages for specific ip addresses. This ability is usefull for testing. For each logging type there are special mandatory parameters: log facility for syslog (read `syslog(3)` manual page for details about facilities), log file for file logging. Also file logging may be buffered for speeding up. For reducing logging noise rspamd detects for sequential identic log messages and replace them with total number of repeats: +It is possible to turn on debug messages for specific ip addresses. This can be useful for testing. For each logging type there are special mandatory parameters: log facility for syslog (read `syslog(3)` man page for details about facilities), log file for file logging. Also, file logging may be buffered for performance. To reduce logging noise, rspamd detects sequential matching log messages and replaces them with a total number of repeats: #81123(fuzzy): May 11 19:41:54 rspamd file_log_function: Last message repeated 155 times #81123(fuzzy): May 11 19:41:54 rspamd process_write_command: fuzzy hash was successfully added ## Unique id -From version 1.0, rspamd logs now contain unique id for each logging message. That allows to find the relevant messages quickly and filter everything else. Moreover, there is `module` definition now, for example `task` or `cfg` modules. Here is a quick example of how it works: let's imagine that we have an incoming task for some message. Then you'd see something like this in the logs: +From version 1.0, rspamd logs contain a unique id for each logging message. This allows finding relevant messages quickly. Moreover, there is now a `module` definition: for example, `task` or `cfg` modules. Here is a quick example of how it works: imagine that we have an incoming task for some message. Then you'd see something like this in the logs: 2015-09-02 16:41:59 #45015(normal) ; task; accept_socket: accepted connection from ::1 port 52895 2015-09-02 16:41:59 #45015(normal) ; task; rspamd_message_parse: loaded message; id: ; queue-id: -So the tag is `ed2abb` in this case. Afterwards, all processing related to this task will have the same tag. It includes not merely `task` module, but also other modules, such as `spf` or `lua` logger. -For other modules, such as `cfg` the tag is generated statically, using some specific characteristic, for example configuration file checksum. +So the tag is `ed2abb` in this case. All subsequent processing related to this task will have the same tag. It is enabled not only on the `task` module, but also others, such as the `spf` or `lua` modules. For other modules, such as `cfg`, the tag is generated statically using a specific characteristic, for example the configuration file checksum. ## Configuration parameters -Here is summary of logging parameters: +Here is summary of logging parameters: -- `type` - Defines logging type (file, console or syslog). For some types mandatory attribute is required: +- `type` - Defines logging type (file, console or syslog). For some types mandatory attributes may be required: + `filename` - path to log file for file logging + `facility` - logging facility for syslog - `level` - Defines logging level (error, warning, info or debug). - `log_buffer` - For file and console logging defines buffer size that will be used for logging output. -- `log_urls` - Flag that defines whether all urls in message would be logged. Useful for testing. -- `debug_ip` - List that contains ip addresses for which debugging would be turned on. +- `log_urls` - Flag that defines whether all urls in message should be logged. Useful for testing. +- `debug_ip` - List that contains ip addresses for which debugging should be turned on. - `log_color` - Turn on coloring for log messages. Default: `no`. -- `debug_modules` - A list of modules that are enabled for debugging. Now the following modules are available here: +- `debug_modules` - A list of modules that are enabled for debugging. The following modules are available here: + `task` - task messages + `cfg` - configuration messages + `symcache` - messages from symbols cache @@ -50,8 +49,7 @@ Here is summary of logging parameters: ### Log format -Rspamd supports custom log format when writing information about a message to log. This feature is supported since 1.1. The format string -looks as following: +rspamd supports a custom log format when writing information about a message to the log. (This feature is supported since version 1.1.) The format string looks as follows: log_format =<< EOD @@ -61,11 +59,9 @@ looks as following: $time_virtual virtual, dns req: $dns_req EOD -Newlines are replaced with spaces. Both text and variables are supported in the log format line. Each variable can have the optional -`if_` prefix when it should be printed if the specified component in the task is presented. Moreover, each variable can have optional body, -where dollar sign is replaced with variable value (as many times as it is found in body, e.g. `$var{$$$$}` will be replaced with variable's name repeated 4 times). +Newlines are replaced with spaces. Both text and variables are supported in the log format line. Each variable can have an optional `if_` prefix, which will log only if it is triggered. Moreover, each variable can have an optional body value, where `$` is replaced with the variable value (as many times as it is found in the body, e.g. `$var{$$$$}` will be replaced with the variable's name repeated 4 times). -Rspamd supports the following variables: +rspamd supports the following variables: - `mid` - message id - `qid` - queue id @@ -78,7 +74,7 @@ Rspamd supports the following variables: - `smtp_rcpts` - envelope rcpts - all recipients - `mime_rcpts` - MIME rcpts - all recipients - `len` - length of essage -- `is_spam` - one letter of spammines: `T` for spam, `F` for ham and `S` for skipped messages +- `is_spam` - a one-letter rating of spammyness: `T` for spam, `F` for ham and `S` for skipped messages - `action` - default metric action - `symbols` - list of all symbols - `time_real` - real time of task processing -- 2.39.5