Log content autodiscovery

By default, Dynatrace automatically discovers all new log files that meet the requirements described below.

Default autodiscovery

Dynatrace automatically discovers, analyzes, and stores (if selected for storage) logs every 60 seconds.

Whether your autodiscovered files are stored in Dynatrace depends on the log ingest rules.

By default, the OneAgent log module autodiscovers the following categories of log files:

  • System logs
    On Windows:

    • Windows Security Log
    • Windows Application Log
    • Windows System Log

    On Linux:

    • /var/log/messages
    • /var/log/syslog

  • Log files opened by running processes. For details, see Log autodiscovery requirements

  • IIS Logs (Windows only) - both event logs and plain log files

  • Container logs (Linux only) in Kubernetes, Openshift, and non-instrumented Docker. For details, see Log Monitoring in Kubernetes

  • z/OS logs. For details, see Monitor z/OS logs

If your logs are not ingested, it can be either because the OneAgent Log Enablement is disabled, or because the logs breach a rule concerning OneAgent Log Security.

Attributes selected in Windows event logs

For Windows event logs, Log Monitoring detects the following fields and sends them as custom attributes:

Semantic attribute name
Event property

winlog.level

Event.RenderingInfo.Level

winlog.levelid

Event.System.EventID

winlog.provider

Event.System.Provider.<xmlattr>.Name

winlog.task

Event.System.Task

winlog.opcode

Event.RenderingInfo.Opcode

Autodiscovery requirements

A log file must meet all of the following requirements in order to be autodiscovered:

  • The log file must be opened by an important process.

  • The log file must exist for a minimum of one minute.

    Unsupported timestamps

    Files with an unsupported timestamp are automatically timestamped with the time the file was read.

  • The logs must have a supported character encoding. By default, the supported encoding is UTF-8. Other supported types include UTF-8 BOM and, if the files contain the byte-order mark (BOM), UTF-16LE and UTF-16BE.

    Binary logs

    Binary log files are not detected automatically. You can use custom log sources with Allow binary format option set to ingest Binary log files.

  • The log file must be at least 0.5 KB in size.

  • The log file must have been updated (written to) in the last 7 days.
    Log files that have not been updated in the past 7 days while Log Monitoring is active will not be visible on dashboards.

  • The log file must be in the actual log or logs folder or in its subfolders:

    • Valid path examples:
      c:\log\log_file.txt
      c:\logs\NewFolder\log_file.txt
    • Invalid path example:
      c:\log\NewFolder\NewFolder\log_file.txt

    or the log filename must contain a log string preceded or followed by the period (.) or underscore (_) character:

    • Valid filename examples:
      c:\NewFolder\abc.log
      c:\NewFolder\0865842.log.txt
    • Invalid filename example:
      c:\NewFolder\logfile.txt

Turn off log autodiscovery

If you don't want Dynatrace to automatically discover new log files on a specific monitored host, you can turn off log autodiscovery.

  1. On the host, open the log analytics configuration file for editing.
    • On Linux:
      /var/lib/dynatrace/oneagent/agent/config/ruxitagentloganalytics.conf
    • On Windows:
      %PROGRAMDATA%\dynatrace\oneagent\agent\config\ruxitagentloganalytics.conf
  2. Set the following:
    AppLogAutoDetection = false

OneAgent restart is not required.

Limits for your log autodiscovery when using OneAgent

Log files in One agent:

  • cannot be deleted earlier than a minute after creation.
  • must be appended (old content is not updated).
  • must have text content.
  • must be opened constantly (not just for short periods of adding log entries).
  • must be opened in write mode.

Built-in autodetector rules

The autodetector has the following additional built-in rules:

OS
Directory pattern
File pattern
Action
All
/Log/
\*xel
Exclude
All
/commitlog/
CommitLog\*log
Exclude
Windows
/CCM/Logs/
\*
Exclude
Windows
/MSSQL/Log/
\*trc
Exclude
Windows
/*MSSQL*/OLAP/Log/
\*trc
Exclude
Windows
MSSQL/DATA/
\*ldf
Exclude
Windows
\*evtx
Exclude
Linux
/var/log/pods/
\*
Exclude
Linux
/var/lib/docker/containers/
\*
Exclude
All
/
*\[-.*]log\[-.*]*
Include
All
/
\*\[-.\_]log
Include
All
/
catalina.out\*
Include
All
/log/
\*
Include
All
/log/*/
\*
Include
All
/logs/
\*
Include
All
/logs/*/
\*
Include
Linux
^/var/log/**/
\*
Include

The custom security rules can only narrow auto-detection but not expand it.

Each custom log source path you add needs to be validated by OneAgent and abide by its security rules (file matching rules). The following security rules are applied on the OneAgent side:

Security rules

Dynatrace's security rules for custom log sources ensure data protection by managing OneAgent access to log sources. By implementing these security measures, Dynatrace ensures defense against unauthorized access and data misuse. You also have the option to add or override these predefined security rules in the configuration file on the host where OneAgent is intalled, allowing for flexibility in adapting to specific security needs.

The rules prohibit log paths in critical system directories (such as /etc, /boot, /proc, and several others), paths containing .ssh, paths with the .pem extension, and paths in directories starting with a dot (indicating hidden directories). Additionally, acceptable log paths must either have a log extension with certain separators, be located within the first or second level of a log or logs directory, be situated at any level of the /var/log directory, or have the filename catalina.out.

The rules take into account the resolved paths of symbolic links for security matching, emphasizing the importance of the actual file location over the symlink path.

  • A log path is not in any of the following: /etc, /boot, /proc, /dev, /bin, /sbin, /usr, WindowsRoot:\windows, or WindowsRoot:\winnt. However, Windows|winnt\system32\winevt\Logs is accepted AND
  • A log path does not contain .ssh AND
  • A log path does not have the .pem extension AND
  • A log path is not located in a directory whose name starts with . (for example, /.hidden) AND
  • A log path must have the log extension separated by ., -, or _ (it can be followed by another extension with the same separator set) OR
    • A log path must be located on the first or second level of the log or logs directory OR
    • A log path must be located on any level of the /var/log directory OR
    • A log path must have the file name catalina.out.

Files with paths that do not fulfill one or more criteria are not accepted. Once the conditions above are met, log file matching takes place. Check the log file matching rules.

Override security rules

You can add or override predefined security rules only in the configuration file on the host where OneAgent is installed.

  • Save your changes as a separate file placed in the OneAgent persistent configuration directory.

    • /var/lib/dynatrace/oneagent/agent/config/logmodule on Linux and UNIX

    • %PROGRAMDATA%\dynatrace\oneagent\agent\config\logmodule on Windows

      Any log file with the .json suffix is allowed in the above directories.

  • Do not edit the file that contains predefined rules:
    • /opt/dynatrace/oneagent/agent/conf on Linux and UNIX
    • %PROGRAMFILES%\dynatrace\oneagent\agent\conf on Windows
  • Rules defined by you under the custom configuration take precedence over the default rules. Additionally, the first matching rule determines whether a path passes the security test. The override configuration file (the one that you save in the persistent configuration directory) format needs to be the same as the format for a file with predefined rules.

Override configuration file

  • There is a predefined directory pattern that is executed from right to left. For example, /log/ will match /log/file and /var/log/file but not /log/dir/file
  • Only one directory is matched. For example, /log/*/ will match /log/dir/file but not /log/dir/dir2/file
  • The [-.\\_] expression in a pattern means that one of the characters provided in the square brackets must be present for a match to occur.

The override configuration file is a JSON object that defines rules for allowing or excluding certain log paths based on specified directory and file patterns.

The following structure is given in the file:

  • allowed-log-paths-configuration: Marks the array of the rules.

Each rule consists of three key-value pairs, with the following mandatory keys:

  • directory-pattern
  • file-pattern
  • action

The description of the keys is given below:

  • directory-pattern: This object specifies the pattern for matching directories. The directory pattern is executed from right to left, for example: /log/ will match /log/file.txt and /var/log/file.txt but not /log/dir/file.txt. The following rules apply:

    • A directory is matched by a wildcard *. For example, /log/*/ will match /log/dir/file.txt but not /log/dir/dir2/file.txt.
    • ** matches any number of subdirectories. For example, the pattern /log/dir/**/file.txt will match /log/dir/dir1/dir2/dir3/file.txt.
    • ^ matches the start of the path. It anchors the pattern to the beginning of the examined path For example, ^/usr/*/ matches paths starting with /usr/, such as /usr/log/file.txt and /usr/local/file.txt, but will not match /some/usr/log/file.txt. For Windows paths, the anchor can also skip the drive letter. For example, the pattern ^/Users/Public/ would match the actual path C:\Users\Public\file.txt. JSON treats \ as an escape character, so when specifying Windows paths, you can use either C:\\Users\\Public or C:/Users/Public but not C:\Users\Public.

    You can combine special characters such as *, **, and ^ within a single directory pattern to create more complex matching rules. For example, the pattern ^/log/**/dir/*/*/ will match the path /log/some/deep/dir/and/deeper/file.txt.

  • file-pattern: This object specifies the pattern for matching files within the directories matched by the directory pattern. This pattern is applied using full match. This means that a pattern such as *.txt will match error.txt but not error.txt.1. To properly detect files that follow rotation patterns, the file pattern must include a wildcard at the end. For example, to match files that rotate from error.txt to error.txt.1, the file pattern should be constructed as *.txt*.

  • action: This object specifies the action to be taken for the matched file. In this case, EXCLUDE or INCLUDE.

The [-.\\_] expression in square brackets means that one of the characters provided in the square brackets must be present for a match to occur.

An example override configuration file is given below:

Example override configuration file

{
    "allowed-log-paths-configuration":[
       {
          "directory-pattern":"/",
          "file-pattern":"*.pem",
          "action":"EXCLUDE" // or INCLUDE
       },
       ... your rules ...
    ]
 }

Examples of OneAgent security rules

Each custom log source path you add needs to be validated by OneAgent and abide by its security rules (file matching rules). Some predefined security rules are applied on the OneAgent side. Examples of exclude and include rules for UNIX, Linux, and Windows are listed in the table below.

Operating system
Directory pattern
File pattern
Action

UNIX

/

*.pem

EXCLUDE

UNIX

/

*[-.\\_]log[-.\\_]*

INCLUDE

Linux

/.ssh/

*

EXCLUDE

Linux

/

*[-.\\_]log

INCLUDE

Windows

/.*/

*

EXCLUDE

Windows

/windows/system32/winevt/Logs/

*

INCLUDE

Security rule lists for UNIX, Linux, and Windows

The full list of security rules for UNIX:

{
  "allowed-log-paths-configuration": [
    {
       "directory-pattern":"/",
       "file-pattern":"*.pem",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.ssh/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.*/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/",
       "file-pattern":".*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/etc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/boot/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/proc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/dev/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/bin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/sbin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/usr/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log[-.\\_]*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "catalina.out*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/lib/docker/containers/*/",
      "file-pattern": "*.log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/log/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    }
  ]
}

The full list of security rules for Linux:

{
  "allowed-log-paths-configuration": [
    {
       "directory-pattern":"/",
       "file-pattern":"*.pem",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.ssh/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/.*/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"/",
       "file-pattern":".*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/etc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/boot/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/proc/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/dev/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/bin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/sbin/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
       "directory-pattern":"^/usr/**/",
       "file-pattern":"*",
       "action":"EXCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log[-.\\_]*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "*[-.\\_]log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/",
      "file-pattern": "catalina.out*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/log/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "/logs/*/*/",
      "file-pattern": "*",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/lib/docker/containers/*/",
      "file-pattern": "*.log",
      "action": "INCLUDE"
    },
    {
      "directory-pattern": "^/var/log/**/",
      "file-pattern": "*",
      "action": "INCLUDE"
    }
  ]
}

The full list of security rules for Windows:

{
    "allowed-log-paths-configuration":[
       {
          "directory-pattern":"/",
          "file-pattern":"*.pem",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/.ssh/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/.*/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":".*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/windows/system32/winevt/Logs/",
          "file-pattern":"*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"/winnt/system32/winevt/Logs/",
          "file-pattern":"*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"^/windows/**/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"^/winnt/**/",
          "file-pattern":"*",
          "action":"EXCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":"*[-.\\_]log[-.\\_]*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":"*[-.\\_]log",
          "action":"INCLUDE"
       },
       {
          "directory-pattern":"/",
          "file-pattern":"catalina.out*",
          "action":"INCLUDE"
       },
       {
          "directory-pattern": "/log/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/log/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/log/*/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/logs/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/logs/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       },
       {
          "directory-pattern": "/logs/*/*/",
          "file-pattern": "*",
          "action": "INCLUDE"
       }
    ]
}