Integrating with Dynatrace via API

Supported version

BMC Helix Intelligent Integrations supports version 1.307 of Dynatrace for data collection.​​​​

Before you begin

Review the following prerequisites to help you plan and configure a connection with Dynatrace.

Dynatrace requirements

To access the Dynatrace APIs required for data collection, generate an API token with the following scopes: 

• API v2:
  • entities.read
  • events.read
  • extensions.read
  • logs.read
  • metrics.read
  • networkZones.read
  • problems.read
  • releases.read
  • securityProblems.read
  • settings.read
  • slo.read
• API v1:
  • DataExport

For more information about tokens, see Dynatrace API - Tokens and authentication.

BMC Helix Intelligent Integrations requirements

• Depending on the location of the third-party product (SaaS, on-premises), choose one or more BMC Helix Intelligent Integrations deployment modes and review the corresponding port requirements. For information about various deployment modes and port requirements, see Deployment scenarios.
• Based on the deployment mode, use the BMC Helix Intelligent Integrations SaaS deployment or the BMC Helix Intelligent Integrations on-premises gateway or both. For more information about the gateway, see Deploying the BMC Helix Intelligent Integrations on-premises gateway.
• The on-premises gateway must be able to reach the third-party product on the required port (default value is 443).
• You have the latest Technology Knowledge Update (TKU) required to collect topology data.  
  To obtain the latest TKU, see Schedule and Roadmap.  
• In the pattern configuration for Dynatrace, set the create_nodes variable to true (default is false). 
  For information about setting the variable, see Configuring patterns in the UI. 

Task 1: To configure the connection with Dynatrace

1. To access BMC Helix Intelligent Integrations, perform one of the following steps depending on your deployment mode:

   • BMC Helix Intelligent Integrations SaaS – Log on to BMC Helix Portal, and click Launch on BMC Helix
     Intelligent Integrations.
   • BMC Helix Intelligent Integrations on-premises gateway – Use the following URL to access BMC Helix
     Intelligent Integrations: https://<hostName>:<portNumber>/swpui
2. On the CONNECTORS  tab, click in the SOURCES panel.

3. Click the Dynatrace tile. 

4. Specify the following details for the source connection:

   1. Specify a unique instance name.

      Success

      Best practice
      We recommend that you specify the instance name in the following format: 

      <sourceType>_<sourceControllerServerName>{_<InstanceQualifier>}                    

      The instance qualifier helps you to distinguish the multiple instances configured from the same source server. For example, you can name your instances as Dynatrace_Host_PROD, Dynatrace_Host_TEST, and so on.

   2. Specify the Dynatrace host name.
   3. Specify the Dynatrace HTTP or HTTPS port number, depending on the connection protocol (the default port number is 443).
   4. Select the HTTPS option to use an HTTPS connection to the Dynatrace host.
      Error

      Caution

      Do not select the Allow Unsigned Certificate option in a production environment. You can select this option to allow unsigned certificates in a test environment. To learn how to install SSL certificates, see the Dynatrace  documentation.

   5. Specify the number of maximum concurrent REST API requests that should be executed during a collection schedule (default value is 5).
   6. Specify the time, in seconds, after which no attempt should be made to establish a connection (default value is 30).

   7. Specify a valid token id to access the API. Make sure that the token has the required permissions to access the API. For more information, see Dynatrace API - Tokens and authentication.

   8. (On-premises only) The Environment ID is similar to the Account ID. Leave this field blank for SaaS implementations.
   9. Click Proxy and specify whether you want to configure a proxy server. If yes, specify the host name and port number (default value is 8888).
5. Click VALIDATE AND CREATE.
   The specified connection details are validated, and the corresponding source connection is created in the Source Connection list.

6. Select the source connection that you created from the list if it is not selected already.

   Warning

   Important

   The destination host connection is created and configured automatically when the source connection is created.

7. Make sure that you select the options for the required data types to collect data.

8. Configure the collectors for the selected data types by clicking the respective data type in the Collectors section. 

   Warning

   Important

   Depending on the Dynatrace API version you want to use for metrics collection and the type of metrics you want to collect, select one of the following options:

   • Dynatrace Managed Metrics: Depending on your selections in metric lists, such as metric categories, applications, and application tags, the Dynatrace Timeseries API v1 or Metrics API v2 is used to collect metrics, and the corresponding metrics are collected.
   • Dynatrace Managed V2 Metrics (Recommended): The Dyantrace Metrics API v2 to used to collect v2 metrics.

   Click here to view the collection parameters for the selected data types

   Important: The ✅️  symbol indicates that this field is applicable to the data type.

   Parameter name	Description	Data type
   		Dynatrace Managed Alerts	Dynatrace Managed Metrics	Dynatrace Managed V2 Metrics	Dynatrace Managed Tolology
   Collection Schedule	Specify the data collection frequency by using one of the following methods: Constantly, by specifying the schedule in minutes, hours, or days using the Duration option Default: 5 minutes Example: Collection Schedule is set to 5 mins. Current time is 00:30. If you run the collector just after 00:30, data is collected every 5 mins, first at 00:30 and next at 00:35, and so on.   Periodically, by specifying the schedule through a cron expression using the Cron schedule option  A cron expression is a string consisting of five subexpressions (fields) that describe individual details of the schedule.  These fields, separated by blank spaces, can contain any of the allowed values with various combinations of the allowed characters for that field. Default: */5 * * * * (evaluates to 5 minutes) Format: Minutes Hours (24-hour format) Day of Month Month Day of Week Example: If you specify 10 15 3 7 * , data is collected at 15:10 hours every third day in the month of July. For more information about how this parameter affects data collection,  see Data collection schedule.	✅️	✅️	✅️	✅️
   Data Collection Window	Specify the historical time period (in minutes) from the current time for which the data should be collected from Dynatrace .  Default: 5 minutes Example: Collection Schedule is set to 5 mins. Data Collection Window is set to 5 mins. Current time is 00:30. If you run the collector just after 00:30, data is collected first at 00:30 for the interval, 00:25 - 00:30, and next at 00:35 for the interval, 00:30 - 00:35, and so on. For more information about this parameter, see Data collection window.	✅️	✅️	✅️	✅️
   Data Latency	Specify the time (in minutes) by which the data time window should be shifted back on the timeline.  This parameter is useful in delayed data availability situations. Default: 60 minutes Example: Collection Schedule is set to 5 mins.  Data Collection Window is set to 10 mins. Data Latency is set to 2 mins.  Current time is 00:30. If you run the collector just after 00:30, data is collected first at 00:30 for the interval, 00:18 - 00:28, and next at 00:35 for the interval, 00:23 - 00:33, and so on. For more information about this parameter, see Data latency.	✅️	✅️	✅️	✅️
   Impacts	Select one or more alert impact statuses from the list.	✅️	❌️	❌️	❌️
   Severities	Select one or more alert severities from the list.	✅️	❌️	❌️	❌️
   Statuses	Select the alert status from the list.	✅️	❌️	❌️	❌️
   Metric Categories (Applicable only for API v1)	Select all or a subset of metric categories from the list. This list is updated automatically from Dynatrace.	❌️	✅️	❌️	❌️
   Application Tags and Applications	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for applications with specific tags or for all applications.​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored.   The Application Tags and Applications lists are updated automatically from Dynatrace. To collect metrics for the applications with tags, perform the following steps: Select tags from the Application Tags list. Important: Tags are meant only for restricting the number of applications to be displayed in the Applications list. Metrics are collected based on the applications you select in the Applications list. Remove the All Applications option from the Application Tags list. The Applications list is populated with the applications that have the selected tags. Do one of the following: Select the applications one by one for which you want to collect metrics. Select the Select All option to display the applications having the selected tags and then, remove All Applications from the list. Otherwise, the metrics for all the applications are collected. Important: If you select All Applications, the tags you have selected from the Application Tags list are not considered and metrics for all the applications are collected. To collect metrics for all applications​​​​, perform the following steps: Make sure that All Applications is selected in the Application Tags list. Make sure that All Applications is selected in the Applications list.	❌️	✅️	❌️	❌️
   Service Tags and Services	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for services with specific tags or for all services​​.​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Service Tags and Services lists are updated automatically from Dynatrace. To collect metrics for the services with tags, perform the following steps: Select tags from the Service Tags list. Note: Tags are meant only for restricting the number of services to be displayed in the Services list. Metrics are collected based on the services you select in the Services list. Remove the All Services option from the Service Tags list. The Services list is populated with the services that have the selected tags. Do one of the following: Select the services one by one for which you want to collect metrics. Select the Select All option to display services with the selected tags and then, remove All Services from the list. Otherwise, the metrics for all the services are collected. Important: If you select All Services, the tags you have selected from the Service Tags list are not considered and metrics for all the services are collected. To collect metrics for all services, perform the following steps: Make sure that All Services is selected in the Service Tags list. Make sure that All Services is selected in the Services list.	❌️	✅️	❌️	❌️
   Host Tags and Hosts	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for hosts with specific tags or for all hosts. If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Host Tags and Hosts lists are updated automatically from Dynatrace. To collect metrics for the hosts with tags, perform the following steps: Select tags from the Host Tags list. Note: Tags are meant only for restricting the number of hosts to be displayed in the Hosts list. Metrics are collected based on the hosts you select in the Hosts list. Remove the All Hosts option from the Host Tags list. The Host list is populated with the hosts that have the selected tags. Do one of the following: Select the hosts one by one for which you want to collect metrics. Select the Select All option to display hosts with the selected tags and then, remove All Hosts from the list. Otherwise, the metrics for all the hosts are collected. Important: If you select All Hosts , the tags you have selected from the Host Tags list are not considered and metrics for all the hosts are collected. To collect metrics for all hosts, perform the following steps: Make sure that All Hosts is selected in the Host Tags list. Make sure that All Hosts is selected in the Hosts list.	❌️	✅️	❌️	❌️
   Process Tags and Processes	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for processes with specific tags or for all processes​​.​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Process Tags and Processes lists are updated automatically from Dynatrace. To collect metrics for the processes with tags, perform the following steps: Select tags from the Process Tags list. Note: Tags are meant only for restricting the number of processes to be displayed in the Processes list. Metrics are collected based on the processes you select in the Processes list. Remove the All Processes option from the Process  Tags list. The Processes list is populated with the processes that have the selected tags. Do one of the following: Select the processes one by one for which you want to collect metrics. Select the Select All option to display processes with the selected tags and then, remove All Processes from the list. Otherwise, the metrics for all the processes are collected. Important: If you select All Processes , the tags you have selected from the Process Tags list are not considered and metrics for all the processes are collected. To collect metrics for all processes, perform the following steps: Make sure that All Processes is selected in the Process Tags list. Make sure that All Processes is selected in the Processes list.	❌️	✅️	❌️	❌️
   Process Group Tags and Process Groups	Depending on your selections in the Metric Categories and V2 Metrics lists, collect metrics for process groups with specific tags or for all process groups​.​​​​​​​ If you have selected any categories from the Metric Categories list, metrics are collected only for those categories. If you have selected any metrics from the V2 Metrics list, only those metrics are collected. If you have selected options from both lists, the selected metric categories are ignored. The Process Group Tags and Process Groups lists are updated automatically from Dynatrace. To collect metrics for the process groups with tags, perform the following steps: Select tags from the Process Group Tags list. Important: Tags are meant only for restricting the number of process groups to be displayed in the Process Groups list. Metrics are collected based on the process groups you select in the Process Groups list. Remove the All Process Groups option from the Process Group Tags list. The Process Groups list is populated with the process groups that have the selected tags. Do one of the following: Select the process groups one by one for which you want to collect metrics. Select the Select All option to display process groups with the selected tags and then, remove All Process Groups from the list. Otherwise, the metrics for all the process groups are collected. Important: If you select All Process Groups , the tags you have selected from the Process Group Tags list are not considered, and metrics for all the process groups are collected. To collect metrics for all process groups, perform the following steps: Make sure that All Process Groups is selected in the Process Group Tags list. Make sure that All Process Groups is selected in the Process Groups list.	❌️	✅️	❌️	❌️
   V2 Metrics (Applicable only for API v2)	Select all or a subset of v2 metrics from the list. If you don't select any metrics, data for all the v2 metrics is collected. This list is updated automatically from Dynatrace .	❌️	✅️	✅️	❌️
   Entity Types	Select all or a subset of entity types from the list. This list is updated automatically from Dynatrace.	❌️	❌️	✅️	✅️
   Management Zone Regex	Specify the regex for the management zones. Data is collected only for entities that belong to zones whose names match the specified regex. By default, data for all entities is collected if you leave the text box empty. Examples: To collect metrics only for entities that belong to a management zone, specify .*.  To collect metrics for entities that belong to the management zones whose names contain the strings Prod and QA, specify the regex as (?=.*Prod)(?=.*QA).*.  To collect metrics for entities that belong to the management zones whose names start with the string Prod, specify the regex as ^Prod.*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*Prod.* and ^(?!.*Prod).* together. The former regex collects metrics for entities that belong to management zones whose names contain the string Prod, while the latter regex collects metrics for entities that belong to management zones whose names do not contain the string Prod.	✅️	❌️	✅️	✅️
   Entity Tag Regex and Entity Name Regex	Use these parameters to collect metrics for the entities with specific tags or all entities (default). Specify the regex for the entity tags and entities. Perform the following steps to collect metrics for the entities with tags:​​​​​ Specify the regex for entity tags.  Important: Tags are meant only for restricting the number of entities to be evaluated for the Entity Regex text box. Metrics are collected based on the regex you specify in the Entity Regex list. Specify the regex for entities.​​​​​​	❌️	❌️	✅️	❌️

9. To create the required collector streams for the selected data types, click CREATE COLLECTORS.

10. Configure the distributors for the selected data types by clicking the respective data type in the Distributors section.

    Click here to view the distribution parameters for the selected data types

    Parameter name	Description	Dynatrace Managed Alerts	Dynatrace Managed Metrics	Dynatrace Managed V2 Metrics	Dynatrace Managed Topology
    Max Batching Size	Specify the maximum number of data items to send in a single POST request to the destination API. The batch size depends on the destination’s ability to buffer the incoming data. Default: 250	✅️	✅️	✅️	✅️
    Max Batching Delay	Specify the maximum time (in seconds) to wait before building and processing a batch. Default: 3 seconds	✅️	✅️	✅️	✅️
    Base Retry Delay	Specify the initial time (in seconds) for which to wait before retrying to build and process a batch. The waiting time increases in the following sequence: n1, n2, n3, and so on, where n indicates the number of seconds. Default: 2 seconds Example: Base Retry Delay is set to 2 seconds. Retry is performed after 2, 4, 8, 16, ... seconds.	✅️	✅️	✅️	✅️
    Max Intra-Retry Delay	Specify the maximum limit for the base retry delay.  Default: 60 seconds Example: Max Intra-Retry Delay is set to 60 seconds. Base Retry Delay is set to 2 seconds. Retries are performed 2, 4, 8, 16, 32,... seconds later.	✅️	✅️	✅️	✅️
    Max Retry Duration	Specify the total time for retrying a delivery. For REST destinations, a delivery is a batch of data items in one POST request.  Default: 5 minutes Example: Max Retry Duration is set to 8 hours. Base Retry Delay is set to 2 seconds. Requests are sent for 2+4+8+16+32+64+132... until 8 hours in total duration is reached. After that, no subsequent attempts are made to retry the delivery. The assumption here is that if there is an outage or other issue with the destination tool, recovery should take less than the value of the Max Retry Duration parameter to be completed.	✅️	✅️	✅️	✅️
    Attributes To Be Dropped When Updating Events	Specify the event attributes that you do not want to be updated in BMC Helix Operations Managementwhen events are updated.  For example, if you do not want an event's severity, source address, source category, and subcategory to be updated in BMC Helix Operations Management, you need to specify those attributes in a comma-separated format: severity,source_address,source_category,source_subcategory . Important: You can obtain the event attribute names in BMC Helix Operations Management, by exporting any event data in JSON, BAROC, XML, or CSV format . The exported file contains all attributes of the event data, and from there you can identify the attributes to be dropped.	✅️	✅️	✅️	✅️
    Device Filters and Metrics filtersDevice and Metrics filters help remove unwanted data and send only the required data to BMC Helix applications. The data is filtered by using the regular expression (regex) provided for device name, monitor name, monitor type, and metrics, and is sent to BMC Helix applications.
    Device Name Regex	Specify the regex for the device name. Metrics for devices whose names match the regex are sent to BMC Helix applications. Examples: To send data for the devices that contain the string Linux in their names, specify the regex as .*Linux.*. To send data for the devices that contain the string Cisco and Linux, specify the regex as (?=.*Cisco)(?=.*Linux).*. To send the data for the devices whose names start with the string Linux, specify the regex as ^Linux.*.  Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*Linux.* and ^(?!.*Linux).* together. The former regex sends metrics for the devices whose names contain the string Linux, while the latter regex sends metrics for the devices whose names do not contain the string Linux.	❌️	✅️	✅️	❌️
    Monitor Name Regex	Specify the regex for the monitor name. Metrics for the monitors whose names match the regex are sent to BMC Helix applications. Examples: To send data for the monitors that contain the string system in their names, specify the regex as .*system.*. To filter out the data for monitors that contain system in their name, specify the regex as ^(?!.*system).*. To send the data for monitors whose names start with the string system, specify the regex as ^system.*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*system.* and ^(?!.*system).* together. The former regex sends metrics for the monitors whose names contain the string system, while the latter regex sends metrics for the monitors whose names do not contain the string system.	❌️	✅️	✅️	❌️
    Monitor Type Regex	Specify the regex for the monitor type. Metrics are sent to BMC Helix applications for the monitor type that matches the regex. Examples: To send data for the monitor type that contains the string health, specify the regex as .*health.*. To send data for the monitor type that starts with the string health, specify the regex as ^health.*. To filter out the monitor type that contains the string health, specify the regex as ^(?!.*health).*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter, ^health.* and ^(?!.*health).* together. The former regex collects metrics for the monitor type whose names contain the string health, while the latter regex collects data for the monitor types whose names do not contain the string health.	❌️	✅️	✅️	❌️
    Metrics Regex	Specify the regex for the metrics. Metrics are sent to BMC Helix applications whose names match the regex. Examples: To send metrics that contain the string avg in their names, specify the regex as .*avg.*. To filter out the metrics that contain the string avg, specify the regex as ^(?!.*avg).*. To send metrics whose names start with the string avg, specify the regex as ^avg.*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter, .*avg.* and ^(?!.*avg).* together. The former regex sends metrics whose name contains the string avg, while the latter regex sends metrics whose name does not contain the string avg.	❌️	✅️	✅️	❌️
    Events FiltersEvents filters help remove unwanted data and send only the required events to BMC Helix applications. The data is filtered by using the regular expression (regex) provided for host, message, and detailed message and is sent to BMC Helix applications.
    Host Regex	Specify the regex for the host name. Events for the hosts whose names match the regex are sent to BMC Helix applications. Examples: To send data for the host name /inventory/pricing, specify the regex as ^/inventory/pricing$. To filter out data whose host name contains the string inventory, specify the regex as ^(?!.*inventory).*. To send the data for the host whose names start with the string inventory, specify the regex as ^inventory.*.  Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*(inventory).* and ^(?!.*inventory).* together. The former regex sends events for the hosts whose names contain the string inventory, while the latter regex sends events for the hosts whose names do not contain the string inventory.	✅️	❌️	❌️	❌️
    Message Regex	Specify the regex for the event message. Messages for the events that match the regex are sent to BMC Helix applications. Examples: To send events whose messages contain the string HRV alert, specify the regex as .*HRV alert*. To filter out the events whose message contains the string HRV alert, specify the regex as ^(?!.*HRV alert).*. To send events whose message starts with the string HRV alert, specify the regex as ^(HRV alert).*.  Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*HRV alert.* and ^(?!.*HRV alert).* together. The former regex sends events whose message contains the string HRV alert, while the latter regex sends events whose message do not contain the string HRV alert.	✅️	❌️	❌️	❌️
    Detailed Message Regex	Specify the regex for the detailed message. Detailed messages for the events that match the regex are sent to BMC Helix applications. Examples:​​ To send events whose detailed message contains the string ci_display_name: easyTravel-k8s, specify the regex as .*ci_display_name: easyTravel-k8s.*. To filter out the events whose detailed message contains the string ci_display_name: easyTravel-k8s, specify the regex as ^(?!.*ci_display_name: easyTravel-k8s).*. To send the events whose detailed message starts with the string ci_display_name: easyTravel-k8s, specify the regex as ^(ci_display_name: easyTravel-k8s).*. Important: If you are using multiple regex, make sure that the regex do not conflict. For example, do not enter .*ci_display_name: easyTravel-k8s.* and ^(?!.*ci_display_name: easyTravel-k8s).* together. The former regex sends events whose detailed message contains the string ci_display_name: easyTravel-k8s, while the latter regex sends events whose message do not contain the string ci_display_name: easyTravel-k8s.	✅️	❌️	❌️	❌️

11. Click CREATE DISTRIBUTORS to create the required distributor streams for the selected data types.

12. Click one of the following buttons:

    • SAVE STREAM: Click this button if you want to edit the integration details before creating the instance. After you save the stream, the connector that you just created is listed in the SOURCES panel. Move the slider to the right to start the data stream.
    • SAVE AND START STREAM: Click this button if you want to save the integration details and start receiving data immediately.

    Important
    For a data stream, the Run Latency (max/avg), Items (Avg per Run), and Last Run Status columns on the Streams page might show the status as No Runs during the data collection process. After completion of the process, these columns are updated with an appropriate status.

    For more information about data streams, see Managing data streams.