docs: document exposed Prometheus metrics and health status encoding

[unseenmagik]

Documents the Prometheus metrics exposed when ENABLE_METRICS=TRUE.

opensearch_cluster_health_status encodes 2 = green, 1 = yellow, 0 = red, which is the inverse of the elasticsearch_exporter convention where a higher value means worse health. The encoding is documented nowhere, and a healthy cluster reports a constant 2 indefinitely — which is what led me to file #374 as a stuck-gauge bug when the gauge was in fact correct.

Adds to the Metrics section:

• the full list of OpenSearch gauges with their exact scrape names, taken from upstream's ApiMetricsTest
• a callout on the health status encoding, with the correct alert expression (< 2)
• a note that all OpenSearch gauges are served from one snapshot Photon refreshes at most every 30s, so scraping faster than that returns repeated values

Docs only, no behaviour change.

The metrics themselves come from Photon, not this image, so I opened komoot/photon#1123 to add the same information to the gauge # HELP text at the source.

Closes #374

🤖 Generated with Claude Code

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 4dedc612-9543-4066-9e23-cf6109583919

📥 Commits

Reviewing files that changed from the base of the PR and between 0c2db44 and d56a19a.

📒 Files selected for processing (1)

• README.md

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The README adds an Exposed Metrics section. It documents Photon’s OpenSearch Prometheus gauges, cluster health encoding, alert threshold, and 30-second snapshot refresh interval.

Changes

OpenSearch metrics documentation

Layer / File(s)	Summary
Metrics reference README.md	Documents the exposed gauges, cluster health values, recommended alert threshold, and snapshot staleness of up to 30 seconds.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Merge Risk: ⚪ Minimal · up to d56a1

This updates the OpenSearch metrics reference with health encoding, alert guidance, and snapshot refresh behavior. No merge-readiness risk remains.

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The pull request documents the reported metric behaviour, but it does not implement the linked issue's expected fix for refreshing opensearch_cluster_health_status to reflect current cluster health …	Implement or link to the code change that refreshes opensearch_cluster_health_status according to the requirements in #374, or update the issue linkage and acceptance criteria to state that documentation alone resolves the issue.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the documentation change and the Prometheus health status encoding covered by the pull request.
Description check	✅ Passed	The description accurately explains the documented metrics, health status encoding, refresh interval, and absence of behaviour changes.
Out of Scope Changes check	✅ Passed	The pull request changes only the README and documents the Prometheus metrics described in its objectives. No unrelated changes are present.

Full details: Linked Issues check

Explanation

The pull request documents the reported metric behaviour, but it does not implement the linked issue's expected fix for refreshing opensearch_cluster_health_status to reflect current cluster health on each scrape [#374].

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}