Mapping rules

Mapping aggregation rules downsample in-memory metric data on the streaming ingest path before storing any results in the database—that is, before metric aggregation.

Downsampling requires the creation of two mapping rules:

  • A rule which performs the downsampling
  • A rule that deletes the raw metric

If you don't create a mapping rule to drop the raw metric, two metrics persist—one with the original resolution and one with the new resolution.

Mapping rules drop a given set of metrics by using the drop: true key/value pair. This can be of use when paired with rollup rules, as often the goal of a rollup rule is to remove the original raw metrics after aggregation. This is unlike drop rules, which drop the metric before any aggregation takes place. This achieves the same result as setting the drop_raw: true flag on the rollup rule; if this flag is set, it's not necessary to add a matching mapping rule with drop: true.

Mapping rules support both Prometheus and Graphite metrics.

Work with existing rules

  • List rules

    Return all mapping rules with the chronoctl mapping-rules list command, filtered by the bucket they belong to with the --bucket-slugs flag.

    List all mapping rules that belong to the default and observability bucket, run:

    chronoctl mapping-rules list --bucket-slugs default,observability
  • Delete rules

    Delete mapping rules with the chronoctl mapping-rules delete command, providing the slugs of the rules to delete with the --slugs flag.

    For example, to delete the http_request_duration_by_service_and_status rule, run:

    chronoctl mapping-rules delete http_request_duration_by_service_and_status

Create rules

To create a mapping rule, define the desired rule as YAML in a file and applying it with Chronoctl.

  1. To generate a templated example, use the Chronoctl mapping-rules scaffold command:

    chronoctl mapping-rules scaffold

    You can redirect the output to a file for editing:

    chronoctl mapping-rules scaffold > mapping-rule.yaml

    Replace mapping-rule.yaml with any valid filename.

  2. After editing the definition to configure the rule, submit it to Chronosphere for creation by passing the file to chronoctl apply.

    chronoctl apply -f mapping-rule.yml

    Mapping rules take effect immediately but might require a full recording interval to show a change.

Here are some example mapping rules.

Define a metric's retention interval

This example uses the following definable keys:

  • aggregation_policy: Specifies the policy applied to aggregate the metric for a given resolution window.

    • aggregation: For example, setting this property to LAST takes the last element as the aggregated metric. See Supported aggregation operations for a complete list.
    • interval: Specifies the time between aggregated data points. (Known as storage_policies in version 0.286.0-2023-01-06-release.1 and earlier.) Intervals are based on your retention policy.
  • filters: Specifies that the rule catches metrics of name http_request_duration with the label k8s_pod.

    Label filters can include multiple labels. Metrics must match each label for the filter to apply. Label values support glob syntax, including matching multiple patterns with an OR, such as pattern1,pattern2.

api_version: v1/config
kind: MappingRule
spec:
  name: http request duration
  slug: http_request_duration
  bucket_slug: default
  aggregation_policy:
    aggregation: LAST
    interval: 30s
  filters:
  - name: "__name__"
    value_glob: "http_request_duration"
  - name: "k8s_pod"
    value_glob: "*"

Dropping a metric

You don't need to specify an aggregation operation or interval to drop a metric.

api_version: v1/config
kind: MappingRule
spec:
  bucket_slug: default
  filters:
  - name: "__name__"
    value_glob: http_request_bucket
  - name: k8s_pod
    value_glob: "*"
  - name: le
    value_glob: "*"
  - name: git_sha
    value_glob: "*"
  - name: route
    value_glob: "*"
  name: drop raw http_request_bucket
  slug: http_request_bucket
  drop: true