---
title: Metrics Search Syntax
description: >-
  Learn about how to use metrics search syntax for your Observability Pipelines
  processors filter queries.
breadcrumbs: Docs > Observability Pipelines > Search Syntax > Metrics Search Syntax
---

# Metrics Search Syntax

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ().
{% /alert %}

{% /callout %}

## Overview{% #overview %}

When you add a processor to a pipeline, you can filter metrics (Preview (PREVIEW indicates an early access version of a major product or feature that you can opt into before its official release.)) to only process a defined subset. This document goes over the following information:

- Free text search
- Attribute search
- Tags search
- Boolean operators
- Wildcards

**Note**: Metrics search syntax is case sensitive.

## Free text search{% #free-text-search %}

Free text search for metrics only searches the `name` field.

An example of a free text search: `system.cpu.user`, which matches metrics with `name:system.cpu.user`.

## Attribute search{% #attribute-search %}

You can search the attribute keys:

- `kind`: Whether the metrics is `absolute` or `incremental`.
- `value`: The metric type.
  - `counter`
  - `gauge`
  - `distribution`
  - `histogram`

Here are some attribute search syntax examples:

{% dl %}

{% dt %}
`kind:absolute`
{% /dt %}

{% dd %}
Matches metrics with `kind:absolute`.
{% /dd %}

{% dt %}
`value:counter`
{% /dt %}

{% dd %}
Matches `counter` metrics.
{% /dd %}

{% /dl %}

## Tags search{% #tags-search %}

You can search a metric's `tags`. Special characters and spaces in a tag must be escaped in the search syntax.

### Escape special characters and spaces{% #escape-special-characters-and-spaces %}

The following characters are considered special and must be escaped with a backslash (`\`):

`-` `!` `&&` `||` `>` `>=` `<` `<=` `(` `)` `{` `}` `[` `]` `"` `*` `?` `:` `#`, and spaces.

**Notes**:

- `/` is not considered a special character and doesn't need to be escaped.
- You can search for special characters in a tag. See Search for a tag that contains special characters.
- If you want to match metrics tags that contain the special character `!` , use the attribute search syntax: `tags:*\:!*.`

### Search for a tag that contains special characters{% #search-for-a-tag-that-contains-special-characters %}

Searching for a tag that contains special characters requires escaping or double quotes. For example, to search for a tag `service` with the value `web-store`, use one of the following search syntaxes:

- `tags:service\:web\-store`
- `tags:service\:"web-store"`

### Match a single special character{% #match-a-single-special-character %}

To match a single special character or space, use the `?` wildcard. For example, the search syntax: `"tags:service\:web?store"` matches metrics with either of these tags:

- `service:"web store"`
- `service:"web-store"`

### Examples{% #examples %}

To learn how to escape special characters in a tag search, let's look at a metric example:

```
{
  "name":"datadog.agent.retry_queue_duration.bytes_per_sec",
  "tags":{
      "agent":"core",
      "domain":"https://7-72-3-app.agent.datadoghq.com",
      "host":"COMP-YGVQDJG75L",
      "source_type_name":"System",
      "env:prod",
      "service:web-store"
    },
  "timestamp":"2025-11-28T13:03:09Z",
  "kind":"absolute",
  "gauge":{"value":454.1372767857143}
}
```

The following are search syntax examples that escape special characters in the metric example:

{% dl %}

{% dt %}
`tags:env*`
{% /dt %}

{% dd %}
Matches metrics with `tags` containing the `env` key.
{% /dd %}

{% dt %}
`tags:(env\:prod OR env\:test)`
{% /dt %}

{% dd %}
Matches metrics with `env:prod` or `env:test` in `tags`.
{% /dd %}

{% dd %}
This query can also be written as `tags:("env:prod" OR "env:test")`.
{% /dd %}

{% dt %}
`tags:env\:prod AND -tags:version\:beta`
{% /dt %}

{% dd %}
Matches metrics that have `env:prod` and does not have `version:beta` in `tags`.
{% /dd %}

{% dd %}
This query can also be written as `tags:"env:prod" AND -tags:"version:beta"`.
{% /dd %}

{% /dl %}

## Boolean operators{% #boolean-operators %}

You can use the following case sensitive Boolean operators to combine multiple terms in a search query.

The follow are example queries that use Boolean operators:

{% dl %}

{% dt %}
`NOT system.cpu.user`
{% /dt %}

{% dd %}
Matches metrics that do not have `name:system.cpu.user`.
{% /dd %}

{% dd %}
This query can also be written as `-system.cpu.user`.
{% /dd %}

{% dt %}
`system.cpu.user OR system.cpu.user.total`
{% /dt %}

{% dd %}
Matches metrics that have either `name:system.cpu.user` or `name:system.cpu.user.total`.
{% /dd %}

{% dt %}
`value:counter AND (tags:env\:staging OR tags:env\:dev)`
{% /dt %}

{% dd %}
Matches metrics that have both `counter:{value:<value>}` and the either the tag `env:prod` or `env:dev`
{% /dd %}

{% /dl %}

## Wildcards{% #wildcards %}

​​You can use `*` for wildcard searches. The following are wildcard search examples:

{% dl %}

{% dt %}
`*system.cpu.user*`
{% /dt %}

{% dd %}
Matches metrics with a `name` value that contains `system.cpu.user`.
{% /dd %}

{% dt %}
`system.cpu.user*`
{% /dt %}

{% dd %}
Matches metrics with a `name` value that starts with `system.cpu.user`.
{% /dd %}

{% dt %}
`*system.cpu.user`
{% /dt %}

{% dd %}
Matches metrics with a `name` value that ends with `system.cpu.user`.
{% /dd %}

{% dt %}
`tags:*\:bin`
{% /dt %}

{% dd %}
Matches metrics that have a tag with the value `bin`, regardless of what the tag key is.
{% /dd %}

{% /dl %}