# Dynatrace provider

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: <a href="#supported-component-types" id="supported-component-types"></a>

* Kubernetes and Docker
* Web Application
* Ubuntu-16.04, Rhel-7.6
* java-openjdk-8, java-openjdk-11
* java-ibm-j9vm-6, java-ibm-j9vm-8, java-eclipse-openj9-11

Refer to [Dynatrace provider metrics mapping](../../akamas-reference/telemetry-providers/dynatrace-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](#permissions).

### Dynatrace Token <a href="#permissions" id="permissions"></a>

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](https://www.dynatrace.com/support/help/extend-dynatrace/dynatrace-api/basics/dynatrace-api-authentication).

## 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 <a href="#map-by-id" id="map-by-id"></a>

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:

{% code lineNumbers="true" %}
```yaml
name: My Host
properties:
 dynatrace:
  id: HOST-12345YUAB1
```
{% endcode %}

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.

### By name <a href="#map-by-name" id="map-by-name"></a>

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:

{% code lineNumbers="true" %}
```yaml
name: MyComponent
properties:
 dynatrace:
  name: host-1
```
{% endcode %}

### By tags <a href="#map-by-tags" id="map-by-tags"></a>

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`

{% code lineNumbers="true" %}
```yaml
name: MyComponent
properties:
 dynatrace:
  tags:
     environment: test
     [AWS]dynatrace-monitored: true
```
{% endcode %}

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

{% code lineNumbers="true" %}
```yaml
name: MyComponent
properties:
 dynatrace:
  tags:
     myKeyOnlyTag: ""
```
{% endcode %}

### By Kubernetes properties <a href="#improve-component-mapping-with-type" id="improve-component-mapping-with-type"></a>

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

### Container <a href="#container" id="container"></a>

In order 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.

| Akamas property | Dynatrace property        | Location            |
| --------------- | ------------------------- | ------------------- |
| namespace       | Kubernetes namespace      | Container dashboard |
| containerName   | Kubernetes container name | Container dashboard |
| basePodName     | Kubernetes base pod name  | Container dashboard |

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

<figure><img src="https://1840531935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC1d2wNp5yTa9gnHgSILG%2Fuploads%2Fgit-blob-b6538a3a299ab627414a5fd3732ffb7abcd0f5ac%2Fe845f4b6-a190-4ddc-9a32-0a974e771ae3.png?alt=media" alt=""><figcaption></figcaption></figure>

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

<pre class="language-yaml" data-line-numbers><code class="lang-yaml">dynatrace:
  type: CONTAINER_GROUP_INSTANCE
<strong>  kubernetes:
</strong>    namespace: boutique
    containerName: server
    basePodName: ak-frontend-*
</code></pre>

### Pod <a href="#pod" id="pod"></a>

In order 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.

| Akamas property | Dynatrace property | Location      |
| --------------- | ------------------ | ------------- |
| state           | State              | Pod dashboard |
| namespace       | Namespace          | Pod dashboard |
| workload        | Workload           | Pod dashboard |

If you need to further narrow your pod selection 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 <a href="#example.1" id="example.1"></a>

<figure><img src="https://1840531935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC1d2wNp5yTa9gnHgSILG%2Fuploads%2Fgit-blob-b78ad4f9a6ca447d13fc3af0fd49cb1d3ae40cbd%2F60e5ab80-ffa7-405b-a383-2f786631a83b.png?alt=media" alt=""><figcaption></figcaption></figure>

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

{% code lineNumbers="true" %}
```yaml
dynatrace:
  type: CLOUD_APPLICATION_INSTANCE
  namePrefix: ak-frontend-
  kubernetes:
    labels:
      workload: ak-frontend
      product: hipstershop
```
{% endcode %}

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

| Kubernetes type  | Dynatrace type                |
| ---------------- | ----------------------------- |
| Docker container | CONTAINER\_GROUP\_INSTANCE    |
| Pod              | CLOUD\_APPLICATION\_INSTANCE  |
| Workload         | CLOUD\_APPLICATION            |
| Namespace        | CLOUD\_APPLICATION\_NAMESPACE |
| Cluster          | KUBERNETES\_CLUSTER           |

## Improve component mapping with type <a href="#improve-component-mapping-with-type" id="improve-component-mapping-with-type"></a>

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.

{% code lineNumbers="true" %}
```yaml
name: MyComponent
properties:
 dynatrace:
  type: SERVICE     # here the type helps the mapping by tags by filtering down entities that are only services
  tags:
     environment: test
     "[AWS]dynatrace-monitored": true
```
{% endcode %}

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

<figure><img src="https://1840531935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC1d2wNp5yTa9gnHgSILG%2Fuploads%2Fgit-blob-f2967bc7c8bc967ec8f80aab02c44194c2a6aaa4%2Fimage-20220120-152125.png?alt=media" alt=""><figcaption></figcaption></figure>

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

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