# 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:
```yaml
# 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:
```bash
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 to retrieve the URL of your installation)
* `token` - A Dynatrace API Token with the [proper permissions](/akamas-docs/integrating/integrating-telemetry-providers/dynatrace-provider.md#permissions)
#### Collect additional metrics
You can collect additional metrics with the Dynatrace provider by using the `metrics` field:
```yaml
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:
```yaml
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.
```yaml
provider: Dynatrace # this is an instance of the 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](https://www.dynatrace.com/support/help/extend-dynatrace/dynatrace-api/)) |
| `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](/akamas-docs/integrating/integrating-telemetry-providers/dynatrace-provider.md). |
| `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.
{% tabs %}
{% tab title="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 |
| {% endtab %} | |
{% tab title="Deployments" %}
Deployments are identified on Dynatrace by entities of type CLOUD\_APPLICATION and CLOUD\_APPLICATION\_INSTANCES. For these entities, the following properties can be used.
For CLOUD\_APPLICATION\_INSTANCE:
| Property name | Corresponding Dynatrace Metadata |
| ------------- | -------------------------------- |
| labels (map) | cloudApplicationLabels |
| state | cloudApplicationInstancePhase |
| workloadName | workloadName |
| namespace | namespaceName |
| resourceUid | resourceUid |
For CLOUD\_APPLICATION
| Property name | Corresponding Dynatrace Metadata |
| -------------- | -------------------------------- |
| detectedName | detectedName |
| resourceUid | resourceUid |
| deploymentType | cloudApplicationDeploymentTypes |
| namespace | namespaceName |
| labels (map) | cloudApplicationLabels |
| {% endtab %} | |
{% tab title="Namespace" %}
Namespaces are identified on Dynatrace by entities of type CLOUD\_APPLICATION\_NAMESPACE. The following properties can be used for these entities.
| Property name | Corresponding Dynatrace Metadata |
| ------------- | -------------------------------- |
| detectedName | detectedName |
| resourceUid | resourceUid |
| labels (map) | cloudApplicationLabels |
| {% endtab %} | |
{% tab title="Cluster" %}
Clusters are identified on Dynatrace by entities of type KUBERNETES\_CLUSTER. For these entities, the following properties can be used.
| Property name | Corresponding Dynatrace Metadata |
| -------------- | -------------------------------- |
| customizedName | customizedName |
| distribution | kubernetesDistribution |
| clusterId | kubernetesClusterId |
| {% endtab %} | |
{% tab title="Processes" %}
Processes running inside containers (e.g., JVMs) are identified on Dynatrace by entities of type PROCESS\_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 |
| {% endtab %} | |
| {% endtabs %} | |
#### 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](https://www.dynatrace.com/support/help/dynatrace-api/environment-api/metric-v2/metric-selector#aggregation) | 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](https://www.dynatrace.com/support/help/extend-dynatrace/dynatrace-api/basics/dynatrace-api-authentication/) 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:
```yaml
name: MyLinuxComponent
description: this is a Linux component
properties:
dynatrace:
id: HOST-A987D45512ABCEEE
```
You can leverage the name of the entity as well:
```yaml
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:
```yaml
name: Dynatrace
config:
url: https://my_dyna_installation_url
token: MY_DYNA_TOKEN
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.akamas.io/akamas-docs/integrating/integrating-telemetry-providers/dynatrace-provider/create-dynatrace-provider-instances.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.