Dynatrace: mastering entity selectors for observability at scale

1. Strategic importance of the entity selector #

The entity selector is the cornerstone of the Dynatrace platform for targeting and isolating specific components of your dynamic infrastructure.

Why is it essential? #

Whether you are defining the scope of a management zone, configuring targeted alerts, building dynamic dashboards or querying the REST API v2, the entity selector is unavoidable. It lets you move from static management (manually selecting hosts or services) to dynamic management based on the real attributes of your environment. It thus ensures automated observability that is resilient to continuous change (deployments, autoscaling, etc.).

2. Syntax and key operators #

An entity selector is a string used to filter entities. Criteria are separated by commas, which act as a logical AND operator.

The fundamental operators #

• type(): filters by entity type (e.g. HOST, SERVICE, APPLICATION, PROCESS_GROUP).
• tag(): filters by a tag attached to the entity. It can target a simple key or a key:value pair (e.g. tag("ENV:PROD")).
• entityName(): filters by the entity name.
• not(): the negation operator, to explicitly exclude certain entities.

3. The golden design rule (scaling) #

To ensure optimal performance and simpler maintenance, a strict architectural rule must be followed in your configurations.

Ban rigid IDs #

Golden rule (scaling): For each selection rule, you must define either an Entity ID (unique technical identifier) or an Entity type.

Best practice for production: Fixed Entity IDs should be avoided in production, because this approach is too specific and rigid, and does not survive a resource being redeployed. To manage at scale, compatible with the dynamic life cycle of your infrastructure, use only the Entity type (e.g. type("HOST")) combined with dynamic attributes or tags.

Secondary criteria #

• type("ENTITY"): specifies the item type (e.g. HOST, SERVICE, CONTAINER_GROUP_INSTANCE).
• entityName(...): filters on the resource's display name.
• tag(...): isolates items carrying specific keys/values.
• healthState(...): filters by current health state (HEALTHY, UNHEALTHY).
• entityAttribute(...): evaluates intrinsic system properties of the entity.

Text and semantic operators #

Performance tip: Use operators in this order to optimize response time: first equals or in (the fastest), then startsWith or endsWith. Use contains only as a last resort, because it is very resource-intensive.

4. Practical examples: advanced combination scenarios #

Here are some frequent use cases illustrating the power of combining selectors.

Scenario A: target production, excluding a sub-project #

You want to select all production hosts, but exclude those dedicated to load testing:

type("HOST"),tag("ENV:PROD"),not(tag("PROJECT:LOADTEST"))

Scenario B: grouping microservices #

You want to isolate all services related to the payment system running in the Kubernetes ecosystem:

type("SERVICE"),entityName("EasytravelService")

Scenario C: target a team's technology processes #

You want to list all process groups managed by the Backend team that run Java:

type("PROCESS_GROUP"),tag("Owner:Backend"),softwareTechnologies("Java")

Scenario D: isolate web applications by region #

Select the web applications (RUM) deployed for the European region:

type("APPLICATION"),property("Region:EMEA")

Scenario E: target specific databases #

Select all Oracle database services in production:

type("SERVICE"),property("db_type:oracle"),tag("ENV:PROD")

Scenario F: cloud hosts in a specific region #

Filter virtual machines hosted on AWS in the 'eu-west-1' region. Using the cloudType property is more robust than a tag because Dynatrace detects it automatically.

type("HOST"),cloudType("EC2"),tag("Region:eu-west-1")

Scenario G: Kubernetes worker nodes #

Isolate only the worker nodes of your production Kubernetes cluster:

type("KUBERNETES_NODE"),tag("Role:worker"),tag("ENV:PROD")

Scenario H: exclude entities under maintenance #

Select all active services of your infrastructure, explicitly excluding those marked with a maintenance tag:

type("SERVICE"),not(tag("Status:Maintenance"))

Scenario I: filter within an existing management zone #

Target only the hosts that already belong to an 'MZ_Finance' management zone to refine an alert:

type("HOST"),mzName("MZ_Finance")

Scenario J: group mobile applications #

You want to isolate all your mobile applications running on iOS. The osType property is extracted directly by Dynatrace and is therefore more reliable than a manual tag.

type("MOBILE_APPLICATION"),osType("IOS")

Scenario K: target several entity types with the 'in' operator #

Select both hosts and process groups that share the 'ENV:PROD' tag:

type.in("HOST","PROCESS_GROUP"),tag("ENV:PROD")

Scenario L: case-insensitive search with 'caseSensitive' #

Find a specific service without worrying about the exact case of its name:

type("SERVICE"),entityName.equals("frontend-api", caseSensitive:false)

Scenario M: check that a tag exists with 'exists' #

Isolate all hosts on which the 'Owner' tag has been defined, whatever its value:

type("HOST"),tag.exists("Owner")

Scenario N: isolate alerting entities with 'healthState' #

Target only the production services that currently have a problem (unhealthy state):

type("SERVICE"),tag("ENV:PROD"),healthState("UNHEALTHY")

Scenario O: topology and dependencies with 'toRelationships.calls' #

Select all services that call an Oracle database service:

type("SERVICE"),toRelationships.calls(type("SERVICE"),tag("ENV:PROD"))

5. How-to: validating the rule with cURL #

You must validate your selectors through the API before deploying them in critical management zone or alerting rules.

Querying the Entities API v2 #

The /api/v2/entities endpoint is used to list the entities matching an entity selector.

Expert tip: URL encoding
This often-forgotten step causes HTTP 400 errors. Your selector contains special characters (double quotes ", commas ,, or spaces) that must be URL-encoded. For example, double quotes " become %22 and spaces become %20. Use tools or commands that can encode the string before sending it to the API.

Validation example with cURL #

Here is the command to safely test the selector type("HOST"),tag("ENV:PROD") (URL-encoded):

curl -X GET "https://{VOTRE_ENV}.live.dynatrace.com/api/v2/entities?entitySelector=type(%22HOST%22),tag(%22ENV:PROD%22)" \
  -H "accept: application/json" \
  -H "Authorization: Api-Token dt0c01.VOTRE_TOKEN..."

Analyze the totalCount section and the entities array of the returned JSON to check that the targeting is correct.

6. Assessment and self-check #

Take a moment to check your overall understanding of the concepts covered.

Self-assessment mini-quiz #

• Question 1: What is the minimal, mandatory condition for an entity selector to be valid according to the golden rule?
• Question 2: How do you link several conditions to form a logical 'AND' query?
• Question 3: Which URL-encoded character replaces the double quote (") that is essential in your REST API queries?

Answers:
1. Explicitly contain a type() or an entityId().
2. Simply by using a comma (,) between each condition.
3. The code %22.