Configuring Dynatrace Observer jobs

Using the Dynatrace Observer, you can query a specified Dynatrace environment for information about its applications, services, process groups, and infrastructure entities.

Before you begin

Important: The Dynatrace Observer supports Dynatrace cloud, SaaS and Dynatrace onPrem v1.182.102.

Ensure you generate a Dynatrace token to access your Dynatrace environment. You also need topology access scope to access the Dynatrace resources.

Ensure you have the Dynatrace access details to hand, such as Dynatrace API URL and API token.

Enabling access to the URL routes

To access the URL routes for the topology Swagger documentation, see the Enabling access to URL routes topic.

About this task

You define and start the following job.

Dynatrace Load job

A transient (one-off) job that loads all requested Dynatrace resource data.

By default, Load jobs are one-off, transient jobs that do a full upload of all requested topology data as soon as they are triggered.

You can also run these jobs (again) from the Observer UI, or schedule them to run at set times when configuring them.

Notice: Dynatrace v1 API endpoints are no longer supported.

Procedure

Define or edit the following parameters, then click Run job to save and run the job.

Encryption requirement: See the Configuring observer jobs security topic for more information.

Dynatrace Observer job parameters

Parameter Action Details
Unique ID Enter a unique name for the job Required
Data tenant Data tenant is used to track your data. It needs to be unique for each job or else it will override the previously discovered data. Required
Base URL Specify the API URL of the Dynatrace endpoint (including version). An example of a Dynatrace cloud-based URL is: https://< your-environment-id >.live.dynatrace.com/api/v2/, while an example of a Dynatrace managed or onPrem URL is: https://< your-domain >/e/< your-environment-id >/api/v2/ Required
Dynatrace API Token Enter the Dynatrace token for authentication Required
Enable/Disable Secure Connection to CSO's host Select to either enable or disable a secure connection to the CSO's host. Set to true to secure the connection, or false to bypass it. Required
The entitySelectors for the Dynatrace v2 API The format is {"taskname" : "entitySelector"}, and multiple tasks can be added to the entitySelector list.
The taskname (string, required) is a user defined value that identifies each task uniquely.
The entitySelector defines the scope of the query. Only entities matching the scope and criteria will be discovered. Separate each filter of entitySelector with ';' and place its value inside parentheses '( )'. For a filter that supports a list, separate the values using a comma ','. For more entitySelector information, see more details and example below this table.
Required
Edge Capture Direction Choose to display either a one-directional or bi-directional edge topology. A (default) bi-directional direction uses both FromRelationships and ToRelationships edges when displaying the Dynatrace relationship, while a one-directional direction uses only FromRelationships edges. Tip: If the Dynatrace relationship is bi-directional, the observer will use both FromRelationships and ToRelationships between A and B, and also between B and A, and therefore both edges will be displayed in a bi-directional edge topology. If the Dynatrace relationship is one-directional, the observer will use FromRelationships from host A to host B, and also FromRelationships from host B to host A. Optional
Number of records to be fetched per page Number of records to be fetched per page. Maximum value is 4000 and minimum is 1. Optional. Default value is 4000.
Relationship mapping for dynatrace with ASM Observer relationship to be used for Dynatrace relationship. The user can use edge mapping values to also override the default values Optional. Observer will use a default mapping for edges.
Entity mapping for dynatrace with ASM Observer entity types to be used for Dynatrace entity type. Observer will use a default mapping for entity. The user can use entity mapping values to also override the default values. Optional. If there is no default value then Dynatrace entity type will be used as ASM entity type.
Grouping vertex preference The observer creates the defined topology for the discovered vertices based on the preference in this field. Optional. Value can be host or none.
- Default value is none, which indicates that no resource groups are created.
- When host is selected, resource groups are created with the host as seed and its connected entities, except other hosts, as members.
Certificate validation Option for SSL validation. Turning SSL validation off will use HTTPS without host verification. Optional
Trust all certificates by bypassing certificate verification Trust all certificates without validating the certificate's contents. Required. Default value is true.
Connection timeout (milliseconds) Set the connection timeout in milliseconds. Optional. The default is 5000ms.
Read timeout (milliseconds) Set the read timeout in milliseconds. Optional. The default is 5000ms.
Proxy Host Specify the proxy host to connect to. Optional
Proxy Port Specify the proxy port, defaults to 8080. Optional
Target system certificate Specify a certificate by name to load into the trustStore. Optional. To obtain authentication certificates using OpenSSL and store them as secrets, see Configuring observer job security.
Proxy Username Specify the proxy user name to connect. Set for basic auth proxy. Optional
Proxy Password Specify the password for the proxy user (if Proxy Username has been specified). Optional. Use plain text.
Proxy Secure Specify whether to connect to the proxy in secure mode. Set to True for HTTPS proxy. Optional. The default is 'false'.
Access scope Enter text to provide a scope for the resources. Access scope can help map alerts to resources when resources in different scopes share the same parameters, such as matchTokens. Optional. Tip: You can define access scope for locations, project names, namespaces, etc.
Generate debug support file Set this parameter to 'True' in order to capture the output of the next scheduled job run as a file. This file will be stored with an observer's log files and can be used to debug observer issues, for example at the request of your designated support team, or while using a test environment. For one-off jobs (that is, Load jobs), this parameter reverts to 'False' after the next completed run. To examine the output produced, you can load the generated debug file using the File Observer. Optional
Observer job description Enter additional information to describe the job Optional
Job schedule Specify when the job runs Optional. Load jobs only.

Note: For the Grouping vertex preference job parameter, when host is selected for creating resource groups, the host unique ID is set as the seed during the processing of the host API response. Connected entities from the response (excluding connected hosts) are used as the members of the created resource group. In Dynatrace, entities like application, service, process and even custom data can be part of several hosts.

Dynatrace API entitySelector parameters and examples:

Examples:

Single task example:

{
"HostTask": "type(host);entityId(HOST-E9B8C2EF21BA5217,HOST-B343896535B69B84,HOST-F4A80CBC1027416A);timeframe(now-10m);fields(properties.osType,properties.hypervisorType)"
}

Multiple tasks example:

{
"HostTask":"type(host);timeframe(now-10m);fields(properties)",
"AppTask":"type(application);timeframe(now-10m);fields(properties)",
"ServiceTask":"type(service_instance);timeframe(now-10m);fields(properties)",
"ProcessTask":"type(process_group_instance);timeframe(now-10m);fields(properties)"
}

Parameters:

  • ! (negation): For example !entityName(eur01.ibm.com)
  • type (string, required): Each task can only accept one type. You must set this criteria in the entitySelector. Negation is not supported by type.
  • mzName (string, list, optional): Management zone name of the entity
  • mzId (string, list, optional): Management zone id of the entity
  • entityName (string, list, optional): Name of the entity
  • (wildcards): For example the string "type(host);entityName(eur0*);..." will fetch all of the hosts that start with an entityName of 'eur0', such as 'eur01.ibm.com,eur02.ibm.com', etc; while the string "type(host);entityName(*eur0*);..." will fetch all hosts that contain 'eur0' as part of their entityName parameters, such as ibm.eur0.com,ibm.eur02.com, etc.
  • entityId (string, list, optional): Id of the entity
  • tag (string, list, optional): Tags of the entity
  • state (string, list, optional, case-sensitive): State of the entity
  • excludeRelationsWith: Excludes the connectivity with the listed entity type. Negation is not supported.
  • timeframe (string, optional): Time frame of the entity. The time frame should be a minimum of 5m and a maximum of 24h. The format is timeframe-NU, where 'N' is the amount of time, and 'U' is the unit of time. The default is '(now-5m)'. Supported time units for the relative time frame are 'm' (minutes), and 'h' (hours). For a setting of timeframe-1hr, the observer filters out if the lastSeenTms is within one hour of the observer job's start time, and only model those resources.
  • fields (string, list, optional): Entity fields that will be added to the entity vertex