Contact UsGet started

Recording rules

Written by
Updated at April 28, 2025

Recording rules allow you to compute new values based on the obtained metrics and save them as time series. This helps to configure data analysis to meet your needs and optimize Yandex Managed Service for Prometheus® performance.

Rule evaluation highlights

  • Yandex Managed Service for Prometheus® uses a two-minute global evaluation delay to keep recording rules in sync with read query results. This means that the rules take effect two minutes after the data arrives. It allows all metrics collection agents to transmit the data before it is read by Yandex Managed Service for Prometheus® and recorded as a result of applying the recording rules.

  • The default series limit for rule evaluation results is 1,000. The maximum limit value is 10,000.

Requirements for recording rules

In Prometheus, you can upload your custom files with recording rules. It supports all fields described in the YAML file specification.

Note

The file name can only contain Latin letters, numbers, dots, hyphens, and underscores. It may be up to 256 characters long. The group name may not be longer than 256 characters.

You can manage recording rule files via the management console or API.

Pre-configuration for using the API

The API consists of REST resources available at https://monitoring.api.cloud.yandex.net/prometheus/workspaces/<workspace_ID>/extensions/v1/rules.

To start running requests:

  1. Install cURL.
  2. Authenticate with the API.
  3. Create a workspace and copy its ID to then use it in the request address.

Adding or replacing a recording rule file

  1. On the Monitoring page, select Prometheus on the left.
  2. Select or create a workspace.
  3. Navigate to the Recording rules tab.
  4. If you have not uploaded any files yet, click Add file and select a .yml file with rules.
  5. To add another file, click Add file.
  6. To replace the existing file, click > Replace file to its right.

  1. Encode the file contents to Base64 as defined in RFC 4648:

    cat recording-rule.yaml

# groups:
#   - name: example
#     rules:
#     - record: example
#       expr: up

base64 -i recording-rule.yaml

# Z3JvdXBzOgogIC0gbmFtZTogZXhhbXBsZQogICAgcnVsZXM6CiAgICAtIHJlY29yZDogZXhhbXBsZQogICAgICBleHByOiB1cA==

  2. Save the result as a JSON file:

    body.json

    {
    "name": "recording-rules",
    "content" : "Z3JvdXBzOgogIC0gbmFtZTogZXhhbXBsZQogICAgcnVsZXM6CiAgICAtIHJlY29yZDogZXhhbXBsZQogICAgICBleHByOiB1cA=="
}

  3. Create or replace a recording rule file:

    export IAM_TOKEN=<IAM_token>

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data "@body.json" \
  "https://monitoring.api.cloud.yandex.net/prometheus/workspaces/<workspace_ID>/extensions/v1/rules"

If the request is successful, you will get the 204 HTTP code, if not, the error text.

If any rules or rule groups are deleted when replacing a file, they will no longer be evaluated. Evaluation will now cover all new rules and rule groups.

Viewing a list of files

  1. On the Monitoring page, select Prometheus on the left.
  2. Select a workspace.
  3. Navigate to the Recording rules tab.

Run this request:

export IAM_TOKEN=<IAM_token>

curl \
  --request GET \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://monitoring.api.cloud.yandex.net/prometheus/workspaces/<workspace_ID>/extensions/v1/rules"

Here is a response example:

{
  "files": [
    "recording-rules"
  ]
}

Viewing file contents

  1. On the Monitoring page, select Prometheus on the left.
  2. Select a workspace.
  3. Go to the Recording rules tab.
  4. To the right of the file, click > File code.

Run this request:

export IAM_TOKEN=<IAM_token>

curl \
  --request GET \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://monitoring.api.cloud.yandex.net/prometheus/workspaces/<workspace_ID>/extensions/v1/rules/recording-rules"

Here is a response example:

{
  "name": "recording-rules",
  "content": "Z3JvdXBzOgogIC0gbmFtZTogZXhhbXBsZQogICAgcnVsZXM6CiAgICAtIHJlY29yZDogZXhhbXBsZQogICAgICBleHByOiB1cA=="
}

Checking file evaluation status

  1. On the Monitoring page, select Prometheus on the left.
  2. Select a workspace.
  3. Go to the Recording rules tab.
  4. Select the file with rules. On the page that opens, you will see the status of the latest evaluations for this rule.

You can get the evaluation info for any rule across all file groups by using the snapshots REST resource. Each snapshot contains information about the status, error, rule name, and evaluation time.

Run this request:

export IAM_TOKEN=<IAM_token>

curl \
  --request GET \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://monitoring.api.cloud.yandex.net/prometheus/workspaces/<workspace_ID>/extensions/v1/rules/recording-rules/snapshots"

Here is a response example:

{
  "snapshotByGroup": {
    "example": [
      {
        "state": "OK",
        "error": "",
        "evaluationTimeMs": 21,
        "evaluatedAtTimeEpochMs": 1710490243322,
        "record": "example"
      }
    ]
  }
}

Possible rule states:

  • NOT_EVALUATED_YET: File is uploaded but evaluation has not started yet.
  • OK: Rule is successfully evaluated.
  • LIMIT_EXCEEDED: Number of time series returned by the rule exceeds the limit specified in the YAML file. Partial evaluation results are not saved for such rules.
  • TIMEOUT: Rule evaluation timed out.
  • UNEXPECTED_RESULT_TYPE: Unexpected evaluation result, e.g., a string.
  • UNKNOWN_ERROR: Generic error not described by any of the above states.

Deleting a file

  1. On the Monitoring page, select Prometheus on the left.
  2. Select a workspace.
  3. Go to the Recording rules tab.
  4. To the right of the file, click > Delete.

Run this request:

export IAM_TOKEN=<IAM_token>

curl \
  --request DELETE \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://monitoring.api.cloud.yandex.net/prometheus/workspaces/<workspace_ID>/extensions/v1/rules/recording-rules"

Downloading a file

  1. On the Monitoring page, select Prometheus on the left.
  2. Select a workspace.
  3. Go to the Recording rules tab.
  4. To the left of the file, click > Download file.

© 2025 Linux Foundation. All rights reserved. The Linux Foundation owns and uses registered trademarks. For a list of Linux Foundation trademarks, see Trademark Usage.

Previous
Grafana
Next
Alerting rules