Create Dynatrace telemetry instances

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:

Field	Type	Value restrictions	Required	Default Value	Description
url	String	It should be a valid URL	Yes		The URL of the Dynatrace installation API (see the official reference)
verifySSL	Boolean		No	True	wether to verify the authenticity of the SSL certificate when connecting to Dynatrace via https
token	String		Yes		The Dynatrace API Token the provider should use to interact with Dynatrace. The token should have sufficient permissions.
proxy	Object	See Proxy options reference	No		The specification of the HTTP proxy to use to communicate with Dynatrace.
pushEvents	String	true, false	No	true	If set to true the provider will inform dynatrace of the configuration change event which will be visible in the Dynatrace UI.
tags	Object		No		A set of global tags to match Dynatrace entities. The provider uses these tags to apply a default filtering of Dynatrace entities for every component.
pageSize	Integer	0-1000	No	1000	The number of entities to retrieve for each paged request
retryAttempts	Integer	1-1000	No	8	The number of times the provider retries to communicate with Dynatrae APIs when receiving a temporary error response
retrySleep	Integer	1-300	No	5	The nuber of seconds to wait before retrying a request to Dynatrace that received a temporary error code as response
maxIdsPerEntity	Integer	0-1000	No	0 (No limit)	Limits the number of dynatrace entities that can be associated to a component during the extraction. If a limit is set metrics would be aggregated only on those Dynatrace entities.
maxExtractionTime	Integer	0-1440	No	0 (No Limit)	Limit the metrics extraction to the last minutes of the trial. This is particularly useful when running very long trials (e.g. days) and you are only interesed in importing the last period.
kubernetes	Object		No		A set of properties to be used when extracting entities runnign on a kubernetes cluster. These will be matched with dynatrace entities metadata (see below)

Kubernetes options reference

This table reports the reference for the kubernetes property section within the definition of the Dynatrace provider instance. These properties are used to identify which Dynatrace entities to import based on the metadata of the corresponding kubernetes elements (e.g. pod name, cluster id, namespace...) The set of specific properties that can be used depend on the kind of Dynatrace instances.

Container

Containers are identified on Dynatrace by entities of type CONTAINER_GROUP_INSTANCE. The following properties can be used for these entities.

Property name	Corresponding Dynatrace Metadata
namespace	KUBERNETES_NAMESPACE
containerName	KUBERNETES_CONTAINER_NAME
basePodName	KUBERNETES_BASE_POD_NAME
clusterId	KUBERNETES_CLUSTER_ID

Deployments

Namespace

Cluster

Processes

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:

Field	Type	Value Restrictions	Required	Default value	Description
metric	String	It must be an Akamas metric	Yes		The name of an Akamas metric that should map to the new metric you want to gather
datasourceMetric	String	A valid Dynatrace metric	Yes		The Dynatrace query to use to extract metric
labels	Array of strings	-	No		The list of Dynatrace labels that should be retained when gathering the metric
staticLabels	Key-Value	-	No		Static labels that will be attached to metric samples
aggregation	String	see Dynatrace metric aggregations	No	avg	The aggregation to perform if the mergeEntities property under the extras section is set to true
extras	Object	Only the parameter mergeEntities can be defined to either true or false	No		Section for additional properties

Proxy options reference

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

Field	Type	Value restrictions	Required	Default value	Description
address	String	It should be a valid URL	Yes		The URL of the HTTP proxy to use to communicate with the Dynatrace installation API
port	Number (integer)	1 <port<65535	Yes		The port at which the HTTP proxy listens for connections
username	String		No		The username to use when authenticating against the HTTP proxy, if necessary
password	String		No		The username to use when authenticating against the HTTP proxy, if necessary

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