SOLR-18417: Have a proper page on healthchecks by epugh · Pull Request #4886 · apache/solr

epugh · 2026-09-08T00:09:28Z

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

Description

Inspired by the upcoming removeal of "ping.adoc", this is a page on how to perform healthchecks.

Solution

A single page covering our Healthcheck API. I chose to only document the V2 one since that is our future. Did add docs on the healthcheck cli command too.

I think there might be room to add richer healthchecks in the future to our healthcheck api, like ones that run a query on a collection..

Tests

Docs.

gerlowskija · 2026-09-08T12:04:43Z

-The optional `maxGenerationLag=<n>` parameter specifies the maximum number of Lucene commit generations by which a follower is allowed to trail its leader; the endpoint returns HTTP 503 if any core exceeds this threshold.
-See xref:deployment-guide:user-managed-index-replication.adoc#monitoring-follower-replication-lag[Monitoring Follower Replication Lag] for details and examples.
+Health:: Report the health of the node, via the `api/node/health` endpoint ({solr-javadocs}/core/org/apache/solr/handler/admin/api/NodeHealth.html[NodeHealth]).
+See xref:deployment-guide:healthcheck.adoc[] for details, parameters, and examples.


[Q] Is there a reason you dropped the references to the v1 endpoint here?

yeah, we don't want v1, so why explain it? Maybe it should be listed until we remove V1? Happy to go whichever way you think...

gerlowskija · 2026-09-08T12:09:42Z

+
+See xref:user-managed-index-replication.adoc#monitoring-follower-replication-lag[Monitoring Follower Replication Lag] for details.
+
+== Collection Data Healthcheck


[0] I found this section-title a bit confusing, as it didn't appear in the summary table at the top of the page. Might be worth aligning that terminology.

yeah... glad you didn't like it, cause after i re-read it, I didn't lvoe it either, and was like... what the heck is "Collection Data" ;-)

okay, reworked the section title, and hoenstly, the whole paragraph.

gerlowskija · 2026-09-08T12:21:45Z

+== Collection Data Healthcheck
+
+Where the Node Health endpoint asks "is this process alive?", `bin/solr healthcheck` asks "does this collection actually work?"
+It queries the collection for a total document count, then queries each individual replica directly (non-distributed) for its own document count, and reports whether every shard has a leader and every replica is `ACTIVE`.


[Q] Is bin/solr healthcheck specific to SolrCloud? What would it do in stand-alone mode?

[Q] What is a user supposed to do with this per-replica docCount info? Healthy, well-functioning replicas often disagree on doc count just by nature of their autoCommit periods not being perfectly aligned. It might be worth flagging that for users, so they don't treat mismatches as "issues".

So, I just learned about the colour coding stuff that is in one of the cluster apis:

ClusterStatus.postProcessCollectionJSON()computes ahealthfield per shard and per collection —GREEN/YELLOW/ORANGE/RED, based on the fraction of ACTIVE` replicas and whether a leader exists. This computation exists nowhere else
in the codebase.

So that is interesting.....

I will check if hte CLI is cloud only.

And fair point on the counts. Also, I kind of want bin/solr healthcheck to optionally take in a query to deterimien "good/bad" ness... Maybe like the old ping did. That might be out of scope or a new thing to think trhoguh.

You know what, I think I won't hold this PR up on the GREEN/YELLOW/ORANGE/RED. That can be for the future beasue it wrequires coding.

[Q] Is bin/solr healthcheck specific to SolrCloud? What would it do in stand-alone mode?

What is "stand-alone" mode? I've heard of "user managed" mode. I actually don't know anything about how bin/solr heathcheck works in "stand-alone" mode. Probably the same way it works with Solr "embedded" mode? 🤷

[Q] What is a user supposed to do with this per-replica docCount info? Healthy, well-functioning replicas often disagree on doc count just by nature of their autoCommit periods not being perfectly aligned. It might be worth flagging that for users, so they don't treat mismatches as "issues".

Humm, interesting... I don't know how far into the minutia of solr cloud we want to go here... let me see...

Okay, I tried User Managed mode and:

➜ dev git:(introduce_healthcheck_focused_docs) ✗ bin/solr healthcheck -c techproducts Neither --solr-connection, --zk-host or --solr-url parameters, nor SOLR_CONNECTION, ZK_HOST env var provided, so assuming solr url is http://localhost:8983. Healthcheck tool only works in Solr Cloud mode.

gerlowskija · 2026-09-08T12:47:25Z

+
+== Coming From `/admin/ping`?
+
+Solr's older `/admin/ping` endpoint (`PingRequestHandler`) was deprecated in Solr 10.1 and removed in Solr 11.


[-1] IMO it does not make sense to continue to carry around documentation for features that have been removed from Solr. We don't do it for DIH, etc.

These sort of "If you used to use 'X', switch to 'Y'" notices are one of the main benefits of our changelog. IMO this should just go there.

I agree... After having writtne the text, my first thought was "does this live until solr 11 or 12 or when do we remove it". We do have a policy that we don't do this, so yeah, agreed.

gerlowskija · 2026-09-08T12:56:57Z

+Solr's older `/admin/ping` endpoint (`PingRequestHandler`) was deprecated in Solr 10.1 and removed in Solr 11.
+Unlike the Node Health endpoint, Ping executed a real, configurable query against a specific core -- so a passing ping meant the query path was actually functional, not just that the node was alive.
+
+If you configured a load balancer against `/admin/ping` specifically to catch a broken query path (not just a dead node), the Node Health endpoint is *not* a drop-in replacement -- it never touches the index.


[0] I personally don't know what a "broken query path" means. Maybe I'm just blanking, but if you end up retaining this section (see my comment on L174 above) then might be worth word-smithing that a bit.

so, I konw that some poeple would have a loadbalancer that would take a node out of rotation if sya it didn't have all the docs.. if you expected 10,000 docs, and your nightly job deletes and recreates the index, and it only go to 9,999 docs then it would be taken out by the load balancer.

this section was removed

epugh · 2026-09-16T19:13:47Z

Okay, I have done rewrites based on your feedback, would love one more review.

epugh · 2026-09-21T03:59:31Z

Going to merge on Monday.

Have a proper page on healthchecks

5955435

github-actions Bot added the documentation Improvements or additions to documentation label Sep 8, 2026

epugh mentioned this pull request Sep 8, 2026

SOLR-18417: Remove PingRequestHandler and related code #4874

Open

gerlowskija reviewed Sep 8, 2026

View reviewed changes

epugh requested a review from gerlowskija September 16, 2026 18:37

rewrites based on feedback

aaba439


		See xref:user-managed-index-replication.adoc#monitoring-follower-replication-lag[Monitoring Follower Replication Lag] for details.

		== Collection Data Healthcheck


		== Coming From `/admin/ping`?

		Solr's older `/admin/ping` endpoint (`PingRequestHandler`) was deprecated in Solr 10.1 and removed in Solr 11.

Conversation

epugh commented Sep 8, 2026

Description

Solution

Tests

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!

epugh commented Sep 16, 2026

Uh oh!

epugh commented Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants