SOLR-17436: Create a v2 equivalent for /admin/metrics #4057

igiguere · 2026-01-16T17:47:33Z

https://issues.apache.org/jira/browse/SOLR-17436

Description

Create a JAX-RS V2 equivalent for /admin/metrics.

Solution

Add interface MetricsApi, and implementation GetMetrics, as an extension of JerseyResource (via AdminAPIBase).

The new full URL path is /api/metrics. The metrics response is a StreamingOutput.

Add class MetricsUtil to re-group logic used by both MetricsHandler and GetMetrics. Both classes get their information directly from SolrMetricManager.

Adjust documentation.

Tests

Added unit tests for the GetMetrics implementation of MetricsApi.

Added unit tests for SolrJ MetricsRequest.

Functional tests on "devSlim", with a mini cluster of 2 nodes.

Checklist

Please review the following and check all that apply:

I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
I have created a Jira issue and added the issue ID to my pull request title.
I have given Solr maintainers access to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
I have developed this patch against the main branch.
I have run ./gradlew check.
I have added tests for my changes.
I have added documentation for the Reference Guide
I have added a changelog entry for my change

Add interface MetricsApi and class GetMetrics. Add MetricsUtil to merge the List<MetricSnapshot> in either MetricsHandler or GetMetrics. Implementations in MessageBodyWriters: not sure if needed. Note in SplitShardCmd: this appears to have been broken before. The Solr response might always be null now. More testing and cleaning-up to do.

Fix compilation and add unit tests

Adjust documentation. Set ResponseParser in MetricsRequest constructor. Clean-up.

Last clean-up after testing proxyToNodes() on a local cluster.

add changelog, and commit result of tidy

…olr.git into SOLR-17436-V2-Metrics-API

gerlowskija

Was very excited to see this PR @igiguere , thanks for putting this together!

I've only reviewed about half the PR but wanted to publish what I have so far.

Everything looks great overall so far, though there were a few small things I think will need tweaked that I've tried to call out inline. Lmk if any of those comments are unclear or you disagree and I'll try to respond when I come back for the second half later!

solr/api/src/java/org/apache/solr/client/api/endpoint/MetricsApi.java

solr/api/src/java/org/apache/solr/client/api/model/MetricsResponse.java

solr/core/src/java/org/apache/solr/cloud/api/collections/SplitShardCmd.java

solr/core/src/java/org/apache/solr/handler/admin/api/GetMetrics.java

solr/core/src/java/org/apache/solr/metrics/MetricsUtil.java

solr/core/src/java/org/apache/solr/handler/admin/api/GetMetrics.java

gerlowskija

Alright, finished my review. Left a few more in-line comments, though things look very good overall. Just a few smaller things I think we'll need to change.

Let me know if you have any questions or I can help with anything!

solr/core/src/java/org/apache/solr/jersey/JerseyApplications.java

solr/core/src/java/org/apache/solr/metrics/MetricsUtil.java

solr/core/src/java/org/apache/solr/response/PrometheusResponseWriter.java

solr/core/src/test/org/apache/solr/handler/admin/api/GetMetricsTest.java

solr/solr-ref-guide/modules/deployment-guide/pages/metrics-reporting.adoc

gerlowskija · 2026-01-20T12:49:11Z

solr/solr-ref-guide/modules/deployment-guide/pages/metrics-reporting.adoc

 === OpenMetrics

-OpenMetrics format is available from the `/admin/metrics` endpoint by providing the `wt=openmetrics` parameter or by passing the Accept header `application/openmetrics-text;version=1.0.0`. OpenMetrics is an extension of the Prometheus format that adds additional metadata and exemplars.
+OpenMetrics format is available from the `/metrics` endpoint by providing the `wt=openmetrics` parameter or by passing the Accept header `application/openmetrics-text;version=1.0.0`. OpenMetrics is an extension of the Prometheus format that adds additional metadata and exemplars.


[Q] Huh - I'm surprised that these docs mention the "Accept" header even before you added a v2 endpoint in this PR. I didn't think anything on the v1 side looked at "Accept". I guess that's a good thing, I'm just surprised is all...

I had written something custom to check content-type but just for OpenMetrics but not prometheus. See my comment above.

solr/solr-ref-guide/modules/deployment-guide/pages/metrics-reporting.adoc

gerlowskija · 2026-01-20T12:56:34Z

solr/solrj/src/java/org/apache/solr/client/solrj/request/MetricsRequest.java


 /** Request to "/admin/metrics" */
-public class MetricsRequest extends SolrRequest<SolrResponse> {
+public class MetricsRequest extends SolrRequest<InputStreamResponse> {


[Q] Why change the SolrJ class that corresponds to the v1 metrics API? Your PR only modifies the v2 API, right?

V1, since Solr 10, returns a stream (prometheus or openmetrics), not a SolrResponse (where I would expect a NamedList... right?).
If I recall, the only place in Solr code where MetricsRequest is used is a method somewhere in the CLI tools that stars with something like : if (true) return; The method is disabled, and there's a couple of comments about tickets to be done.
I think the type param InputStreamResponse makes it clearer that this is not a typical Solr response.

solr/solr-ref-guide/modules/deployment-guide/pages/metrics-reporting.adoc

mlbiscoc

Thanks @igiguere for doing this! The timing was great as the metrics api just had a huge overhaul in 10 so getting up to date on V2 gets us closer to a more modern path.

solr/api/src/java/org/apache/solr/client/api/model/MetricsResponse.java

solr/core/src/java/org/apache/solr/handler/admin/api/GetMetrics.java

solr/core/src/java/org/apache/solr/metrics/MetricsUtil.java

solr/core/src/test/org/apache/solr/handler/admin/api/GetMetricsTest.java

mlbiscoc · 2026-01-20T21:17:57Z

solr/solr-ref-guide/modules/deployment-guide/pages/metrics-reporting.adoc

 === OpenMetrics

-OpenMetrics format is available from the `/admin/metrics` endpoint by providing the `wt=openmetrics` parameter or by passing the Accept header `application/openmetrics-text;version=1.0.0`. OpenMetrics is an extension of the Prometheus format that adds additional metadata and exemplars.
+OpenMetrics format is available from the `/metrics` endpoint by providing the `wt=openmetrics` parameter or by passing the Accept header `application/openmetrics-text;version=1.0.0`. OpenMetrics is an extension of the Prometheus format that adds additional metadata and exemplars.


I had written something custom to check content-type but just for OpenMetrics but not prometheus. See my comment above.

Address review comments. Add query params to the API method. Fix implementation and tests. Adjust documentation and comments. Remove class MetricsResponse. TODO : AdminHandlersProxy only supports V1

igiguere · 2026-01-22T02:30:35Z

@gerlowskija, @mlbiscoc
I think I addressed most review comments, or commented here.
One remaining issue : AdminHandlersProxy only support V1. If we should still suport the "node" (or "nodes") param, there'S a bit more work there. I'll sleep on it...

gradlew clean check in progress, locally.

Adapt AdminHandlersProxy to handle V2 API. Change GetMetricsTest to send REST GET requests. Adapt MetricsRequest to support V1 and V2, and set the response parser, according to 'wt'... Should handle "Accept" header, but SolrRequest is not aware of HTTP headers. Adapt re-existing code (tests) accordingly. Add unit tests for MetricsRequest

remove temp file, remove ingore

Address review comments: Keep just one utility class for metrics (MetricUtils). Remove debug "System.out" form unit tests.

…olr.git into SOLR-17436-V2-Metrics-API

igiguere · 2026-01-26T20:37:23Z

@gerlowskija, @mlbiscoc I think I addressed most review comments, or commented here. One remaining issue : AdminHandlersProxy only support V1. If we should still suport the "node" (or "nodes") param, there'S a bit more work there. I'll sleep on it...

gradlew clean check in progress, locally.

AdminHandlersProxy now supports both V1 and V2.
gradlew clean check passed locally.

solr/core/src/java/org/apache/solr/handler/admin/api/GetMetrics.java

solr/modules/jwt-auth/src/test/org/apache/solr/security/jwt/JWTAuthPluginTest.java

solr/core/src/java/org/apache/solr/handler/admin/AdminHandlersProxy.java

Remove unnecessary logging. Remove debug System.out

Merge remote-tracking branch 'origin-solr/main' into SOLR-17436-V2-Metrics-API

Isabelle Giguere and others added 5 commits January 15, 2026 10:00

Merge branch 'apache:main' into SOLR-17436-V2-Metrics-API

2585d22

SOLR-17436: add unit tests

16c0909

Fix compilation and add unit tests

SOLR-17436: V2 Metrics API

6458693

Adjust documentation. Set ResponseParser in MetricsRequest constructor. Clean-up.

SOLR-17436: V2 Metrics API

27d4304

Last clean-up after testing proxyToNodes() on a local cluster.

github-actions bot added tests cat:search cat:cloud cat:api cat:metrics labels Jan 16, 2026

Isabelle Giguere added 2 commits January 16, 2026 12:51

SOLR-17436: changelog

faad32e

add changelog, and commit result of tidy

Merge branch 'SOLR-17436-V2-Metrics-API' of git@github.com:igiguere/s…

2445c4d

…olr.git into SOLR-17436-V2-Metrics-API

github-actions bot added documentation Improvements or additions to documentation test-framework client:solrj module:opentelemetry labels Jan 16, 2026

igiguere marked this pull request as ready for review January 16, 2026 21:49

dsmiley requested review from gerlowskija and mlbiscoc January 17, 2026 15:26

gerlowskija requested changes Jan 19, 2026

View reviewed changes

gerlowskija reviewed Jan 20, 2026

View reviewed changes

mlbiscoc reviewed Jan 20, 2026

View reviewed changes

SOLR-17436: V2 Metrics API

bdccb1a

Address review comments. Add query params to the API method. Fix implementation and tests. Adjust documentation and comments. Remove class MetricsResponse. TODO : AdminHandlersProxy only supports V1

Isabelle Giguere and others added 6 commits January 23, 2026 14:41

SOLR-17436: V2 metrics tests

87da899

remove temp file, remove ingore

Merge branch 'apache:main' into SOLR-17436-V2-Metrics-API

59c9c95

SOLR-17436: remove unused import

97acc04

Merge branch 'apache:main' into SOLR-17436-V2-Metrics-API

02d4e2f

SOLR-17436: V2 Metrics API - review comments

b58d10d

Address review comments: Keep just one utility class for metrics (MetricUtils). Remove debug "System.out" form unit tests.

Merge branch 'SOLR-17436-V2-Metrics-API' of git@github.com:igiguere/s…

c51b50c

…olr.git into SOLR-17436-V2-Metrics-API

github-actions bot added module:jwt-auth cat:security and removed cat:metrics labels Jan 26, 2026

igiguere requested a review from gerlowskija January 26, 2026 20:39

mlbiscoc reviewed Jan 26, 2026

View reviewed changes

solr/core/src/java/org/apache/solr/handler/admin/api/GetMetrics.java Outdated Show resolved Hide resolved

solr/modules/jwt-auth/src/test/org/apache/solr/security/jwt/JWTAuthPluginTest.java Outdated Show resolved Hide resolved

igiguere commented Jan 26, 2026

View reviewed changes

solr/core/src/java/org/apache/solr/handler/admin/AdminHandlersProxy.java Show resolved Hide resolved

igiguere mentioned this pull request Jan 26, 2026

SOLR-16458: Node system info V2 api jersey resource #4078

Draft

8 tasks

SOLR-17436: V2 metrics API - review comments

73d0dad

Remove unnecessary logging. Remove debug System.out

github-actions bot removed module:jwt-auth cat:security labels Jan 27, 2026

SOLR-17436: fix merge conflicts

9f0ba30

Merge remote-tracking branch 'origin-solr/main' into SOLR-17436-V2-Metrics-API

igiguere requested a review from mlbiscoc January 27, 2026 23:31

SOLR-17436: Create a v2 equivalent for /admin/metrics #4057

Are you sure you want to change the base?

SOLR-17436: Create a v2 equivalent for /admin/metrics #4057

Conversation

igiguere commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Solution

Tests

Checklist

Uh oh!

gerlowskija left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gerlowskija left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gerlowskija Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

mlbiscoc Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gerlowskija Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

igiguere Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mlbiscoc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mlbiscoc Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

igiguere commented Jan 22, 2026

Uh oh!

igiguere commented Jan 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

igiguere commented Jan 16, 2026 •

edited

Loading

igiguere Jan 20, 2026 •

edited

Loading