Drop Dimensions

Analytics Metrics

Synopsis

Removes the listed attribute keys from an OTLP metric — or, with keep, retains only those listed and removes the rest. Datapoint and resource attributes are addressed separately.

Schema

- drop_dimensions:
    dimensions: <string[]>
    resource_dimensions: <string[]>
    keep: <boolean>
    filter: <script>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

Field	Required	Default	Description
`dimensions`	N	-	Datapoint attribute keys to act on
`resource_dimensions`	N	-	Resource attribute keys to act on
`keep`	N	`false`	Invert the meaning of both lists: retain the named keys and remove everything else
`filter`	N	-	Cribl-style JavaScript truthiness expression evaluated after `if`. A falsy result skips the processor
`description`	N	-	Explanatory note
`if`	N	-	Condition to run
`ignore_failure`	N	`false`	See Handling Failures
`on_failure`	N	-	See Handling Failures
`on_success`	N	-	See Handling Success
`tag`	N	-	Identifier
`disabled`	N	`false`	When `true`, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Details

Dropping attributes is how metric cardinality is controlled. Every distinct combination of attribute values is a separate time series, so a single high-cardinality attribute — a request ID, a pod name — can multiply one metric into thousands of series. Removing it collapses them.

The two scopes are independent, and an omitted list means "leave this scope alone" — not "keep nothing". Setting only resource_dimensions while keep: true is in force does not strip every datapoint attribute through an empty allow-list; the datapoint scope is simply not touched. The same holds the other way. Each scope is filtered only when its own list is non-empty, which is what makes it safe to write a keep list for one scope without having to enumerate the other.

keep applies to both lists at once. There is no way to keep some datapoint attributes while dropping named resource attributes in a single processor — use two.

This processor removes attributes but does not merge the series that become identical as a result. Pair it with Series Aggregate, which folds series onto a reduced identity over a window.

Examples

Dropping a High-Cardinality Attribute

Removing the attribute that multiplies the series count...

- drop_dimensions:
    dimensions:
      - pod_name
      - request_id

every other datapoint attribute, and all resource attributes, survive:

# http_requests_total{pod_name="api-7f9",request_id="abc",route="/v1"}
# http_requests_total{pod_name="api-2c1",request_id="def",route="/v1"}
#   becomes, twice over:
# http_requests_total{route="/v1"}

Keeping an Explicit Set

With `keep`, the list becomes an allow-list...	`- drop_dimensions: keep: true dimensions: - route - status_code`
so a newly added attribute cannot silently inflate cardinality:	`# Resource attributes are untouched — resource_dimensions # was not set, so that scope is left alone rather than emptied.`

Both Scopes

Naming both lists acts on both scopes, under the same keep...

- drop_dimensions:
    keep: true
    dimensions: ["route", "status_code"]
    resource_dimensions: ["service.name", "deployment.environment"]

keeping two attributes at each level and dropping the rest:

# `keep` cannot differ between the two scopes.
# Use two processors if you need to keep at one level
# and drop named keys at the other.

Synopsis​

Schema​

Configuration​

Details​

Examples​

Dropping a High-Cardinality Attribute​

Keeping an Explicit Set​

Both Scopes​