> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automaticrostering.visma.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Metrics

> Track roster metrics while a roster is being generated.

Metrics let you show users how a roster is developing while the solver runs.

Each metric is an aggregate for the current roster. The returned `scope` matches the scope you requested, which makes it straightforward to associate a value with the metric shown in your user interface.

<Info>
  A metric value is `null` until the solver publishes its first metrics update, or when the selected scope has no value.
</Info>

## Scope metrics with rule labels

A metric scope is defined by its `metricKey` and, optionally, its `ruleLabel`:

<Info>
  `ruleLabel` can only be used for metrics based on labeled rules.
</Info>

* With only a `metricKey`, the service aggregates that metric across every rule of the relevant type.
* With both a `metricKey` and `ruleLabel`, it aggregates only rules of that type that have the exact, case-sensitive label.

This lets you track a meaningful business measure rather than every instance of a rule type. For example, label each Period Distribution rule that limits weekend work with `maximum-weekend-amount`, then request `PERIOD_DISTRIBUTION.EXCESSIVE_WORKED_PERIODS` with that label. The result is the total number of excessive weekend periods across all matching rules.

```json title="Track excessive weekend periods" theme={null}
{
  "metricKey": "PERIOD_DISTRIBUTION.EXCESSIVE_WORKED_PERIODS",
  "ruleLabel": "maximum-weekend-amount"
}
```

## Track and show metrics

<Steps>
  <Step title="Choose the metrics to track">
    Add each metric scope to `statusOptions.metricScopes` in your `POST /roster/start` request. A scope can track a metric across all matching rules, or use `ruleLabel` to limit it to a labeled group of rules.

    ```json title="Add status options to the roster start request" theme={null}
    {
      "statusOptions": {
        "metricScopes": [
          {
            "metricKey": "UTILIZATION.MINUTES_BELOW_IDEAL",
            "ruleLabel": "weekly-hours"
          },
          {
            "metricKey": "PERIODIC_REST.CONTINUOUS_REST_VIOLATIONS"
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Start the roster job">
    Send the roster start request and retain the returned `jobId`. The service creates one status-metric entry for every requested scope.
  </Step>

  <Step title="Poll the job status">
    Call `GET /roster/status/{jobId}` while the job runs. Each response contains the latest values in the `metrics` array, using the same scopes you requested.

    ```json title="Metrics returned when checking job status" theme={null}
    {
      "jobId": "7a608c99-8d91-4ab7-bd66-5561ad2c0c09",
      "status": "running",
      "hasResult": true,
      "metrics": [
        {
          "scope": {
            "metricKey": "UTILIZATION.MINUTES_BELOW_IDEAL",
            "ruleLabel": "weekly-hours"
          },
          "value": 120
        },
        {
          "scope": {
            "metricKey": "PERIODIC_REST.CONTINUOUS_REST_VIOLATIONS"
          },
          "value": 2
        }
      ]
    }
    ```
  </Step>

  <Step title="Show progress to users">
    Match every returned `scope` to the metric in your interface and update its displayed value on each poll. Values will move as the solver improves the roster.
  </Step>
</Steps>

## Available metrics

| Metric key                                                                                   | Description                                                                        |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| <code className="whitespace-nowrap">AVAILABILITY.WORKED\_MINUTES</code>                      | Total minutes worked in the periods covered by Availability rules.                 |
| <code className="whitespace-nowrap">AVAILABILITY.ASSIGNMENTS</code>                          | Number of assignments relevant to Availability rules.                              |
| <code className="whitespace-nowrap">DEMAND.MISSING\_MINUTES\_TO\_MIN</code>                  | Total minutes missing below minimum demand.                                        |
| <code className="whitespace-nowrap">DEMAND.MISSING\_MINUTES\_TO\_IDEAL</code>                | Total minutes missing between minimum and ideal demand.                            |
| <code className="whitespace-nowrap">DEMAND.MISSING\_SHIFTS\_TO\_MIN</code>                   | Total shifts missing below minimum shift demand.                                   |
| <code className="whitespace-nowrap">DEMAND.MISSING\_SHIFTS\_TO\_IDEAL</code>                 | Total shifts missing between minimum and ideal shift demand.                       |
| <code className="whitespace-nowrap">COOLDOWN.MISSING\_DAYS</code>                            | Total number of required cooldown days that are missing.                           |
| <code className="whitespace-nowrap">COOLDOWN.MISSING\_MINUTES</code>                         | Total number of required cooldown minutes that are missing.                        |
| <code className="whitespace-nowrap">COOLDOWN.VIOLATIONS</code>                               | Number of cooldowns that are shorter than required.                                |
| <code className="whitespace-nowrap">CONSECUTIVE.MIN\_VIOLATIONS</code>                       | Number of consecutive-work groups that are shorter than the configured minimum.    |
| <code className="whitespace-nowrap">PATTERN.DESIRED\_COMPLETE\_MATCHES</code>                | Number of periods that completely match a desired pattern.                         |
| <code className="whitespace-nowrap">PATTERN.DESIRED\_PARTIAL\_MATCHES</code>                 | Number of periods that partially match a desired pattern.                          |
| <code className="whitespace-nowrap">PATTERN.DESIRED\_INCOMPLETE\_PERIODS</code>              | Number of periods that do not completely match a desired pattern.                  |
| <code className="whitespace-nowrap">PATTERN.UNDESIRED\_COMPLETE\_PERIODS</code>              | Number of periods that completely match an undesired pattern.                      |
| <code className="whitespace-nowrap">UTILIZATION.TOTAL\_MINUTES</code>                        | Total worked minutes counted by Utilization rules.                                 |
| <code className="whitespace-nowrap">UTILIZATION.MINUTES\_BELOW\_MIN</code>                   | Total minutes by which work falls below configured minimum-hour targets.           |
| <code className="whitespace-nowrap">UTILIZATION.MINUTES\_BELOW\_IDEAL</code>                 | Total minutes by which work falls below configured ideal-hour targets.             |
| <code className="whitespace-nowrap">UTILIZATION.MINUTES\_ABOVE\_IDEAL</code>                 | Total minutes by which work exceeds configured ideal-hour targets.                 |
| <code className="whitespace-nowrap">UTILIZATION.ASSIGNMENTS\_BELOW\_MIN</code>               | Total assignments by which work falls below configured minimum-shift targets.      |
| <code className="whitespace-nowrap">UTILIZATION.ASSIGNMENTS\_BELOW\_IDEAL</code>             | Total assignments by which work falls below configured ideal-shift targets.        |
| <code className="whitespace-nowrap">UTILIZATION.ASSIGNMENTS\_ABOVE\_IDEAL</code>             | Total assignments by which work exceeds configured ideal-shift targets.            |
| <code className="whitespace-nowrap">PERIOD\_DISTRIBUTION.WORKED\_PERIODS</code>              | Number of periods with at least one assignment.                                    |
| <code className="whitespace-nowrap">PERIOD\_DISTRIBUTION.MISSING\_WORKED\_PERIODS</code>     | Total number of required worked periods that are missing.                          |
| <code className="whitespace-nowrap">PERIOD\_DISTRIBUTION.EXCESSIVE\_WORKED\_PERIODS</code>   | Total number of worked periods above configured maximums.                          |
| <code className="whitespace-nowrap">PERIOD\_DISTRIBUTION.MAX\_CONSECUTIVE\_VIOLATIONS</code> | Total amount by which consecutive worked-period groups exceed their maximum.       |
| <code className="whitespace-nowrap">PERIOD\_DISTRIBUTION.MIN\_SURROUNDING\_VIOLATIONS</code> | Total number of required surrounding free periods that are missing.                |
| <code className="whitespace-nowrap">PERIODIC\_REST.CONTINUOUS\_REST\_VIOLATIONS</code>       | Number of employee-rule combinations that violate the continuous-rest requirement. |