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

Supported versions

• Dynatrace SaaS or Managed version 1.187 or later

  • Versions < 2.0.0 are compatible with Akamas until version 1.8.0

  • Versions >= 2.0.0 are compatible with Akamas from version 1.9.0

Supported component types

• Linux

  • Ubuntu-16.04, Rhel-7.6

• JVM

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

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

• Web Application

• Kubernetes and Docker

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

Prerequisites

• a valid Dynatrace license

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

• Connectivity between:

  • Akamas server and Dynatrace server over port 443 (if Dynatrace is deployed on-premises)

  • Akamas server and internet (over https) if Dynatrace is managed as a SaaS platform

• URL (+ port if it is not the default one) of your Dynatrace server (SaaS or Managed)

• API token from your Dynatrace server (Saas or Managed) with the rights to "Access problems and event feed, metrics, and topology" - see more details

• A Dynatrace user belonging to the group "Monitoring viewer", which allows access to the environment in read-only mode, without being able to change settings, download or install OneAgent

Permissions

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

• metrics.read (Read entities)

• entities.read (Read metrics)

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

• DataImport (Data ingest, e.g.: metrics and events)

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

Component configuration

To map metrics collected from Dynatrace to Akamas component, the Dynatrace provider looks up some properties in the components of a system grouped under dynatrace.

These properties give you access to different strategies to map Akamas components onto Dynatrace entities:

• Map by id

• Map by name

• Map by tags

Map 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:

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) require to drill down into the host entities to get the PROCESS_GROUP_INSTANCE or PROCESS_GROUP id

Map by name

You can map a component to a Dynatrace entity by leveraging the entity’s display name which you should put under the name property in the component definition:

Map 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 all instances matching any of the specified tags will be selected.

In the case of a key-only tag, the example above would be:

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.

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

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

Kubernetes specific properties

A set of Kubernetes-specific properties can be used to allow users to retrieve data related to the monitored Kubernetes clusters.

Please note, that the property type is required to retrieve Kubernetes entities. Currently, the supported types in Dynatrace are the following

The following Kubernetes object can be retrieved from Dynatrace.

Container

The following properties are supported for containers:

Example

Pod

The following properties are supported for pods

Example