Install the Telemetry Provider

Skip this part if the Telemetry Provider is already installed.

To install the Dynatrace provider, create a YAML file (called provider.yml in this example) with the definition of the provider:

Then you can install the provider using the Akamas CLI:

The installed provider is shared with all users of your Akamas installation and can monitor many different systems, by configuring appropriate telemetry provider instances.

To create an instance of the Dynatrace provider, build a YAML file (instance.yml in this example) with the definition of the instance:

# Dynatrace Telemetry Provider Instance
provider: Dynatrace
config:
  url: https://wuy711522.live.dynatrace.com
  token: XbERgThisIsAnExampleToken

Then you can create the instance for the system using the Akamas CLI:

akamas create telemetry-instance instance.yml system

Configuration options

When you create an instance of the Dynatrace provider, you should specify some configuration information to allow the provider to correctly extract and process metrics from Dynatrace.

You can specify configuration information within the config part of the YAML of the instance definition.

Required properties

• url - URL of the Dynatrace installation API (see https://www.dynatrace.com/support/help/extend-dynatrace/dynatrace-api/ to retrieve the URL of your installation)

• token - A Dynatrace API Token with the proper permissions

Collect additional metrics

You can collect additional metrics with the Dynatrace provider by using the metrics field:

config:
  url: https://wuy71982.live.dynatrace.com
  token: XbERgkKeLgVfDI2SDwI0h
metrics:
- metric: "akamas_metric"                     # extra akamas metrics to monitor
  datasourceMetric: builtin:host:new_metric   # query to execute to extract the metric
  labels:
  - "method"      # the "method" label will be retained within akamas

Configure a proxy for Dynatrace

In the case in which Akamas cannot reach directly your Dynatrace installation, you can configure an HTTP proxy by using the proxy field:

config:
  url: https://wuy71982.live.dynatrace.com
  token: XbERgkKeLgVfDI2SDwI0h
  proxy:
    address: https://dynaproxy  # the URL of the HTTP proxy
    port: 9999                  # the port the proxy listens to

Telemetry instance reference

This section reports the complete reference for the definition of a telemetry instance.

provider: Dynatrace  # this is an instance of the <name> provider
config:
  url: https://wuy71982.live.dynatrace.com
  token: XbERgkKeLgVfDI2SDwI0h
  proxy:
    address: https://dynaproxy # the URL of the HTTP proxy
    port: 9999            # the port the proxy listens to
    username: myusername  # http basic auth username if necessary
    password: mypassword  # http basic auth password if necessary
  tags:
    Environment: Test       # dynatrace tags to be matched for every component

metrics:
- metric: "cpu_usage"  # this is the name of the metric within Akamas
  # The Dynatrace metric name
  datasourceMetric: "builtin:host.cpu.usage"
  extras:
    mergeEntities: true  # instruct the telemetry to aggregate the metric over multiple entities
  aggregation: avg  # The aggregation to perform if the mergeEntities property is set to true

This table shows the reference for the config section within the definition of the Dynatrace provider instance:

Proxy options reference

This table reports the reference for the config → proxy section within the definition of the Dynatrace provider instance:

Metrics options reference

This table reports the reference for the metrics section within the definition of the Dynatrace provider instance. The section contains a collection of objects with the following properties:

Use cases

This section reports common use cases addressed by this provider.

Collect system metrics

Check the Linux optimization pack for a list of all the system metrics available in Akamas.

As a first step to start extracting metrics from Dyntrace, generate your API token and make sure it has the right permissions.

As a second step, choose a strategy to map your Linux component (MyLinuxComponent) with the corresponding Dyntrace entity.

Let’s assume you want to map by id your Dynatrace entity, you can find the id in the URL bar of a Dyntrace dashboard of the entity:

Grab the id and add it to the Linux component definition:

name: MyLinuxComponent
description: this is a Linux component
properties:
  dynatrace:
    id: HOST-A987D45512ABCEEE

You can leverage the name of the entity as well:

name: MyLinuxComponent
description: this is a Linux component
properties:
  dynatrace:
    name: Host1

As a third and final step, once the component is all set, you can create an instance of the Dynatrace provider and then build your first studies:

name: Dynatrace
config:
  url: https://my_dyna_installation_url
  token: MY_DYNA_TOKEN

The Dynatrace provider collects metrics from Dynatrace and makes them available to Akamas.

This provider includes support for several technologies. In any case, custom queries can be defined to gather the desired metrics.

Supported versions

Dynatrace SaaS/Managed version 1.187 or later

Supported component types:

• Kubernetes and Docker

• Web Application

• Ubuntu-16.04, Rhel-7.6

• java-openjdk-8, java-openjdk-11, java-openjdk-17

• java-ibm-j9vm-6, java-ibm-j9vm-8, java-eclipse-openj9-11

Refer to Dynatrace provider metrics mapping to see how component-types metrics are extracted by this provider.

Prerequisites

This section provides the minimum requirements that you should match before using the Prometheus provider.

• Dynatrace SaaS/Managed version 1.187 or later

• A valid Dynatrace license

• Dynatrace OneAgent installed on the servers where the Dynatrace entities to be monitored are running

• Connectivity between Akamas and the Dynatrace server on port 443

• A Dynatrace API token with the privileges described here.

Dynatrace Token

The Dynatrace provider needs a Dynatrace API token with the following privileges:

• metrics.read (Read metrics)

• entities.read (Read entities and tags)

• DataExport (Access problem and event feed, metrics, and topology)

• ReadSyntheticData (Read synthetic monitors, locations, and nodes)

• DataImport (Data ingest, e.g.: metrics and events). This permission is used to inform Dynatrace about configuration changes.

To generate an API Token for your Dynatrace installation you can follow these steps.

Component configuration

To instruct Akamas from which Dynatrace entities (e.g. Workloads, Services, Process Groups) metrics should be collected you can some specific properties on components.

Different strategies can be used to map Dynatrace entities to Akamas components:

• By id

• By name

• By tags

• By Kubernetes properties

By id

You can map a component to a Dynatrace entity by leveraging the unique id of the entity, which you should put under the id property in the component. This strategy is best used for long-lived instances whose ID does not change during the optimization such as Hosts, Process Groups, or Services.

Here is an example of how to setup host monitoring via id:

name: My Host
properties:
 dynatrace:
  id: HOST-12345YUAB1

You can find the id of a Dynatrace entity by looking at the URL of a Dynatrace dashboard relative to the entity. Watch out that the "host" key is valid only for Linux components, other components (e.g. the JVM) must drill down into the host entities to get the PROCESS_GROUP_INSTANCE or PROCESS_GROUP id.

By name

You can map a component to a Dynatrace entity by leveraging the entity’s display name. This strategy is similar to the map by id but provides a more friendly way to identify the mapped entity. Beware that id multiple entities in your Dynatrace installation share the same name they will all be mapped to the same component. The Dynatrace display name should be put under the name property in the component definition:

name: MyComponent
properties:
 dynatrace:
  name: host-1

By tags

You can map a component to a Dynatrace entity by leveraging Dynatrace tags that match the entity, tags which you should put under the tags property in the component definition.

If multiple tags are specified, instances matching any of the specified tags will be selected.

This sample configuration maps to the component all Dynatrace entities with tag environment: test or [AWS]dynatrace-monitored: true

name: MyComponent
properties:
 dynatrace:
  tags:
     environment: test
     [AWS]dynatrace-monitored: true

Dynatrace supports both key-value and key-only tags. Key-only tags can be specified as Key-value tags with an empty value as in the following example

name: MyComponent
properties:
 dynatrace:
  tags:
     myKeyOnlyTag: ""

By Kubernetes properties

By leveraging dedicated properties, you can map a component to a Dynatrace entity referring to a Kubernetes cluster (e.g., a Pod or a Container).

Container

To properly identify the set of containers to be mapped, you can specify the following properties. Any container matching all the properties will be mapped to the component.

You can retrieve all the information to setup the properties on the top of the Dynatrace container dashboard.

The following example shows how to map a component to a container running in Kubernetes:

dynatrace:
  type: CONTAINER_GROUP_INSTANCE
  kubernetes:
    namespace: boutique
    containerName: server
    basePodName: ak-frontend-*

Pod

To properly identify the set of pods to be mapped, you can specify the following properties. Any pod matching all the properties will be mapped to the component.

If you need to narrow your pod selection further you can also specify a set of tags as described in the by tags. Note that tags for Kubernetes resources are called Labels in the Dynatrace dashboard.

Labels are specified as key-value in the Akamas configuration. In Dynatrace’s dashboard key and value are separated by a column (:)

Example

The following example shows how to map a component to a pod running in Kubernetes:

dynatrace:
  type: CLOUD_APPLICATION_INSTANCE
  namePrefix: ak-frontend-
  kubernetes:
    labels:
      workload: ak-frontend
      product: hipstershop

Container, Pod, or Workload?

Please note, that when you are mapping components to Kubernetes entities the property type is required to instruct Akamas on which type of entity you want to map. Dynatrace maps Kubernetes entities to the following types:

Improve component mapping with type

You can improve the matching of components with Dynatrace by adding a type property in the component definition, this property will help the provider match only those Dynatrace entities of the given type.

name: MyComponent
properties:
 dynatrace:
  type: SERVICE     # the type helps the mapping by tags by filtering down entities that are only services
  tags:
     environment: test
     "[AWS]dynatrace-monitored": true

The type of an entity can be retrieved from the URL of the entity’s dashboard

Available entity types can be retrieved, from your Dynatrace instance, with the following command:

curl 'https://<Your Dynatrace host>/api/v2/entityTypes/?pageSize=500' \
  --header 'Authorization: Api-Token <API-TOKEN>'

Mapping multiple entities in one component

In some circumstances, you might want to map multiple Dyantrace entities (e.g. a set of hosts) to the same Akamas component and import aggregated metrics.

This can be easily done by using tags. If Akamas detects that multiple entities have been mapped to the same component it will try to aggregate metrics; some metrics, however, can not be automatically aggregated.

To force aggregation on all available metrics you can add the mergeable: trueproperty to the component under the Dynatrace element.

name: MyComponent
properties:
 dynatrace:
  mergeable: true
  tags:
     environment: test
     [AWS]dynatrace-monitored: true

By default, only requests at the service level are imported by the telemetry provider.

To import specific key requests you can follow these steps.

Component Creation

Create a new component of type Web Application for each key request you want to import. This allows tracking response time, throughput, and error rates separately.

You can use the following yaml file as an example and customize it to suit your needs.

name: KeyRequestA
description: The key request A for my application
componentType: Web Application
properties:
 dynatrace: 
  type: SERVICE_METHOD
  id: SERVICE_METHOD-D4BCC949D5DD656A

In order to instruct Akamas to import a specific key request you just need to change the id field of the yaml above to the one that matches your key request on Dynatarce.

To obtain that ID open the analysis page for the request as in the example below, take note of the URL of the page, and look for the SERVICE_METHOD keyword. The id is the one starting with SERVICE_METHOD and ending before the character %14

Considering the example below the id is SERVICE_METHOD-D4BCC949D5DD656A

Telemetry instance setup

Create a telemetry instance for your system using the yaml specified below as an example and modify it to provide your Dynatrace account and credentials. This will instruct Akamas to use key request metrics instead of service metrics.

provider: Dynatrace
config:
 url: https://<my-account>.dynatrace.com/
 token: <my-token>
metrics:
  - metric: requests_response_time
    datasourceMetric: builtin:service.keyRequest.response.time
    scale: 0.001    
    defaultValue: 0.0
    staticLabels:
      provider: dynatrace
  - metric: requests_throughput
    datasourceMetric: builtin:service.keyRequest.errors.server.successCount
    scale: 0.0166666666666666666666666666666
    defaultValue: 0.0
    staticLabels:
      provider: dynatrace        
  - metric: requests_error_rate
    datasourceMetric: builtin:service.keyRequest.errors.server.rate
    scale: 0.01
    defaultValue: 0.0
    staticLabels:
      provider: dynatrace