Log ingest rules (Logs Classic)
Log Monitoring Classic
Dynatrace version 1.252+ OneAgent version 1.243+
If you use a OneAgent version earlier than 1.243 and Dynatrace Cluster version earlier than 1.252, go to Log Sources and Storage.
Dynatrace allows you to include and exclude specific log sources for your analysis. Using Dynatrace identity and access management (IAM) framework, you can control which user can change configurations on which scope.
The configuration is based on rules that use matchers for hierarchy, log path, and process groups. These rules determine which log files among those detected by OneAgent, either automatically or defined as custom log sources, are ingested.
Log ingest rule
-
Go to Settings and select Log Monitoring > Log ingest rules.
-
Select Add rule and provide the name for your configuration.
By default, the Include in storage button is turned on, indicating that items configured by this rule will be stored in Dynatrace. Alternatively, you can select the Exclude from storage rule type. -
Expand Details of your new rule and select Add matcher to create a specific match for this rule.
Multiple matchers can be included in one rule.Other than the Log source attribute in Windows (due to file paths being case insensitive), matchers are case-sensitive.
-
Select the matching attribute:
Attribute
Description
Search dropdown logic
Process group
Matching is based on the process group ID.
Attributes visible in the last 3 days are listed.
Log source
Matching is based on a log path; wildcards are supported in form of an asterisk. Autocompletion for Log source is only partial. You can either choose one of the predefined values or enter your log source.
Can be entered manually. No time limit.
Log source origin1
Matching is based on the detector was used by the log agent to discover the log file.
Can be entered manually. No time limit.
Log content
Matching is based on the content of the log; wildcards are supported in form of an asterisk.
Can be entered manually. No time limit.
Matching is based on the level of the log record. It supports the following values: alert
, critical
, debug
, emergency
, error
, info
, none
, notice
, severe
, warn
.
Can be entered manually. No time limit.
Matching is based on the host tag. The attribute only supports the tags set with the OneAgent command line tool or with the Remote configuration in a key=value
pair format. They can be distinguished by the [Environment]
prefix on the UI, but you should use the value without the prefix.
Multiple tags can be specified in a single matcher, but each tag needs to have the same key, such as logscope=frontend
, logscope=backend
.
Can be entered manually. No time limit.
K8s container name
Matching is based on the name of the Kubernetes container.
Attributes visible in the last 90 days are listed.
K8s namespace name
Matching is based on the name of the Kubernetes namespace.
Attributes visible in the last 90 days are listed.
K8s deployment name
Matching is based on the name of the Kubernetes deployment.
Attributes visible in the last 90 days are listed.
Container name
Matching is based on the name of the container.
Attributes visible in the last 90 days are listed.
DT entity container group ID
Matching is based on any of the selected container groups.
Can be entered manually. No time limit.
Process technology
Matching is based on the technology name.
Can be entered manually. No time limit.
Windows log record event ID3
Matching is based on any of the selected event ID attribute.
Can be entered manually. No time limit.
Windows log record source3
Matching is based on any of the selected source attributes.
Can be entered manually. No time limit.
Windows log record task category3
Matching is based on any of the selected task category attributes.
Can be entered manually. No time limit.
Windows log record operational code3
Matching is based on any of the selected operational code attribute.
Can be entered manually. No time limit.
The minimum required OneAgent version is 1.295.
Log record level attribute, transformed by OneAgent, is different than log status
attribute transformed by Dynatrace server.
The minimum required OneAgent version is 1.273.
Manually or automatically applied tags are not visible to OneAgent.
The minimum required OneAgent version is 1.289.
The wildcard is supported for any attribute value, and might be used multiple times in a single value. However, some attributes, for example Process Group, have a limited, predefined list of possible values that are selected from an auto-complete list.
If no wildcard is used in the value, then the matcher looks for an exact fit to the value. If a wildcard is used, the matcher looks for the exact match. For example, the value INFO
results in sending only the log data having the exact INFO
string, but the value *INFO*
(using the wildcards) matches log data that contain the INFO
string in its content.
-
Select Add value and, from the Values, select the detected log data items (log files or process groups that contain log data). Multiple values can be added to the selected attribute. You can have one matcher that indicates log source and matches values /var/log/syslog and Windows Application Log.
-
Save changes.
Defined rules can be reordered and are executed in the order in which they appear on the Log storage page.
- To activate your rule, turn on the Active toggle.
Starting with OneAgent version 1.249, you can activate/inactivate your rules by turning on/off the Active toggle. To manage your rules effectively, we recommend that you upgrade your OneAgent to version 1.249. If you have any rules set on the host with OneAgent version earlier than 249, you will not be able to inactivate them, in which case you need to remove such rules by selecting Delete on the rule level or via the REST API.
Matching a list of rules to log data
Matching occurs in a predefined hierarchy and rules are executed from top to bottom. This means that if a rule above on the list matches certain log data, then the lower ones will be omitted. Items matched in the higher-level configurations are overwritten in the lower-level configurations if they match the same log data. If no rule is matched, the file is not sent. The matching hierarchy is as follows:
- Host configuration rules
- Host group configuration rules
- Tenant configuration rules
Configuration scopes
Three hierarchy scopes are supported: host, host group, and tenant. The scope with the least possible set of rules has priority over larger sets.
- Log storage rules configured for a host take precedence over log storage rules configured for a host group.
- Log storage rules configured for a host group take precedence over log storage rules configured for a tenant.
Host scope
The host scope can be accessed through the Host settings for a specific host.
- Go to Hosts or Hosts Classic (latest Dynatrace).
- Find and select your host to display the host overview page.
- In the upper-right corner of the host overview page, select More (…) > Settings.
- From the host settings, go to Log Monitoring > Log ingest rules.
- Configure storage upload by adding rules with a set of attributes that matches the log data to be stored by Dynatrace.
Host group scope
The host group scope can be accessed via the Host page.
- Go to Hosts or Hosts Classic (latest Dynatrace) and select the host that interests you.
- On the host overview page, select Properties and tags.
- On the Properties and tags panel, find the Host group property to see the name of the host group to which the selected host belongs.
The Host group property is not displayed when the selected host doesn't belong to any host group.
- Select the host group name to list all hosts in that host group. This displays the OneAgent deployment page filtered by the selected host group. Each listed host has a Host group:
<group name>
link, where<group name>
is the name of the host group that you want to configure. - Select the host group name in any row.
- In the host group settings, select Log Monitoring > Log ingest rules.
- Configure storage upload by adding rules with a set of attributes that matches the log data to be stored by Dynatrace.
Tenant scope
The tenant scope is available in the settings menu.
- Go to Settings and select Log Monitoring > Log ingest rules.
- Configure storage upload by adding rules with a set of attributes that matches the log data to be stored by Dynatrace.
List hosts and host groups with overriding rules
The table on Settings > Log Monitoring > Log ingest rules lists all log storage rules that you have set at the tenant level. However, you may want to see where you have set log storage rules for hosts and host groups that override the tenant-level rules.
To list all entities (hosts and host groups) to which more specific log storage rules are applied
-
Go to Settings > Log Monitoring > Log ingest rules.
-
In the upper-right corner of the Log ingest rules page, select More (…) > Hierarchy and overrides. A searchable Hierarchy and overrides panel lists all entities (hosts and host groups) on which you have set log storage rules that override the tenant-level rules listed on Settings > Log Monitoring > Log ingest rules.
-
Select an entity name to go to that entity's Log ingest rules page.
Example upload
In this example, we configure the tenant storage upload for c:\inetpub\logs\LogFiles\ex_*.log
files in two process groups: IIS (PROCESS_GROUP-3D9D854163F8F07A)
and IIS (PROCESS_GROUP-4A7B47FDB53137AE)
. The log storage rule consists of two matchers: the first matcher finds the process groups and the second matcher matches only for the defined log source.
- Go to Settings > Log Monitoring > Log ingest rules.
- Select Add rule and provide the title for your configuration.
- Select Add matcher. This is the first matcher to match two specified process groups.
- From the Attribute list, select Process group.
- Select Add value and type IIS, and then, from the suggestion list, select
IIS (PROCESS_GROUP-3D9D854163F8F07A)
. - Select Add value again, type
IIS
and select the second process group from the suggestion list:IIS (PROCESS_GROUP-4A7B47FDB53137AE)
. - Select Add matcher again. This is the second matcher to match the specified log data source.
- From the Attribute list, select Log source.
- Select Add value and enter
c:\inetpub\logs\LogFiles\ex_*.log
as the value. - Save changes.
Example exclude
In this example, we configure the tenant storage upload for all log sources except c:\inetpub\logs\LogFiles\ex_*.log
files in a process group IIS (PROCESS_GROUP-4A7B47FDB53137AE)
.
- Go to Settings and select Log Monitoring > Log ingest rules.
- Select Add rule and provide the title for your configuration.
- Turn off Send to storage.
- Select Add matcher. This is the first matcher to match the specified process group.
- From the Attribute list, select
Process group
. - Select Add value and type IIS, and then, from the suggestion list, select
IIS (PROCESS_GROUP-3D9D854163F8F07A)
. - Select Add matcher again. This is the second matcher to exclude the specified log data source.
- From the Attribute list select Log source.
- Select Add value and enter
c:\inetpub\logs\LogFiles\ex_*.log
as a value. - Save changes.
REST API
You can use the Settings API to manage your log ingest rules:
- View schema
- List stored configuration objects
- View single configuration object
- Create new, edit, or remove existing configuration object
To check the current schema version for log ingest rules, list all available schemas and look for the builtin:logmonitoring.log-storage-settings
schema identifier.
Log ingest rules can be configured for the following scopes:
tenant
– configuration object affects all hosts on a given tenant.host_group
– configuration object affects all hosts assigned to a given host group.host
– configuration object affects only the given host.
To create a log ingest rule using the API:
-
Create an access token with the Write settings (
settings.write
) and Read settings (settings.read
) permissions. -
Use the GET a schema endpoint to learn the JSON format required to post your configuration. The log storage configuration schema identifier (
schemaId
) isbuiltin:logmonitoring.log-storage-settings
. Here is an example JSON payload with the log storage configuration:[{"insertAfter":"uAAZ0ZW5hbnQABnRlbmFudAAkMGUzYmY2ZmYtMDc2ZC0zNzFmLhXaq0","schemaId": "builtin:logmonitoring.log-storage-settings","schemaVersion": "0.1.0","scope": "tenant","value": {"config-item-title": "Added from REST API","send-to-storage": true,"matchers": [{"attribute": "dt.entity.process_group","operator": "MATCHES","values": ["PROCESS_GROUP-05F00CBACF39EBD1"]},{"attribute": "log.source","operator": "MATCHES","values": ["Windows System Log","Windows Security Log"]}]}}] -
Use the POST an object endpoint to send your configuration.
Examples
The examples that follow show the results of various combinations of rules and matchers.
Example 1: Multiple rules
In this example, there are two rules:
- Rule 1 is an Exclude rule and has two matchers: the process group attribute is Apache, and the Log source attribute is
access.log
). - Rule 2 is an Include rule and has one matcher: the process group attribute is Apache.
Results: access.log
is not sent, error.log
(of Apache) is sent, and error.log
(of other PG) is not sent.
access.log
written by Apache matches the first rule, which hassend-to-storage: false
, so it is not sent.access.log
not written by Apache doesn't match the first rule (due to incorrect process group), and doesn't match the second rule, so it is not sent.error.log
written by Apache does not match the first rule (due to incorrect source), but it matches the second rule, which hassend-to-storage: true
, so it is sent.error.log
not written by Apache doesn't match the first rule (due to both incorrect process group and log source), and doesn't match the second rule, so it is not sent.
{"send-to-storage": false,"matchers": [{"attribute": "log.source","values": ["/path/to/access.log"]},{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID"]}],"enabled": true},{"send-to-storage": true,"matchers": [{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID"]}],"enabled": true}
Example 2: Send logs written by Apache and containing 'ERROR'
This task requires setting one rule with two matchers.
{"send-to-storage": true,"matchers": [{"attribute": "log.content","values": ["*ERROR*"]},{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID"]}],"enabled": true}
Example 3: Send logs written by Apache or containing 'ERROR'
This task requires setting two rules with one matcher each.
{"send-to-storage": true,"matchers": [{"attribute": "log.content","values": ["*ERROR*"]}],"enabled": true},{"send-to-storage": true,"matchers": [{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID"]}],"enabled": true}
Example 4: Send logs written by Apache, and containing 'ERROR' and 'Customer'
This task requires setting one rule with three matchers, with one value each.
{"send-to-storage": true,"matchers": [{"attribute": "log.content","values": ["*ERROR*"]},{"attribute": "log.content","values": ["*Customer*"]},{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID"]}],"enabled": true}
Example 5: Send logs written by Apache, and containing 'ERROR' or 'Customer'
This task requires setting one rule with two matchers: a matcher with the process group value, and a matcher with two content values.
{"send-to-storage": true,"matchers": [{"attribute": "log.content","values": ["*ERROR*", "*Customer*"]}],"enabled": true},{"send-to-storage": true,"matchers": [{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID"]}],"enabled": true}
Example 6: Send logs written by Apache or MySQL
This task requires setting two rules, or one rule with one matcher having two values.
Rules with two matchers will not work here.
Setting two rules:
{"send-to-storage": true,"matchers": [{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-MYSQL"]}],"enabled": true},{"send-to-storage": true,"matchers": [{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID"]}],"enabled": true}
Setting one rule with one matcher having two values:
{"send-to-storage": true,"matchers": [{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID", "PROCESS_GROUP-MYSQL"]}],"enabled": true}
Example 7: Send all logs
This task requires setting a rule without any matchers.
{"send-to-storage": true,"matchers": [],"enabled": true}
Example 8: Send all logs except Apache and MySQL logs
This task requires setting two rules.
- The first rule is an Exclude rule with one matcher having two values.
- The second rule does not contain any matchers.
The rules have to be executed in the order indicated below.
{"send-to-storage": false,"matchers": [{"attribute": "dt.entity.process_group","values": ["PROCESS_GROUP-APACHEID", "PROCESS_GROUP-MYSQL"]}],"enabled": true},{"send-to-storage": true,"matchers": [],"enabled": true}
Frequently asked questions
OneAgent versions earlier than 1.243
won't send any data; they will get an empty whitelist in response.
All host perspective configs are migrated to the corresponding host scope.
No. Autodiscovery is a mechanism of OneAgent that detects logs, but it doesn't mean that log files are sent to storage automatically. A configuration page for autodiscovery is planned for a future release. To learn more about autodiscovery, see Log content autodiscovery (Logs Classic)
Yes, configuration items are matched from top to bottom, meaning that the top value is the most important.
It is applied within 90 seconds.
Yes. A content matcher narrows down the scope of log events (log entries) according to the criteria set (for example, searching only for error logs).
- Filtering (narrowing down the scope according to the criteria set) is carried out in OneAgent.
- Setting limits (for example, the log events per minute limit or the attribute values limit) is conducted in Dynatrace.
Yes. Content filtering conducted on OneAgent reduces both DDU costs and network usage. You can calculate the cost and network use reduction by determining your total data consumption and deducting the GB size of data that was filtered out. For details on how DDUs costs are calculated, see: