---
title: ES|QL METRICS_INFO command
description: 
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/metrics-info
products:
  - Elasticsearch
---

# ES|QL METRICS_INFO command
<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Planned
</applies-to>

The `METRICS_INFO` [processing command](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/processing-commands) retrieves
information about the metrics available in
[time series data streams](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/manage-data/data-store/data-streams/time-series-data-stream-tsds),
along with their applicable dimensions and other metadata.
Use `METRICS_INFO` to discover which metrics exist, what types and units they have, and which
dimensions apply to them without having to inspect index mappings or rely on the field
capabilities API. Any [`WHERE`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/where) filters that precede
`METRICS_INFO` narrow the set of time series considered, so only metrics with matching data are
returned.

## Syntax

```esql
METRICS_INFO
```


## Parameters

<note>
  `METRICS_INFO` takes no parameters.
</note>


## Description

`METRICS_INFO` produces one row per distinct metric signature — that is, per unique combination
of metric name and its properties across backing indices. When the same metric is defined with
different properties (for example, different units) in different data streams, separate rows are
returned for each variant.
The output contains the following columns, all of type `keyword`:
<definitions>
  <definition term="metric_name">
    The name of the metric field (single-valued).
  </definition>
  <definition term="data_stream">
    The data stream(s) that contain this metric (multi-valued when the metric is included in multiple data streams
    which align on the unit, metric type, and field type).
  </definition>
  <definition term="unit">
    The [unit](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/elasticsearch/mapping-reference/mapping-field-meta) declared in the field mapping,
    such as `bytes` or `packets` (multi-valued when definitions differ across backing indices;
    may be `null` if no unit is declared).
  </definition>
  <definition term="metric_type">
    The metric type, for example `counter` or `gauge` (multi-valued when definitions differ across backing indices).
  </definition>
  <definition term="field_type">
    The Elasticsearch field type, for example `long`, `double`, or `integer` (multi-valued when definitions differ
    across backing indices).
  </definition>
  <definition term="dimension_fields">
    The dimension field names associated with this metric (multi-valued). The union of dimension
    keys across all time series for that metric.
  </definition>
</definitions>


### Restrictions

- `METRICS_INFO` can only be used after a [`TS`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/ts) source command.
  Using it after `FROM` or other source commands produces an error.
- `METRICS_INFO` must appear before pipeline-breaking commands such as
  [`STATS`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/stats-by),
  [`SORT`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/sort), or
  [`LIMIT`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/limit).
- The output replaces the original table: downstream commands operate on the metadata rows, not the
  raw time series documents.


## Examples


### List all metrics

Return every metric available in the targeted time series data stream, sorted alphabetically by
name:
```esql
TS k8s
| METRICS_INFO
| SORT metric_name
```


| metric_name:keyword    | data_stream:keyword | unit:keyword | metric_type:keyword | field_type:keyword | dimension_fields:keyword |
|------------------------|---------------------|--------------|---------------------|--------------------|--------------------------|
| network.eth0.rx        | k8s                 | packets      | gauge               | integer            | [cluster, pod, region]   |
| network.eth0.tx        | k8s                 | packets      | gauge               | integer            | [cluster, pod, region]   |
| network.total_bytes_in | k8s                 | bytes        | counter             | long               | [cluster, pod, region]   |
| network.total_cost     | k8s                 | usd          | counter             | double             | [cluster, pod, region]   |


### Discover metrics matching a filter

Place a [`WHERE`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/where) clause before `METRICS_INFO` to
restrict the time series considered. Only metrics that have actual data matching the filter are
returned:
```esql
TS k8s
| WHERE cluster == "prod"
| METRICS_INFO
| SORT metric_name
```


| metric_name:keyword    | data_stream:keyword | unit:keyword | metric_type:keyword | field_type:keyword | dimension_fields:keyword |
|------------------------|---------------------|--------------|---------------------|--------------------|--------------------------|
| network.eth0.rx        | k8s                 | packets      | gauge               | integer            | [cluster, pod, region]   |
| network.eth0.tx        | k8s                 | packets      | gauge               | integer            | [cluster, pod, region]   |
| network.total_bytes_in | k8s                 | bytes        | counter             | long               | [cluster, pod, region]   |
| network.total_cost     | k8s                 | usd          | counter             | double             | [cluster, pod, region]   |


### Select specific columns

Use [`KEEP`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/keep) to return only the columns you need:
```esql
TS k8s
| WHERE cluster == "prod"
| METRICS_INFO
| KEEP metric_name, metric_type
| SORT metric_name
```


| metric_name:keyword    | metric_type:keyword |
|------------------------|---------------------|
| network.eth0.rx        | gauge               |
| network.eth0.tx        | gauge               |
| network.total_bytes_in | counter             |
| network.total_cost     | counter             |


### Filter by metric type

Use [`WHERE`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/where) after `METRICS_INFO` to narrow results
by metadata, for example to only counter metrics:
```esql
TS k8s
| METRICS_INFO
| WHERE metric_type == "counter"
| SORT metric_name
```


| metric_name:keyword    | data_stream:keyword | unit:keyword | metric_type:keyword | field_type:keyword | dimension_fields:keyword |
|------------------------|---------------------|--------------|---------------------|--------------------|--------------------------|
| network.total_bytes_in | k8s                 | bytes        | counter             | long               | [cluster, pod, region]   |
| network.total_cost     | k8s                 | usd          | counter             | double             | [cluster, pod, region]   |


### Filter by metric name pattern

Use a `LIKE` pattern after `METRICS_INFO` to find metrics whose name matches a prefix or
wildcard. This is useful for exploring a specific subsystem when you know part of the metric
name:
```esql
TS k8s
| METRICS_INFO
| WHERE metric_name LIKE "network.eth0*"
| SORT metric_name
```


| metric_name:keyword | data_stream:keyword | unit:keyword | metric_type:keyword | field_type:keyword | dimension_fields:keyword |
|---------------------|---------------------|--------------|---------------------|--------------------|--------------------------|
| network.eth0.rx     | k8s                 | packets      | gauge               | integer            | [cluster, pod, region]   |
| network.eth0.tx     | k8s                 | packets      | gauge               | integer            | [cluster, pod, region]   |


### Count matching metrics

Combine with [`STATS`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/145980/reference/query-languages/esql/commands/stats-by) to aggregate the metadata.
For example, count distinct metrics whose name matches a pattern:
```esql
TS k8s
| METRICS_INFO
| WHERE metric_name LIKE "network.total*"
| STATS matching_metrics = COUNT_DISTINCT(metric_name)
```


| matching_metrics:long |
|-----------------------|
| 2                     |


### Count metrics by type

Group the metric catalogue by `metric_type` to see how many counter, gauge, or other metrics
exist:
```esql
TS k8s
| METRICS_INFO
| STATS metric_count = COUNT(*) BY metric_type
| SORT metric_type
```


| metric_count:long | metric_type:keyword |
|-------------------|---------------------|
| 2                 | counter             |
| 2                 | gauge               |