> For the complete documentation index, see [llms.txt](https://intuitem.gitbook.io/ciso-assistant/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://intuitem.gitbook.io/ciso-assistant/guides/getting-started/first-computed-metric.md).

# Creating your first computed metric

Turn two metrics you already track into a training coverage rate, read it, change its formula safely, and derive a status level from it

This walkthrough takes about ten minutes. You will combine two metrics you already track into a training coverage rate, check its history before saving, read the result, try a change to its formula, and turn the rate into a status level.

You need two numeric metric instances with a few samples, in the same domain or under a common parent. The example uses *Employees trained · Spain* and *Headcount · Spain*, both monthly, in the *ACME Spain* domain. You also need the right to create metric instances and metric definitions in that domain.

## 1. Select the two metrics

1. Open **Metrology > Metric instances**.
2. Tick *Employees trained · Spain* first, then *Headcount · Spain*. The order matters: the first metric will be divided by the second.
3. In the bar that appears above the list, click **Compute from selection**.

<figure><img src="https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-d851832f88c92bbbb503594d175565f69a25b1ff%2Fmetrics-compute-from-selection.png?alt=media" alt="Two metrics ticked in the metric instances list, with Compute from selection in the selection bar"><figcaption><p>Tick the metrics, then Compute from selection</p></figcaption></figure>

The **New computed metric** window opens with both metrics under **Metrics to combine**, in the order you ticked them. Each one has a name the formula can use: `employees_trained` and `headcount`.

## 2. Write the formula

1. Under **Formula**, next to **Start from:**, click **Ratio (%)**. The formula becomes `employees_trained * 100.0 / headcount`.
2. Leave the formula unrounded. The number of decimals shown is a setting of the metric, not part of the formula: a percentage shows one decimal unless you set **Decimals** otherwise, and the stored value keeps its precision.

The **Latest result** box on the right computes it as you type: the current rate, how it moved since last month, a chart of the last twelve months and the last four values. Check them against what you expect before going further. Nothing is saved yet.

<figure><img src="https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-502a00baca3aaa30e99072f73f2df476054b865e%2Fmetrics-compose-modal.png?alt=media" alt="The New computed metric window with the two metrics, the ratio formula, the latest result at 89.08 percent with its chart, and the name and domain filled in"><figcaption><p>The result, with its history, before anything is saved</p></figcaption></figure>

## 3. Name it and create it

1. **Name**: *Training coverage · Spain*.
2. **Domain** is already *ACME Spain*: the lowest domain holding both metrics. **Collection frequency** is already **Monthly**, taken from the metrics you picked.
3. **Unit**: **Percentage**. **Target value**: `90`. **Direction**: **Higher is better**, since a rise in coverage is good news.
4. Click **Create metric**.

The new metric's page opens. Within a few seconds its whole history is computed, one value per month since the first sample of its inputs, and the page fills in by itself.

<figure><img src="https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-35d45f3eb8528ff7c5dc5a43b876feb2b8dcd831%2Fmetrics-instance-page.png?alt=media" alt="The Training coverage · Spain page: current value 89.1 percent, a timeline over the past year, and the Use in a formula, Edit formula and Refresh now buttons"><figcaption><p>1 current value, 2 timeline, 3 Use in a formula, 4 Edit formula, 5 Refresh now</p></figcaption></figure>

A metric definition named *Training coverage · Spain* was created along with it. Nobody needs to enter samples: the metric recomputes every month, and on demand with **Refresh now**.

## 4. Try a change, safely

Suppose the 20 trainers in the headcount should not count as trained.

1. Click **Edit formula**. A drawer opens beside the page.
2. Change the formula to `(employees_trained - 20) * 100.0 / headcount`.
3. Look at the chart under **Latest result**: the dashed line is what the metric holds now, the solid line what it would hold with your formula.

<figure><img src="https://629777851-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCqFeU3oPCgDWkkR386NK%2Fuploads%2Fgit-blob-60ac1a4f3c6811b6ad5762e65364d7ff46119df2%2Fmetrics-drawer.png?alt=media" alt="The formula drawer: the edited formula, and a chart with the current results dashed and the new ones solid"><figcaption><p>Every past month, before and after</p></figcaption></figure>

Saving would recompute every past month with the new formula, as the note above **Save** says. To keep the metric as it is, click **Cancel**, then **Discard**. To keep the change, click **Save**: the drawer closes and the page updates once the computation is done.

## 5. Turn the rate into a status

A level reads better on a dashboard than a percentage: *On track* or *Behind*.

1. On *Training coverage · Spain*, click **Use in a formula**. The window opens with the metric already picked and its name, `training_coverage_spain`, in the formula.
2. Next to **Result**, choose **Level**.
3. Write `training_coverage_spain < 90.0 ? "Behind" : "On track"`. The **Levels** box fills with *Behind*, then *On track*, in the order the texts appear.
4. Check the order: worst first, best last. With the direction **Higher is better**, the last level is the best, so moving up to *On track* shows as good news. Drag a level to change the order.
5. Name it *Training status · Spain* and click **Create metric**.

The status recomputes whenever the coverage does. Both metrics can go on a [dashboard](/ciso-assistant/features/dashboards.md).

## Next steps

* [Create a computed metric](/ciso-assistant/features/metrics/creating.md): every option of the window.
* [Edit a formula](/ciso-assistant/features/metrics/editing.md): what a save changes when other metrics share a definition.
* [Formula reference](/ciso-assistant/features/metrics/formulas.md): missing values, `previous`, functions and levels.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://intuitem.gitbook.io/ciso-assistant/guides/getting-started/first-computed-metric.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.