# Create Custom Metrics telemetry instances

## Create a telemetry instance <a href="#create-a-telemetry-instance" id="create-a-telemetry-instance"></a>

Create a YAML file (e.g., `instance.yml`) to define the telemetry instance. This file includes the configuration parameters, the list of metrics to generate, and their corresponding generation functions. Here is an example:

```yaml
provider: custom metrics
config:
  samples: 10
metrics:
  - metric: cpu_used
    datasourceMetric: jvm;rand[100000000,500000000]
  - metric: mem_used
    datasourceMetric: jvm;rand[100000000,500000000]
```

To create the telemetry instance for the system `test-system`, use the Akamas CLI:

```bash
akamas create telemetry-instance instance.yml test-system
```

### Configuration options <a href="#configuration-options" id="configuration-options"></a>

The only available configuration option is `samples`: default value is 10 and is the number of samples that will be generated for each listed metric

### Metrics Section

This section defines all metrics to be generated, along with the generation function and its parameters. The format for a metric is:

```
  - metric: METRIC_NAME
    datasourceMetric: COMPONENT_NAME;FUNCTION[PARAM1,PARAM2]
```

* `METRIC_NAME`: Name of the metric as defined in the component.
* `COMPONENT_NAME`: Name of the component associated with the metric.
* `FUNCTION`: Function used to generate the values. See ["Available Functions"](#available-functions) for details.
* `PARAM1`, `PARAM2`: Parameters specific to the function.

### Available functions

#### Rand

Generates random values for the metric within a specified range (`PARAM1`, `PARAM2`).

```
  - metric: cpu_used
    datasourceMetric: jvm;rand[100000000,500000000]
```

This will generate random numbers for `jvm.cpu_used` between 100000000 and 500000000. It's important to take into account the correct units used. In this example it's nanocores and that's why those big number were used. If the range is not specified (e.g., `rand[]`), a default range of `[0,1]` will be used.

#### Parameter

This function retrieves the value of the specified parameter and multiplies its value buy a random noise factor given in the function. Example:

```
  - metric: mem_used
    datasourceMetric: jvm;parameter[jvm.jvm_newSize,0.25]
```

This calculates `jvm.mem_used` by applying a random noise of ±25% to the current value of `jvm.jvm_newSize`. If the noise factor is not specified (e.g., `parameter[component.param]`), a default noise factor of `0.0` will be used.

#### Formula

Allows the use of complex formulas for metric generation, such as those used in study goals. The formula will use parameter values from the current experiment.

```
  - metric: mem_util
    datasourceMetric: jvm;formula[100*jvm.jvm_newSize/jvm.jvm_maxNewSize]
```

This will retrieve the current experiment parameter values and replace the values in the formula, then it will assign the resulting value to metric jvm.mem\_util. Provide a valid formula or an error will be displayed in the provider instance logs

#### Fixed

With this function the value will be fixed and used as specified. It's not necessary to set the function name here.

```
  - metric: mem_util
    datasourceMetric: jvm;[1280000]
```

This will assign to metric jvm.mem\_util the fixed value 128000