Atatus allows you to handle multiline events that span multiple lines of text. This is particularly useful for dealing with files that contain stack traces or other types of multiline log entries. By defining the correct multiline pattern, Atatus can group related lines together to form a single event.

To process the multiline log events in Atatus, you must configure the processing_rules settings in the /etc/atatus-infra-agent/conf.d/files.d/files.yml file. These settings allow you to specify which lines of the log file belong to the same event and should be combined into a single message.

# Log section
logs:
  - type: file
    paths:
      - /var/log/my-app/error.log
    service: my_service
    source: my_source
    processing_rules:
       - type: 'multiline'
         pattern: '^[[:space:]]'
         negate: false
         group: 'after'

processing_rules.type: This specifies the type of multiline event processing that atatus should use. This is set to multiline by default.

processing_rules.pattern: The processing_rules.pattern type uses regular expressions to match the start and end of a multiline event. When Atatus encounters a logline that matches the specified pattern, it assumes that the following are part of the same event until a new log line that matches the pattern is found.

processing_rules.negate: The processing_rules.negate option in Atatus’s multiline configuration determines whether the regular expression pattern specified by processing_rules.pattern should be negated. When set to "true", any line that does not match the specified pattern is considered the start of a new event. This option is handy when there is a specific pattern for the start of an event but no specific pattern for the end.

processing_rules.group: The processing_rules.group option specifies combining matching lines into a single event. The possible settings for processing_rules.group are after or before, and the behavior of these settings depends on the value of the processing_rules.negate option.

Examples of processing rule configurations

PHP stack traces

PHP error stack traces consist of multiple lines. After the initial line, subsequent lines of the stack traces are not grouped. below is the example

ERROR - 2023-08-15 08:56:45 --> mysqli_sql_exception: syntax error, unexpected $end, expecting FTS_TERM or FTS_NUMB or '*' in /home/dsf/web/vendor/codeigniter4/framework/system/Database/MySQLi/Connection.php:295
Stack trace:
#0 /home/dsf/web/vendor/codeigniter4/framework/system/Database/MySQLi/Connection.php(295): mysqli->query()
#1 /home/dsf/web/vendor/codeigniter4/framework/system/Database/BaseConnection.php(691): CodeIgniter\Database\MySQLi\Connection->execute()
CodeIgniter\Database\BaseConnection->query()
#4 /home/dsf/web/vendor/codeigniter4/framework/system/Model.php(606): CodeIgniter\Database\BaseBuilder->countAllResults()
#8 /home/dsf/web/public/index.php(67): CodeIgniter\CodeIgniter->run()
#9 {main}

CRITICAL - 2023-08-15 08:56:45 --> Call to a member function getResult() on bool
in SYSTEMPATH/Model.php on line 242.
 1 SYSTEMPATH/BaseModel.php(618): CodeIgniter\Model->doFindAll()
 2 SYSTEMPATH/BaseModel.php(1192): CodeIgniter\BaseModel->findAll()
 3 SYSTEMPATH/CodeIgniter.php(368): CodeIgniter\CodeIgniter->handleRequest()
 4 FCPATH/index.php(67): CodeIgniter\CodeIgniter->run()

In order to consolidate those traces, you can add processing rules that group the stack trace, enabling more effective analysis.

    processing_rules:
      - type: 'multiline'
        pattern: '^(ERROR|CRITICAL)'
        negate: true
        group: 'after'
        skip_newline: false