Skip to content

Document label-based routing for Prometheus remote write endpoint #6583

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
felixbarny wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document label-based routing for Prometheus remote write endpoint #6583

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e173ec7
Document label-based routing for Prometheus remote write endpoint
felixbarny May 20, 2026
4fc8477
Apply style guide fixes: active voice, complete sentences
felixbarny May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 32 additions & 3 deletions manage-data/data-store/data-streams/tsds-ingest-prometheus-remote-write.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,15 +80,20 @@ The endpoint accepts `POST` requests with:
## Send data to different data streams

By default, metrics are ingested into the `metrics-generic.prometheus-default` data stream.
You can control the target data stream using URL path parameters:
You can control the target data stream using URL path parameters or per-time-series labels.
In both cases, Elasticsearch sanitizes dataset and namespace values, replacing any character that is not alphanumeric, a hyphen, or an underscore with `_`.

### Route by URL path

Set the dataset and namespace via URL path segments:

| Endpoint | Data stream |
| --- | --- |
| `/_prometheus/api/v1/write` | `metrics-generic.prometheus-default` |
| `/_prometheus/metrics/{dataset}/api/v1/write` | `metrics-{dataset}.prometheus-default` |
| `/_prometheus/metrics/{dataset}/{namespace}/api/v1/write` | `metrics-{dataset}.prometheus-{namespace}` |

For example, to route infrastructure metrics into a dedicated data stream, configure the remote write URL as:
For example, to route infrastructure metrics to a dedicated data stream, set the remote write URL to:

```yaml
remote_write:
Expand All @@ -97,6 +102,28 @@ remote_write:

This sends data to the `metrics-infrastructure.prometheus-production` data stream.

### Route by labels

You can also route individual time series to different data streams by attaching `data_stream_dataset` and `data_stream_namespace` labels to each time series. These labels take precedence over the URL path when set, and allow a single remote write endpoint to fan out metrics to multiple data streams.

Elasticsearch treats these as control fields and does not store them in the document's `labels` object.

If only one of the two labels is present on a time series, the other value falls back to the URL path segment (or the default if no path segment was given).

Use `write_relabel_configs` to add routing labels before sending:

```yaml
remote_write:
- url: "https://<es_endpoint>/_prometheus/api/v1/write"
write_relabel_configs:
- target_label: data_stream_dataset
replacement: myapp
- target_label: data_stream_namespace
replacement: production
```

This attaches `data_stream_dataset=myapp` and `data_stream_namespace=production` to every time series in this remote write target, routing all metrics to `metrics-myapp.prometheus-production`.

## Data mapping

Incoming Prometheus time series are mapped as follows:
Expand All @@ -105,7 +132,9 @@ Incoming Prometheus time series are mapped as follows:
| --- | --- | --- |
| Timestamp | `@timestamp` | The sample timestamp (in milliseconds) |
| `__name__` label | `metrics.<metric_name>` | The metric value, stored as a field named after the metric |
| All labels | `labels.<label_name>` | Mapped as time series dimensions |
| `data_stream_dataset` label | _(routing only)_ | Routes the time series to the specified dataset; not stored in `labels` |
| `data_stream_namespace` label | _(routing only)_ | Routes the time series to the specified namespace; not stored in `labels` |
| All other labels (including `__name__`) | `labels.<label_name>` | Mapped as time series dimensions |

### Metric types

Expand Down
Loading