• Home
  • Platform modules
  • Business Analytics in Dynatrace
  • Business event processing
  • DQL matcher in business events

DQL matcher in business events

powered by Grail

With Dynatrace on Grail, you can use the following Dynatrace Query Language (DQL) functions and logical operators in matchers for business event processing:

Functions

matchesPhrase

Filters records containing a specified phrase. Returns only matching records. This function is case insensitive for ASCII characters, it works with multi-value attributes (matching any of the values), and the asterisk character (*) is a wildcard only referring to a single term, not the whole field value.

  • Validation
    The matchesPhrase function performs case-insensitive contains for the whole query string.
    For found results, additional validation takes place:

    • if the query starts with a word character, the preceding character must be a non-word character.
    • if the query ends with a word character, the succeeding character must be a non-word character.
    • if the query starts with an asterisk, no validation of the preceding character is performed.
    • if the query ends with an asterisk, no validation of the succeeding character is performed.

  • Syntax
    matchesPhrase(<fieldName>, <value>)

  • Example
    In this example, you add a filter that matches log records that contain error phrase in their content.

    dql
    matchesPhrase(content, "error")
    Examples of event processing using DQL matchesPhrase function.
    Part of the input eventProcessing queryMatch resultDescription

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "192.168.0.1")

    Exact match by single term.

    attribute="User 'käärmanü' failed to login from 192.168.0.123"

    matchesPhrase(attribute, "192.168.0.1")

    Non-word character is expected after character 1.

    attribute="User 'käärmanü' failed to login from 192.168.0.123"

    matchesPhrase(attribute, "192.168.0.1*")

    The query would match all IPs with the last octet between 100 and 199.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "failed to login")

    Exact phrase match.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "failed to log")

    log is not a full word, non-word character is expected after log.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "failed to log*")

    If the query ends with a wildcard character, the validation of the succeeding character is skipped.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "ed to login")

    ed is not a full word, the preceding character l is a part of the word.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "*ed to login")

    If the query starts with a wildcard character, the validation of the preceding character is skipped.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "*ed to log*")

    If the query starts and ends with a wildcard character, the validation of the preceding and succeeding characters is skipped.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "käärmanü failed")

    There should be an apostrophe (') character between käärmanü and failed.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, "rmanü' failed")

    Non-ASCII character ä is treated as non-word character.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesPhrase(attribute, " 'käärmanü' failed")

    If the query starts with non-word character, the validation of the preceding character is skipped.

    attribute="Failed to assign monitoring configuration for com.dynatrace.extension"

    matchesPhrase(attribute, "configuration for")

    There is a space in the query and a tabulator in the attribute value.

    attribute="Failed to assign monitoring configuration for com.dynatrace.extension"

    matchesPhrase(attribute, "failed to")

    There is a single space in the query and a double space in the attribute value

    attribute="Failed to assign monitoring configuration for com.dynatrace.extension"

    matchesPhrase(attribute, "failed to")

    It is possible to search with multiple spaces.

    attribute=["Gdansk, Poland", "Linz, Austria", "Klagenfurt, Austria"]

    matchesPhrase(attribute, "Austria")

    The function handles multi-value attributes in "any-match" manner, in this case Austria is matched in second and third value.

    attribute=["Gdansk, Poland", "Linz, Austria", "Klagenfurt, Austria"]

    matchesPhrase(attribute, "Pol*")

    Wildcard can be used also when dealing with multi-value attributes.

matchesValue

Searches the records for a specific value in a given attribute. Returns only matching records.

  • Syntax
    matchesValue(<fieldName>, <value>)

  • Example
    In this example, you add a filter record where process.technology attribute contains nginx value.

    dql
    matchesValue(process.technology, "nginx")
    Examples of event processing using DQL matchesValue function.
    Part of the input eventProcessing queryMatch resultDescription

    attribute="Dynatrace"

    matchesValue(attribute, "dynaTrace")

    Case insensitive equality.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesValue(attribute, "192.168.0.1")

    The whole attribute value is considered.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesValue(attribute, "*192.168.0.1")

    The value ends with 192.168.0.1.

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesValue(attribute, "user*")

    The value starts with user (case-insensitively).

    attribute="User 'käärmanü' failed to login from 192.168.0.1"

    matchesValue(attribute, "*failed to log*")

    The value contains the string failed to log.

    attribute="Österreich"

    matchesValue(attribute, "österreich")

    Case insensitive only for ASCII characters.

    attribute="Österreich"

    matchesValue(attribute, "Österreich")

    Exact match.

    attribute=["Java", "DOCKER", "k8s"]

    matchesValue(attribute, "docker")

    The function handles multi-value attributes in "any-match" manner, in this case, docker is matched in the second value.

    attribute=["Java11", "java17"]

    matchesValue(attribute, "java")

    None of the values is equal to string java.

    attribute=["Java11", "java17"]

    matchesValue(attribute, "java*")

    Both values start with a string java.

isNotNull

Tests if a value is not NULL.

  • Syntax
    isNotNull(<value>)

  • Example
    In this example, we filter (select) data where the host.name field contains a value.

    dql
    isNotNull(`host.name`)
    timestampcontentevent.typehost.name

    2022-08-03 11:27:19

    2022-08-03 09:27:19.836 [QueueProcessor] RemoteReporter...

    LOG

    HOST-AF-710319

    Examples of event processing using DQL isNotNull function.
    Part of the input eventProcessing queryMatch resultDescription
    plaintext
    {
    attribute="Dynatrace"
}

    isNotNull(other)

    The other attribute does not exists

    plaintext
    {
    attribute="Dynatrace"
}

    isNotNull(attribute)

    The attribute has non-null value.

    plaintext
    {
    attribute=null
}

    isNotNull(attribute)

    The attribute has null value.

isNull

Tests if a value is NULL.

  • Syntax
    isNull(<value>)

  • Example
    In this example, we filter (select) data where the host.name field doesn't contain a value.

    dql
    filter isNull(`host.name`)
    timestampcontentevent.typehost.name

    2022-08-03 12:53:26

    2022-08-03T10:52:31Z localhost haproxy[12529]: 192.168.19.100:38440

    LOG

    Examples of event processing using DQL isNull function.
    Part of the input eventProcessing queryMatch resultDescription
    plaintext
    {
    attribute="Dynatrace"
}

    isNull(other)

    The other attribute does not exists.

    plaintext
    {
    attribute="Dynatrace"
}

    isNull(attribute)

    The attribute has non-null value.

    plaintext
    {
    attribute=null
}

    isNull(attribute)

    The attribute has null value.

Operators

Logical operators can be used to connect two or more expressions.

OR

Logical addition.

  • Syntax
    <expression_1> or <expression_2>

  • Example
    In this example, you add a matcher to filter records where the content contains either timestamp phrase or trigger phrase.

    dql
    matchesPhrase(content, "timestamp") or matchesPhrase(content, "trigger")

AND

Logical multiplication.

  • Syntax
    <expression_1> and <expression_2>

  • Example
    In this example, you add a matcher to filter records where the content contains timestamp phrase and trigger phrase.

    dql
    matchesPhrase(content, "timestamp") and matchesPhrase(content, "trigger")

NOT

Logical negation.

  • Syntax
    not <expression>

  • Example
    In this example, you add a matcher to filter records where the content doesn't contain timestamp phrase.

    dql
    not matchesPhrase(content, "timestamp")

Strict equality

Logical operator (==) indicating an exact match.

Data types need to be identical. However, if the decimal value is 0, floating numbers can be compared with integer data. For example, 1==1.0
For strings, the search is case-sensitive.

Contrary to matchesValue function, strict equality operator performs case-sensitive comparison, doesn't support wildcards and doesn't operate on elements being part of multi-value attributes.

  • Syntax
    <expression1> == <expression2>

  • Examples

    Examples of using the strict equality operator.

    Part of the input eventProcessing queryMatch resultDescription
    plaintext
    {
    attribute="Dynatrace"
}

    attribute == "Dynatrace"

    The attribute is of the string type and has the same value.

    plaintext
    {
   attribute="Dynatrace"
}

    attribute == "dynatrace"

    The strict equality is case-sensitive.

    plaintext
    {
    attribute="1"
}

    attribute == 1

    The attributes have different data types

    plaintext
    {
    attribute="1.0"
}

    attribute == 1

    Floating numbers can be compared to integer values if their decimals equal 0

    plaintext
    {
   attribute=["Java", "DOCKER", "k8s"]
}

    attribute == "Java"

    The attributes have different data types.

Grouping

You can create conditional grouping with brackets ( ).

dql
matchesValue(process.technology, "nginx") and ( matchesPhrase(content, "error") or matchesPhrase(content, "warn") )

Reuse expressions

All the matcher expressions used in either log events, metrics, processing or bucket configurations are valid DQL. That means you can also use these expressions together with DQL filter command for example in the log viewer.

filter matchesValue(process.technology, "nginx") and ( matchesPhrase(content, "error") or matchesPhrase(content, "warn") )