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.

Configuring Dynatrace Observer jobs

1. On the Observer jobs page, perform one of the following actions:

   To edit an existing job

   Open the List of options overflow menu next to the job and click View & edit.

   To create a new job

   Click Add a new job + and select the Dynatrace Observer tile.

2. Configure the following parameters, then click Save to save and run the job.

   Table 1. 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). Example of a Dynatrace cloud-based URL: https://<your-environment-id>.live.dynatrace.com/api/v2/ Example of a Dynatrace managed or onPrem URL: https://<your-domain>/e/<your-environment-id>/api/v2/	Required
   Dynatrace API Token	Enter the Dynatrace token for authentication.	Required. Use plain text.
   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.
   The entitySelectors for the Dynatrace v2 API	The format is {"taskname" : "entitySelector"}. 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 details and examples, see Dynatrace v2 API entitySelector parameters and examples.	Required
   Edge Capture Direction	Choose to display either a one-directional or bi-directional edge topology. bi-directional (default) Uses both FromRelationships and ToRelationships edges when displaying the Dynatrace relationship. one-directional Uses only FromRelationships edges when displaying the Dynatrace relationship. 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	Specify the number of records to be fetched per page. Maximum value is 4000 and minimum is 1.	Optional. The default value is 4000.
   Relationship mapping for Dynatrace with ASM	Observer relationship to be used for Dynatrace relationship. You can use edge mapping values to override the default values.	Optional. The observer will use a default mapping.
   Entity mapping for Dynatrace with ASM	Observer entity types to be used for Dynatrace entity type. The observer uses a default mapping for entity. You can use entity mapping values to override the default values	Optional. If there is no default value, the Dynatrace entity type will be used as ASM entity type.
   Grouping vertex preference	The observer creates the topology for the discovered vertices based on the preference you enter.	Optional. The default is host.
   Certificate validation	Option for SSL validation. Turning SSL validation off will use HTTPS without host verification,	Optional
   Trust all certificates by bypassing certificate verification	Set to true to allow connection to target environment without verification.	Required. The default is 'true'.
   Connection timeout (milliseconds)	Set the connection timeout in milliseconds.	Optional. The default is 5000.
   Read timeout (milliseconds)	Set the read timeout in milliseconds.	Optional. The default is 5000.
   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. On-prem Create and store the certificate in the ASM_HOME/security directory. OCP Obtain the authentication certificate using OpenSSL and store it as a secret.
   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 parameters, such as matchTokens.	Optional. Tip: You can define access scope for locations, project names, namespaces, and so on.
   Generate debug support file	Set the optional Generate debug support file parameter to True to capture the output of the next scheduled job run as a file. This file is 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. The file is saved to the following locations: On-premises $ASM_HOME/logs/<obs>-observer/ On OpenShift Container Platform /var/log/itsm/<obs>-observer	Optional
   Observer job description	Enter additional information to describe the job.	Optional
   Job schedule	Specify when the job should run, and whether it should run at regular intervals. By default the job runs immediately, and only once. Optionally you can specify a future date and time for the job to run, and then set it to run at regular intervals after that.	Optional. Transient (one-off) jobs only. If you set a job schedule, the run intervals must be at least 90 seconds apart. If you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.

   Dynatrace API entitySelector parameters and examples:

   Single task example

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

   Multiple task 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 is supported by using '!'

   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.
   • 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