Add Prometheus namespace with five new endpoints by MattDevy · Pull Request #6293 · elastic/elasticsearch-specification

MattDevy · 2026-05-20T17:35:03Z

Summary

Adds a new prometheus/ namespace with five endpoints for the Prometheus HTTP API compatibility layer introduced in Elasticsearch 9.4.0. All are Tech Preview (stability=experimental, visibility=public) and available in both stack and serverless.

Endpoint	Operation	URLs
`prometheus.remote_write`	POST	`/_prometheus/api/v1/write`, `/_prometheus/metrics/{dataset}/api/v1/write`, `/_prometheus/metrics/{dataset}/{namespace}/api/v1/write`
`prometheus.query`	GET	`/_prometheus/api/v1/query`, `/_prometheus/{index}/api/v1/query`
`prometheus.query_range`	GET	`/_prometheus/api/v1/query_range`, `/_prometheus/{index}/api/v1/query_range`
`prometheus.series`	GET	`/_prometheus/api/v1/series`, `/_prometheus/{index}/api/v1/series`
`prometheus.labels`	GET	`/_prometheus/api/v1/labels`, `/_prometheus/{index}/api/v1/labels`

All response bodies are typed as UserDefinedValue (opaque) since the Prometheus HTTP API JSON envelope is complex. The remote_write request body is protobuf — no request_media_type is declared as there is no protobuf entry in the MediaType enum; a follow-up can add one if needed.

ES PRs: elastic/elasticsearch#141957, elastic/elasticsearch#145321, elastic/elasticsearch#144416, elastic/elasticsearch#144494, elastic/elasticsearch#144952 (all labeled v9.4.0)

Test plan

Verify all five endpoints appear in the generated schema under the prometheus namespace
Verify stability=experimental and visibility=public for both stack and serverless on all five
Verify remote_write has three URL variants; all others have two
Verify series has match[] as required; labels has match[] as optional
Verify query_range has start, end, step as required query params

The schema compiler requires every Request interface to have a @doc_id annotation pointing to a registered entry in _doc_ids/table.csv. The five prometheus request files were missing these, causing CI to fail. Added #TODO placeholder URLs following the same pattern used by other new 9.4.0 endpoints (e.g. the reindex management APIs).

github-actions · 2026-05-21T11:15:35Z

Following you can find the validation changes against the target branch for the APIs.

API	Status	Request	Response
`prometheus.labels`	➕ ⚪	Missing test	Missing test
`prometheus.query`	➕ ⚪	Missing test	Missing test
`prometheus.query_range`	➕ ⚪	Missing test	Missing test
`prometheus.remote_write`	➕ ⚪	Missing test	Missing test
`prometheus.series`	➕ ⚪	Missing test	Missing test

You can validate these APIs yourself by using the make validate target.

l-trotta · 2026-05-21T13:15:19Z

+/**
+ * Get label names.
+ *
+ * Return a list of label names that match a certain set of selectors.


Suggested change

* Return a list of label names that match a certain set of selectors.

* Return a sorted list of label names that match a certain set of selectors.

since the endpoint java doc in the server code specifies that the list is sorted we can also add it here

l-trotta · 2026-05-21T13:23:13Z

+     */
+    'match[]'?: string[]
+    /**
+     * The start of the time range. Defaults to `now - 24h`.


we should use the server default annotation

from the server code it looks like it's "end-24h" (which yes it's "now-24h" in case both are empty, but still)

l-trotta · 2026-05-21T13:23:19Z

+     */
+    start?: string
+    /**
+     * The end of the time range. Defaults to now.


we should use the server default annotation

l-trotta · 2026-05-21T13:31:56Z

+
+export class Response {
+  /** @codegen_name body */
+  body: UserDefinedValue


is it really completely unmappable? I'm looking at the server code and it seems like there is some structure, there's also the error case which we could map using the exceptions field.

l-trotta · 2026-05-21T13:34:33Z

+     */
+    query: string
+    /**
+     * The evaluation timestamp. Defaults to the current server time.


we should use the server default annotation (default to now)

l-trotta · 2026-05-21T13:49:17Z

this one is likely missing the body, the request_media_type and the response_media_type. from the server code it's not immediately clear what's expecting, let's gather more info first.

l-trotta · 2026-05-21T13:52:23Z

+
+export class Response {
+  /** @codegen_name body */
+  body: UserDefinedValue


I think this one just returns and empty response, from reading the server code, but again, not super clear, need more info.

l-trotta · 2026-05-21T13:53:58Z

+  ]
+  path_parts: {
+    /**
+     * An index pattern that restricts the query to a specific index.


same as the others

l-trotta · 2026-05-21T13:54:42Z

+  query_parameters: {
+    /**
+     * Repeated series selector arguments that select the series to return.
+     * @codegen_name match
+     */
+    'match[]': string[]
+    /**
+     * The start of the time range. Defaults to `now - 24h`.
+     */
+    start?: string
+    /**
+     * The end of the time range. Defaults to now.
+     */
+    end?: string
+    /**
+     * The maximum number of results to return. `0` means no limit.
+     */
+    limit?: integer
+  }


same comments in labels request apply

l-trotta · 2026-05-21T13:55:20Z

+
+export class Response {
+  /** @codegen_name body */
+  body: UserDefinedValue


same as above

lcawl · 2026-05-28T16:33:12Z

+ *
+ * Return a list of label names that match a certain set of selectors.
+ * @rest_spec_name prometheus.labels
+ * @availability stack since=9.4.0 stability=experimental visibility=public


We've now got "tech_preview" available per #6312

Suggested change

* @availability stack since=9.4.0 stability=experimental visibility=public

* @availability stack since=9.4.0 stability=tech_preview visibility=public

lcawl · 2026-05-28T16:33:26Z

+ * Return a list of label names that match a certain set of selectors.
+ * @rest_spec_name prometheus.labels
+ * @availability stack since=9.4.0 stability=experimental visibility=public
+ * @availability serverless stability=experimental visibility=public


Suggested change

* @availability serverless stability=experimental visibility=public

* @availability serverless stability=tech_preview visibility=public

lcawl · 2026-05-28T16:33:47Z

+ *
+ * Evaluate a PromQL expression at a single point in time.
+ * @rest_spec_name prometheus.query
+ * @availability stack since=9.4.0 stability=experimental visibility=public


Suggested change

* @availability stack since=9.4.0 stability=experimental visibility=public

* @availability stack since=9.4.0 stability=tech_preview visibility=public

lcawl · 2026-05-28T16:34:03Z

+ * Evaluate a PromQL expression at a single point in time.
+ * @rest_spec_name prometheus.query
+ * @availability stack since=9.4.0 stability=experimental visibility=public
+ * @availability serverless stability=experimental visibility=public


Suggested change

* @availability serverless stability=experimental visibility=public

* @availability serverless stability=tech_preview visibility=public

lcawl · 2026-05-28T16:34:16Z

+ * Evaluate a PromQL expression over a time range.
+ * @rest_spec_name prometheus.query_range
+ * @availability stack since=9.4.0 stability=experimental visibility=public
+ * @availability serverless stability=experimental visibility=public


Suggested change

* @availability serverless stability=experimental visibility=public

* @availability serverless stability=tech_preview visibility=public

lcawl · 2026-05-28T16:34:29Z

+ *
+ * Evaluate a PromQL expression over a time range.
+ * @rest_spec_name prometheus.query_range
+ * @availability stack since=9.4.0 stability=experimental visibility=public


Suggested change

* @availability stack since=9.4.0 stability=experimental visibility=public

* @availability stack since=9.4.0 stability=tech_preview visibility=public

lcawl · 2026-05-28T16:34:43Z

+ * Accepts a Prometheus remote write request (protobuf-encoded) and indexes the
+ * time series data into Elasticsearch.
+ * @rest_spec_name prometheus.remote_write
+ * @availability stack since=9.4.0 stability=experimental visibility=public


Suggested change

* @availability stack since=9.4.0 stability=experimental visibility=public

* @availability stack since=9.4.0 stability=tech_preview visibility=public

lcawl · 2026-05-28T16:34:53Z

+ * time series data into Elasticsearch.
+ * @rest_spec_name prometheus.remote_write
+ * @availability stack since=9.4.0 stability=experimental visibility=public
+ * @availability serverless stability=experimental visibility=public


Suggested change

* @availability serverless stability=experimental visibility=public

* @availability serverless stability=tech_preview visibility=public

lcawl · 2026-05-28T16:35:05Z

+ *
+ * Return the list of time series that match a certain set of selectors.
+ * @rest_spec_name prometheus.series
+ * @availability stack since=9.4.0 stability=experimental visibility=public


Suggested change

* @availability stack since=9.4.0 stability=experimental visibility=public

* @availability stack since=9.4.0 stability=tech_preview visibility=public

lcawl · 2026-05-28T16:35:18Z

+ * Return the list of time series that match a certain set of selectors.
+ * @rest_spec_name prometheus.series
+ * @availability stack since=9.4.0 stability=experimental visibility=public
+ * @availability serverless stability=experimental visibility=public


Suggested change

* @availability serverless stability=experimental visibility=public

* @availability serverless stability=tech_preview visibility=public

lcawl · 2026-05-28T16:42:30Z

+ * Ingest Prometheus remote write data.
+ *
+ * Accepts a Prometheus remote write request (protobuf-encoded) and indexes the
+ * time series data into Elasticsearch.


Not mandatory, but might be nice to link to the narrative docs:

Suggested change

* time series data into Elasticsearch.

* time series data into Elasticsearch. For an overview, refer to [Prometheus remote write endpoint](https://www.elastic.co/docs/manage-data/data-store/data-streams/tsds-ingest-prometheus-remote-write).

add prometheus namespace with five new endpoints

894c31b

MattDevy added the backport 9.4 label May 20, 2026

github-actions Bot added the specification label May 20, 2026

MattDevy marked this pull request as ready for review May 21, 2026 09:56

MattDevy requested review from flobernd and l-trotta May 21, 2026 09:56

MattDevy and others added 3 commits May 21, 2026 10:56

Merge branch 'main' into add-prometheus-endpoints

2450cc7

add @codegen_name body to prometheus response files

7ef9460

remove since= from serverless availability annotations

57a17c3

MattDevy marked this pull request as draft May 21, 2026 10:28

fix match[] property name with @codegen_name and regenerate output

ec044ac

MattDevy force-pushed the add-prometheus-endpoints branch from af4f50f to ec044ac Compare May 21, 2026 11:11

MattDevy marked this pull request as ready for review May 21, 2026 11:13

l-trotta reviewed May 21, 2026

View reviewed changes

lcawl reviewed May 28, 2026

View reviewed changes

lcawl mentioned this pull request May 28, 2026

Document label-based routing for Prometheus remote write endpoint elastic/docs-content#6583

Merged

github-actions Bot mentioned this pull request Jun 1, 2026

Spec drift: update for elasticsearch#150235 (new GET /_prometheus/api/v1/status/buildinfo endpoint) #6337

Open

	* Return a list of label names that match a certain set of selectors.
	* Return a sorted list of label names that match a certain set of selectors.

	* @availability stack since=9.4.0 stability=experimental visibility=public
	* @availability stack since=9.4.0 stability=tech_preview visibility=public

	* @availability serverless stability=experimental visibility=public
	* @availability serverless stability=tech_preview visibility=public

	* time series data into Elasticsearch.
	* time series data into Elasticsearch. For an overview, refer to [Prometheus remote write endpoint](https://www.elastic.co/docs/manage-data/data-store/data-streams/tsds-ingest-prometheus-remote-write).

Conversation

MattDevy commented May 20, 2026

Summary

Test plan

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented May 21, 2026 •

edited

Loading