> For the complete documentation index, see [llms.txt](https://docs.akamas.io/akamas-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akamas.io/akamas-docs/integrating/integrating-telemetry-providers/custom-metrics/create-custom-metrics-telemetry-instances.md).

# 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.akamas.io/akamas-docs/integrating/integrating-telemetry-providers/custom-metrics/create-custom-metrics-telemetry-instances.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.