Contact UsGet started

Recording rules

Written by
Updated at December 4, 2024

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 computation highlights

  • Yandex Managed Service for Prometheus® uses a global computation delay of 2 minutes to coordinate recording rules with the results of read requests. This means that the rules are applied 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 limit on the number of series as a result of rule computation is 1,000. The maximum limit value is 10,000.

Requirements for recording rules

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

Note

The file name may contain lowercase Latin letters, numbers, hyphens, and underscores. The file 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 is represented by REST resources located at https://monitoring.api.cloud.yandex.net/prometheus/workspaces/<workspace_ID>/extensions/v1/rules.

To start executing requests:

  1. Install cURL.
  2. Authenticate in the API.
  3. Create a workspace and copy its ID to 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. Go to the Recording rules tab.
  4. If you have no uploaded 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 as Base64 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 groups of rules are deleted when replacing a file, they will no longer be computed. All new rules and groups of rules will start to be computed.

Viewing a list of files

  1. On the Monitoring page, select Prometheus on the left.
  2. Select a workspace.
  3. Go 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"

Response example:

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

Viewing the 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"

Response example:

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

Viewing file computation status

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

You can get the computation status for any rule in all file groups by using the snapshots REST resource. Each snapshot contains information about the status, error, rule name, and computation 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"

Response example:

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

Possible rule states:

  • NOT_EVALUATED_YET: File is uploaded but computation has not started yet.
  • OK: Computation successful.
  • LIMIT_EXCEEDED: Number of time series returned by the rule exceeds the limit specified in the YAML file. For such rules, partial computation result is not saved.
  • TIMEOUT: Rule computation timed out.
  • UNEXPECTED_RESULT_TYPE: Unexpected computation 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.

© 2024 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