Query monitored entities in Grail

This is a guide to effectively using Dynatrace Query Language (DQL) to query monitored entities. This involves using generic DQL features such as expanding arrays, joining data using the lookup command, and using the built-in parse functionality.

Query entity types

To query monitored entities by their respective type, you can use the dt.entity.* views.

To initiate the query, start with a blank query in your notebooks and enter fetch dt.entity. This triggers an auto-complete dialog where you can select the desired entity type.

Example of auto-complete for entity types.

For example, executing the fetch dt.entity.host query retrieves all host entities. By default, entity records include the ID and entity name.

fetch dt.entity.host

entity.name

id

HOST-1

HOST-123

HOST-2

HOST-456

HOST-3

HOST-789

HOST-4

HOST-101

HOST-5

HOST-111

HOST-6

HOST-131

HOST-7

HOST-141

To include additional details, you can use the fieldsAdd command. As you start typing, the auto-complete feature suggests available fields for the entity type.

Another way to get started is to use one of the built-in topology query snippets.

Example of how to get started by using built-in topology query snippets.

Query relationships

Relationships are exposed as fields and can be added similarly to other fields. For instance, you can add the runs relationship to your host records to obtain a list of all entities running on the host.

fetch dt.entity.host
| fieldsAdd runs

entity.name

id

runs

HOST-1

HOST-123

runs: Complex record

HOST-2

HOST-456

runs: Complex record

HOST-3

HOST-789

runs: Complex record

The runs field is a nested record that contains a field for each entity type running on a specific host. Depending on the cardinality, these fields are either strings representing a single entity ID or arrays of strings representing a list of entity IDs. In notebooks, select a nested record in the results list to see its contents.

If you only want to see process groups running on that host, you can specify this in the fieldsAdd command. The auto-complete feature will provide a list of possible identifier types.

Selecting a type refines the query to only return an array containing the process group IDs.

fetch dt.entity.host
| fieldsAdd runs[dt.entity.process_group]

entity.name

id

runs[dt.entity.process_group]

HOST-1

HOST-123

runs: PROCESS_GROUP-D123, PROCESS_GROUP-567, PROCESS_GROUP-012

HOST-2

HOST-456

runs: PROCESS_GROUP-D234, PROCESS_GROUP-234, PROCESS_GROUP-F10

HOST-3

HOST-789

runs: PROCESS_GROUP-D567, PROCESS_GROUP-789, PROCESS_GROUP-123

The field names for relationships differ from the original relationship names in the previous Dynatrace. Instead of using a single name prefixed with fromRelationship and toRelationship, the fields have different names on both sides.

See the relationship mapping table below to understand how second-generation relationships are represented as DQL fields.

Note that 1:n relationships only return 100 entity IDs per type, per record. In such cases, we recommend using classicEntitySelector() instead.

Entity lookups

You can use the lookup command to join data from related entities.

For example, to include the host tags with your service instances, you can access the host from a service instance by following the runs_on relationship.

fetch dt.entity.service_instance
| fieldsAdd runs_on[dt.entity.host]

entity.name

id

runs_on[dt.entity.host]

Mapped Instance for answer_queue on ActiveMQ Artemis

SERVICE_INSTANCE-1AB2

HOST-1

Mapped Instance for Requests executed in the background threads of eT-demo-1-BussinessBackend

SERVICE_INSTANCE-A123

HOST-2

It's important to note that service instances always run on a single host, which means that you obtain a single host ID per service instance record. This allows you to use the lookup command to add the hostname to your records. The hostname is added as the lookup.entity.name field.

fetch dt.entity.service_instance
| fieldsAdd runs_on[dt.entity.host]
| lookup sourceField:`runs_on[dt.entity.host]`, lookupField:id, [ fetch dt.entity.host ]

entity.name

id

runs_on[dt.entity.host]

lookup.entity.name

lookup.id

Mapped Instance for answer_queue on ActiveMQ Artemis

SERVICE_INSTANCE-2AB1

HOST-1

AB1-abc

HOST-1

Mapped Instance for Requests executed in the background threads of eT-demo-1-BussinessBackend

SERVICE_INSTANCE-B123

HOST-2

BA1-cba

HOST-2

Mapped Instance for :80

SERVICE_INSTANCE-C321

HOST-3

BA1-cba

HOST-2

Expand relationships

Hosts can run multiple service instances, so the runs[dt.entity.service_instance] field is an array of entity IDs.

fetch dt.entity.host
| fieldsAdd runs[dt.entity.service_instance]

entity.name

id

runs[dt.entity.service_instance]

dw123

HOST-1

SERVICE_INSTANCE-AB123, SERVICE_INSTANCE-CB123, SERVICE_INSTANCE-DB123

abc/123

HOST-2

SERVICE_INSTANCE-AB902

The lookup command doesn't apply to arrays of IDs, so you need to use the expand command first to retrieve individual records per service instance ID.

fetch dt.entity.host
| fieldsAdd runs[dt.entity.service_instance]
| expand runs[dt.entity.service_instance]

entity.name

id

runs[dt.entity.service_instance]

dw123

HOST-1

SERVICE_INSTANCE-DB123

dw456

HOST-2

SERVICE_INSTANCE-BA987

dw789

HOST-3

SERVICE_INSTANCE-CA687

dw652

HOST-4

SERVICE_INSTANCE-1AB2

In this example, the first record expands into four. Now you can use the lookup command to get the service instance details that you include in the lookup field.

fetch dt.entity.host
| fieldsAdd runs[dt.entity.service_instance]
| expand runs[dt.entity.service_instance]
| lookup sourceField:`runs[dt.entity.service_instance]`, lookupField:id, [ fetch dt.entity.service_instance]

entity.name

id

runs[dt.entity.service_instance]

lookup.entity.name

lookup.id

dw321

HOST-1

SERVICE_INSTANCE-DB123

Mapped Instance for easytravelazure-weather-service

SERVICE_INSTANCE-DB123

dw024

HOST-2

SERVICE_INSTANCE-2E986

Mapped Instance for weather-service-restify

SERVICE_INSTANCE-2E986

dw056

HOST-3

SERVICE_INSTANCE-D13A2

Mapped Instance for easytravelazure-weather-express

SERVICE_INSTANCE-D13A2

dw178

HOST-4

SERVICE_INSTANCE-D03A2

Mapped Instance for easytravelazure-weather-express

SERVICE_INSTANCE-D03A2

Entity tags

Entity tags consist of up to three values: context, key, and value. Dynatrace creates a string representation of these values in the following format:

[<context>]<key>:<value>

All occurrences of the [, ], and : characters need to be escaped using the \ character.
The tags field returns the string representations of these fields.

The following query example retrieves a list of host entity tags.

fetch dt.entity.host
| expand tags, alias:tag
| fields tag

tag

AppSec:Node.js

[Azure]tenant:CustomerA

HostName:dw123

AppSec:.NET

[AWS]created_at:2023-07-07T12:20:10Z

[Environment]tema:cpn

You can use the expand command to optimize tag filtering. This example filters hosts based on a specific cluster name.

fetch dt.entity.host
| expand tags
| filter contains(tags, "[Environment]Cluster.Name:prod-eu-west-6-ireland")

entity.name

id

tags

HOST-1

HOST-C2