Service detection rules

  • Dynatrace Classic
  • How-to guide
  • 15-min read

When monitoring with OneAgent, your deployed applications and related microservices are automatically detected by Dynatrace, based on specific properties of your application deployment and configuration, such as the application identifier, part of the URL, or the server name.

Attributes used for detection are marked with an asterisk ✱ on the service overview page, under Properties and tags.

In certain cases, the quality of data available to Dynatrace might be insufficient for high-precision service detection. To tailor out-of-the-box detection to your environment, you can create new rules or setup improvements.

Manage rule-based service detection

You can use transformation rules, for example, to remedy the following use cases:

  • If the web Application IDs contain the version or build date, you can define a rule that removes the build date/ID from the web application ID.

  • When server names are not properly defined in the underlying deployment (for example, with Apache HTTP or Nginx in AWS environments), you can define a stable web server name and therefore a stable cluster service containing all instances.

  • You can correct the misuse of the context root in the deployed application.

    A typical web server has a concept called the context root to separate services based on the URL. For some technologies, such as Node.js, the context root is not available or it's improperly defined. You can superimpose the context root, and create separate services for each of your applications, instead of a single service containing multiple applications.

  • You can ignore the port for service detection. This is helpful when the port is used dynamically, for example, in Node.js applications.

Additionally, the rules can be exported and imported from one environment to another.

Detection rules are evaluated from top to bottom, and the first matching rule applies, so be sure to place your rule in the correct position on the list.

Configure service detection rules via UI

You can configure service detection rules via the Dynatrace web UI.

Prerequisites

Familiarize yourself with the notion of a full and external (opaque) request.

Create a rule

When you define a new rule, depending on the configuration, the original services might get less traffic or no traffic at all. New monitoring data is then redirected according to the rule configuration, between the original and the newly detected services.

To define a new service detection rule via the Dynatrace web UI

  1. Go to Settings.
  2. Expand Service Detection and select a request type (Full web request rules or Full web service rules, or External web request rules or External web service rules).
  3. Select Add item and start configuring the parameters of the new rule.
    1. Type a Rule name.
    2. To change the service detection's behavior, enable at least one of the service identifier contributors, so that the rule's triggered.
    3. To target the rule application, in the Conditions section, configure restrictions related to—for example—a management zone, specific conditions, or the port.
  4. Select Save changes.

Modify a rule

When you modify a rule, some services might not be affected by it anymore. While historical data is available only for the previous service, all newly captured data is then associated with the new standalone service.

To edit an existing rule via the Dynatrace web UI

  1. Go to Settings.
  2. Expand Service Detection and select a request type (Full web request rules or Full web service rules, or External web request rules or External web service rules).
  3. Expand Expand row the row of the rule.
  4. Edit the rule settings.
  5. Select Save changes.

Delete a rule

If you delete a rule, all individual services are split and once again treated as standalone services.

To delete a service detection rule via the Dynatrace web UI

  1. Go to Settings.
  2. Expand Service Detection and select a request type (Full web request rules or Full web service rules, or External web request rules or External web service rules).
  3. In the Delete column for the corresponding rule row, select Delete row Remove

Configure service detection rules via Settings API

You can also configure service detection rules via the Settings API.

Prerequisites

List all rules

To get a list of existing rules via API, use a GET objects call. Specify the schema of your request type in the schemaIds query parameter.

GET /api/v2/settings/objects?schemaIds=builtin:service-detection.full-web-service

The response contains a list of existing service detection rules with their details, including the objectId, which is required to update or delete a service detection rule.

View a rule

To get details of a specific service detection rule (settings object) via API, use a GET objects call and specify the objectId of the rule you want to retrieve.

GET /api/v2/settings/objects/{objectId}

The response contains all details of the service detection rule, including its configuration and metadata, such as updateToken, which you can use to update the rule.

Create a rule

To create a new service detection rule (or a list of such rules) via API, use a POST request to the POST an object endpoint and specify the settings schema ID and the rule configuration in the request body.

POST /api/v2/settings/objects

Example JSON for a full web request rule:

[
  {
    "schemaId":"builtin:service-detection.full-web-request",
    "scope":"environment",
    "value":{
      "enabled":true,
      "name":"Detect Application,Application-1 as the same",
      "description":"Example: merge services",
      "managementZones":["-8445121454707515572"],
      "idContributors":{
        "applicationId":{
          "enableIdContributor":true,
          "serviceIdContributor":{
            "contributionType":"TransformValue",
            "transformations": [
              {
                "transformationType":"REMOVE_NUMBERS",
                "minDigitCount":1,
                "includeHexNumbers":false
              }
            ]
          }
        },
        "contextRoot":{
          "enableIdContributor":false
        },
        "serverName":{
          "enableIdContributor":false
        }
      },
      "conditions": [
        {
          "attribute":"ApplicationId",
          "compareOperationType":"StringStartsWith",
          "textValues": ["application"],
          "ignoreCase":false
        }
      ]
    }
  }
]

The response contains details of the created service detection rule, including its objectId.

[
  {
    "code": 200,
    "objectId": "vu9U3hXa3q0AAAABACpidWlsdGluOnNlcnZpY2UtZGV0ZWN0aW9uLmZ1bGwtd2ViLXJlcXVlc3QABnRlbmFudAAGdGVuYW50ACQ2MTY5Y2QwNy0xM2Y1LTMyMDAtODc4ZC1hNDljNTRiMmM4Mma-71TeFdrerQ",
  }
]

Modify a rule

To update an existing service detection rule via API, use a PUT request to the PUT an object endpoint. Specify the objectId of the rule you want to update in the URL path and the updated rule configuration in the request body.

PUT /api/v2/settings/objects/{objectId}

To get the current value of the service detection rule you want to modify, use a GET objects call. You can then create the JSON object for your update by modifying the response body.

We recommend using updateToken from the existing object, as it ensures proper versioning of your settings.

Example JSON for a full web request rule:

{
  "updateToken":"vu9U3hXY3q0ATAAkOWFiNGI2ZDAtYWFhNC00M2IwLWEzZDYtNDQ2OTZkNzIyYzE5ACRmMTA1NTJlMC01M2Q5LTExZWQtODAwMS0wMTAwMDAwMDAwMDO-71TeFdjerQ",
  "value":{
    "enabled":true,
    "name":"Detect Application, Application-1 as the same",
    "description":"Example: merge services",
    "managementZones":["-8445121454707515572"],
    "idContributors":{
      "applicationId":{
        "enableIdContributor":true,
        "serviceIdContributor":{
          "contributionType":"TransformValue",
          "transformations":[
            {
              "transformationType":"REMOVE_NUMBERS",
              "minDigitCount":1,
              "includeHexNumbers":false
            }
          ]
        }
      },
      "contextRoot":{
        "enableIdContributor":false
      },
      "serverName":{
        "enableIdContributor":false
      }
    },
    "conditions":[
      {
        "attribute":"ApplicationId",
        "compareOperationType":"StringStartsWith",
        "textValues":["application"],
        ///Added condition to ignore case sensitivity for texts.
        "ignoreCase":true
      }
    ]
  }
}

Delete a rule

To delete a service detection rule via API, use a DELETE request to the DELETE an object endpoint. Specify the objectId of the rule you want to delete in the URL path.

DELETE /api/v2/settings/objects/{objectId}

To get the objectId of the rule you want to delete, use a GET objects call.

Reorder rules

To change the evaluation order for your service detection rules, update each rule with the insertAfter or insertBefore field set to the object ID of the rule that should precede or follow it. To place the rule at the top of the rule list, leave insertAfter empty. To move it to the end of the rule list, add an empty insertBefore attribute.

[
  {
    "schemaId": "builtin:service-detection.full-web-request",
    "scope": "environment",
    "value": {
      "name": "New top rule",
      "...": "..."
    },
    "insertAfter": ""
  }
]

Service detection configuration examples

Separate fully monitored web request services based on URL or superimposed context root

For some technologies monitored by Dynatrace, the context root is not supported. A single service per process group is detected by default. You can change service detection by imposing a context root on a fully monitored web request.

In this example, when the URL path of a full web request starts with specific wording (blog/), we want to detect a service, whose ID will be transformed to the first segment of the URL.

Rule set-up
  1. Go to Settings.
  2. Expand Service Detection and select Full web request rules.
  3. In the full web request rules, select Add item.
  4. Configure the parameters as follows
    1. Enter a Rule name.
    2. Optional Enter a Description.
    3. Go to URL context root and turn on Transform this value before letting it contribute to the Service ID.
      1. From the Contribution type list, select Use transformed URL path.
      2. In Segments to copy from URL path, enter the number of segments of the URL to be kept (1).
    4. Go to Conditions and select Add item.
      1. From the Take the value of this attribute list, select URL path.
      2. From the Apply this operation list, select Starts with.
      3. Go to Values and select Add item, then enter blog/.
  5. Select Save changes.

Merge application data into a single service, based on the application ID value

When incoming data is volatile or not specific enough, you can use service detection rules to merge services, for example, Apache HTTP clusters in AWS without a proper virtual host or web application IDs containing the build date.

In this example, we want to merge in the same service all incoming data from applications whose ID starts with application.

Rule set-up
  1. Go to Settings.
  2. Expand Service Detection and select Full web request rules.
  3. In the full web request rules, select Add item.
  4. Configure the parameters as follows.
    1. Enter a Rule name.
    2. Optional Enter a Description.
    3. Select Set a management zone and choose the management zone for the list.
    4. Go to Application identifier and turn on Transform this value before letting it contribute to the Service ID.
      1. From the Contribution type list, select Use transformed value.
      2. Go to Transformations and select Add item.
        1. From the Transformation type list, select remove numbers.
        2. Enter a min digit count (1)
    5. Go to Conditions and select Add item.
      1. From the Take the value of this attribute list, select Application identifier.
      2. From the Apply this operation list, select Starts with.
      3. Go to Values and select Add item, then enter application.
  5. Select Save changes.

Separate services for “public network services” based on URL

In this example, when the top-level domain of an external web request ends with a specific wording (dynatrace.com), we want to detect a service, whose ID will be transformed to the first segment of the URL.

Rule set-up
  1. Go to Settings.
  2. Expand Service Detection and select External web request rules.
  3. In the external web request rules, select Add item.
  4. Configure the parameters as follows.
    1. Enter a Rule name.
    2. Optional Enter a Description.
    3. Go to URL context root and turn on Transform this value before letting it contribute to the Service ID.
      1. From the Contribution type list, select Use transformed URL path.
      2. In Segments to copy from URL path, enter the number of segments of the URL to be kept (1).
    4. Go to Public domain name and turn off Port.
    5. Go to Conditions and select Add item.
      1. From the Take the value of this attribute list, select Top level domain.
      2. From the Apply this operation drowpdown list, select Ends with.
      3. Go to Values and select Add item, then enter dynatrace.com.
      4. To ignore case sensitivity, turn on Ignore case.
  5. Select Save changes.

Separate services for “public network services” based on subdomains

If different endpoints shouldn’t be combined in the same service (for example, support.dynatrace.com and blog.dynatrace.com), you can instruct Dynatrace to detect multiple services from the same domain, based on the detected hostname instead of the request's domain name.

Rule set-up
  1. Go to Settings.
  2. Expand Service Detection and select External web request rules.
  3. In the external web request rules, select Add item.
  4. Configure the parameters as follows.
    1. Enter a Rule name.
    2. Optional Enter a Description.
    3. Go to Public domain name and turn on Transform this value before letting it contribute to the Service ID.
      1. From the Contribution type list, select Use the original value.
      2. Turn on Copy from host name.
      3. Turn off Port.
    4. Go to Conditions and select Add item.
      1. From the Take the value of this attribute list, select Top level domain.
      2. From the Apply this operation drowpdown list, select Ends with.
      3. Go to Values and select Add item, then enter dynatrace.com.
      4. To ignore case sensitivity, turn on Ignore case.
  5. Select Save changes.

Improve service detection

Web server naming issues

  • In some cases, web servers don't have well-defined virtual hosts, server names, or sites. A web server might simply be named localhost. This can result in multiple similar services that contain multiple website instances. To remedy such issues, adjust process-group detection settings.

  • When there is no virtual host configured on an Apache HTTP server, the web server name defaults to the name of the physical host. In cloud environments, this leads to one virtual host for each physical host instance and thus one service instance. If the cloud environment starts and stops the hosts, these services will be temporary.

    To remedy such localhost scenarios, use an environment variable to define virtual host names: set DT_LOCALTOVIRTUALHOSTNAME for each web server process to any value. Dynatrace will pick up the names and use them in place of the existing localhost virtual host names. With this approach, you ensure that multiple physical hosts report the same virtual host and thus get one service with multiple instances, one instance per physical host.

Define web application IDs

Some technologies don't provide unique application names. In such cases, you can define an environment variable called DT_APPLICATIONID to provide a unique name. This only impacts services of the respective process that don't already have application IDs. For Java applications, you can alternatively use the system property dynatrace.application.id.

Rotating and anonymous ports

Dynatrace takes the listen port of each web request service into account when naming and detecting requests. In some cases, these ports are meaningless or random, changing with each restart. This is especially true if you're using a load balancer that dynamically assigns ports to application processes, as is the case in many Node.js scenarios.

To remedy this, set environment variable DT_IGNOREDYNAMICPORT=true. This removes the port from detection and replaces it with *.

FAQ

If a service doesn't receive any new data after I create/edit/delete a rule, what happens to it?

When you create, edit, or delete a rule, data monitored after the change in service detection rules is aggregated and assigned to services, depending on the rule configuration. If a service stops receiving data, its historical data remains available (for example, for charting). You can still see the service and its traces in your environment.

Related topics

Related tags
Application ObservabilityServices Classic