# Metric template

Metrics are defined using a YAML manifest with the following structure:

{% code lineNumbers="true" %}

```yaml
metrics:
  - name: "cpu_util"
    description: "cpu utilization"
    unit: "percent"
  - name: "mem_util"
    description: "memory utilization"
    unit: "percent"
```

{% endcode %}

and properties:

| Field         | Type   | Value restrictions                                                                                | Is required | Default Value   | Description                             |
| ------------- | ------ | ------------------------------------------------------------------------------------------------- | ----------- | --------------- | --------------------------------------- |
| `name`        | string | No spaces are allowed                                                                             | TRUE        | <p><br><br></p> | The name of the metric                  |
| `unit`        | string | A supported unit or a custom unit (see [supported units of measure](#supported-units-of-measure)) |             |                 | The unit of measure of the metric       |
| `description` | string |                                                                                                   | TRUE        | <p><br><br></p> | A description characterizing the metric |

### Supported units of measure

The supported units of measure for metrics are:

| Type                 | Units                            |
| -------------------- | -------------------------------- |
| Temporal units       | 6db756124ebc4604be5cba70e0f2f505 |
|                      |                                  |
| nanoseconds          |                                  |
| microseconds         |                                  |
| milliseconds         |                                  |
| seconds              |                                  |
| minutes              |                                  |
| hours                |                                  |
| Units of information | 5f5cb1f2518a48448393c0cebf438c95 |
|                      |                                  |
| bits                 |                                  |
| kilobits             |                                  |
| megabits             |                                  |
| gigabit              |                                  |
| terabit              |                                  |
| petabit              |                                  |
| bytes                |                                  |
| kilobytes            |                                  |
| megabytes            |                                  |
| gigabytes            |                                  |
| terabytes            |                                  |
| petabytes            |                                  |
| Others               | percent                          |

{% hint style="warning" %}
Notice that supported units of measure are automatically scaled for visualization purposes. In particular, for units of information, Akamas uses a base 2 scaling for bytes, i.e., 1 kilobyte = 1024 bytes, 1 megabyte = 1024 kilobytes, and so on. Other units of measure are only scaled up using millions or billions (e.g., 124000000 custom units become 124 Mln custom units).
{% endhint %}

### Choosing the correct metric unit

The most important thing when designing custom optimization packs is to choose the correct unit of measure for every metric. In the previous paragraph you were given a full listing of the supported units of measure and the way they are scaled by Akamas UI (e.g. you may notice that, when viewing study or optimization charts memory bytes are scaled to megabytes or gigabytes, whenever needed). There is another scaling involved and this happens inside telemetry providers. Akamas integrates with several telemetry providers (such as Neoload, Loadrunner, Dynatrace, etc). The purpose of these Akamas providers is to mask the differences between scaling units used by the various telemetry providers (again: Neoload, Loadrunner, etc) and to perform a specific scaling on these measures in order to guarantee that all metrics are homogeneous when they are finally fed to the Akamas engine.

Let's take Akamas provider for Dynatrace, for example. Here's a snippet of the internal metrics mapping between Dynatrace and Akamas:

```yaml
- metric: requests_response_time
  datasourceMetric: builtin:service.response.time
  scale: 0.001
- metric: requests_error_rate
  datasourceMetric: builtin:service.errors.total.rate
  scale: 0.01
```

This means that values coming from Dynatrace metric `builtin:service.response.time` will be mapped to Akamas metric `requests_response_time` but since Dynatrace returns microseconds with that metric, Akamas provider code will scale it multiplying by `0.001` to convert it to nanoseconds. Similarly, values coming from Dynatrace metric `builtin:service.errors.total.rate` which are percent values but range from 0 to 100, must be scaled (scale factor is `0,01`) in order to convert them to domain `[0.0, 1.0]` used by Akamas

So when designing a custom optimization pack you should make sure that:

* memory unit is `bytes`
* cpu unit is `CPUs` when real hardware is involved
* cpu unit is `millicores` when docker/Kubernetes containers are involved
* cpu utilization unit is `percent` (100% being 1.00)
* throughput unit is XXX/sec (e.g.: `bytes/sec`, `responses/sec`, `collections/sec`)
* temporal unit for CPU-related metrics is `nanoseconds`
* temporal unit for web-related metrics is `milliseconds`
* temporal unit for human-related metric is `seconds` (unless otherwise noted by the telemetry provider)