Mapping rules
Mapping aggregation rules downsample in-memory metric data on the streaming ingest path before storing any results in the database, which 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 useful when paired with rollup rules, since 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.
When to use mapping rules
Chronosphere recommends using mapping rules instead of rollup rules in scenarios
where you’re ingesting data points for a time series at a sporadic rate,
and that exceeds the standard 15s
, 30s
, and 60s
resolutions. These denser time series consume
more query resources, which means they use more data points per second (DPPS) compared to
the amount of cardinality you’re storing.
Both mapping rules and rollup rules get applied in the same aggregation phase, which means that mapping rules consume matched writes.
View existing mapping rules
Select from the following methods to view your mapping rules.
To list your existing mapping rules using Chronoctl, use the
chronoctl mapping-rules list
command:
chronoctl mapping-rules list
Create mapping rules
Select from the following methods to create a mapping rule.
To create a mapping rule with Chronoctl, define the desired rule in a YAML file and apply it.
If you don’t already have a YAML configuration file, use the scaffold
Chronoctl
parameter to generate a template for a specific resource type:
chronoctl mapping-rules scaffold
You can redirect the results (using the redirection operator >
) to a file for
editing.
-
Create or edit a YAML configuration file to configure the mapping rule.
-
Apply the mapping rule:
chronoctl apply -f FILE_NAME.yaml
Replace FILE_NAME
with the name of the YAML configuration file.
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 resolution
Although you can adjust the resolution for a mapping rule and configure the interval between aggregated data points, Chronosphere doesn’t recommend this approach for the sole purpose of reducing resolution. Instead, adjust the scrape or push interval in the Chronosphere Collector or the OpenTelemetry Collector, depending on how you send metrics to Observability Platform.
The following example uses these keys:
-
aggregation_policy
: Specifies the policy applied to aggregate the metric for a given resolution window.aggregation
: For example, setting this property toLAST
takes the last element as the aggregated metric. See Supported aggregation operations for a complete list.interval
: Specifies the time between aggregated data points. Intervals are based on your retention policy.
-
filters
: Specifies that the rule catches metrics of namehttp_request_duration
with the labelk8s_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
aggregation_policy:
aggregation: LAST
interval: 30s
filters:
- name: "__name__"
value_glob: "http_request_duration"
- name: "k8s_pod"
value_glob: "*"
Drop a metric
You don’t need to specify an aggregation operation or interval to drop a metric.
api_version: v1/config
kind: MappingRule
spec:
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
Delete mapping rules
Select from the following methods to delete a mapping rule.
To delete a mapping rule using Chronoctl, use the
chronoctl mapping-rules delete
command:
chronoctl mapping-rules delete SLUG
Replace SLUG
with the slug of the rule you want to
delete.