HYPERFLEET-1256 - docs: add consolidated observability reference - #187
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdded Estimated code review effort: 1 (Trivial) | ~3 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 11✅ Passed checks (11 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hyperfleet/docs/observability.md`:
- Around line 60-64: Update the Sentinel “Metrics Documentation” link in the
observability documentation to reference docs/metrics.md instead of the stale
docs/sentinel-operator-guide.md path, while leaving the repository and
Architecture Doc links unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Central YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: bbd0ec44-d093-4d68-bfa6-64cb57fe9d85
📒 Files selected for processing (2)
README.mdhyperfleet/docs/observability.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
openshift-hyperfleet/architecture(manual)openshift-hyperfleet/hyperfleet-api(manual)openshift-hyperfleet/hyperfleet-sentinel(manual)openshift-hyperfleet/hyperfleet-adapter(manual)openshift-hyperfleet/hyperfleet-broker(manual)
| - [Health Endpoints Standard](../standards/health-endpoints.md) — Health check conventions | ||
| - [Logging Specification](../standards/logging-specification.md) — Structured logging format | ||
| - [Tracing Standard](../standards/tracing.md) — Distributed tracing conventions | ||
|
|
There was a problem hiding this comment.
Since we are consolidating this -- should we also include information about how to set up prometheus for each component?
There was a problem hiding this comment.
Prometheus setup instructions are deployment-specific and vary by environment (GKE Managed Prometheus, self-hosted Prometheus Operator, cloud-native alternatives). This reference focuses on the architectural contract (ports, endpoints, naming) that remains constant across deployments. This cloud-agnostic contract ensures HyperFleet components work with any Prometheus-compatible system, leaving the deployment choice to operators based on their specific environment.
|
@ldornele are we missing the broker reference in the doc? The ticket mentions broker alongside sentinel/adapters. |
| | | [Helm Chart Conventions](hyperfleet/standards/helm-chart-conventions.md) | Chart structure, values schema, and naming conventions | | ||
| | **Process** | [Ticket Hygiene](hyperfleet/standards/ticket-hygiene.md) | JIRA ticket field requirements and sprint readiness | | ||
|
|
||
| **See also**: [Observability Reference](hyperfleet/docs/observability.md) — consolidated metrics reference for HyperFleet's deployable components |
There was a problem hiding this comment.
Move this section down below to
### 4. Implementation Guides (`docs/`)
There was a problem hiding this comment.
Removed — Implementation Guides section doesn't list specific docs (unlike the Standards table). The observability reference is discoverable via hyperfleet/docs/ navigation.
Does that make sense? TY
|
|
||
| --- | ||
|
|
||
| ## Component Metrics Endpoints |
There was a problem hiding this comment.
| ## Component Metrics Endpoints | |
| ## Component Metrics/Health Endpoints | |
| Metrics are exposed on **port 9090** at the `/metrics` endpoint. | |
| Health statuses exposed on **port 8080 ** at the `/readyz` and `/healthz` andpoint. |
Maybe something like this? Or don't include the health endpoints at all?
There was a problem hiding this comment.
Updated section title and description to cover both metrics and health endpoints
|
Now that this consolidated reference exists, consider adding a link to it from the Metrics Standard (and maybe Health Endpoints) under the component-specific metrics sections. That would make this the discoverable entry point from the standards, not only from the README. |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@hyperfleet/docs/observability.md`:
- Around line 36-45: Update the universal endpoint statement in the
observability documentation to qualify it as applying only to the listed
deployable components. Add an explicit note that hyperfleet-broker does not
expose standalone metrics or health endpoints because these are surfaced through
the Adapter, while preserving the existing endpoint table.
- Line 47: Update the observability documentation note to describe port 9090 and
port 8080 as separate listener ports, not network isolation. If isolation is
intended, document the concrete NetworkPolicy, firewall, or ACL mechanism that
enforces it; otherwise remove the isolation claim.
- Around line 43-47: Resolve the API health-port inconsistency between the
observability contract and the runbook: update the API health check in
docs/runbook.md to use the contract’s authoritative health port, while keeping
REST requests on port 8000. Ensure the API entry in observability.md and the
runbook agree before publishing the contract.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Central YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: 5743e6fc-2b84-4347-a3e1-3e8e8020b998
📒 Files selected for processing (1)
hyperfleet/docs/observability.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
openshift-hyperfleet/architecture(manual)openshift-hyperfleet/hyperfleet-api(manual)openshift-hyperfleet/hyperfleet-sentinel(manual)openshift-hyperfleet/hyperfleet-adapter(manual)openshift-hyperfleet/hyperfleet-broker(manual)
| **Notes:** | ||
|
|
||
| - Components expose separate listener ports: `:9090` for metrics, `:8080` for health checks | ||
| - The API service also exposes REST endpoints on port `:8000` | ||
| - **Broker**: `hyperfleet-broker` is an embedded library ([broker.md](../components/broker/broker.md)), not a standalone service — it does not expose its own endpoints. Broker metrics and health checks are surfaced through the embedding component (Adapter) |
There was a problem hiding this comment.
Broker metrics are also surfaced through Sentinel, not only Adapter. Sentinel embeds hyperfleet-broker and exposes hyperfleet_broker_* on its own /metrics endpoint. Worth wording this as embedding components (Sentinel and Adapter).
There was a problem hiding this comment.
Fixed — both Sentinel and Adapter embed the broker.
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: pnguyen44 The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
326641c
into
openshift-hyperfleet:main
4 participants
Summary
Creates consolidated observability reference documentation for all HyperFleet components, providing a single source of truth for metrics endpoints, health checks, and monitoring setup.
JIRA: HYPERFLEET-1256
What Changed
New File
hyperfleet/docs/observability.md— Consolidated observability reference covering::9090/metrics) for API, Sentinel, Adapter Framework:8080/healthz,:8080/readyz) per Health Endpoints StandardUpdated Files
README.md— Added "See also" reference to Observability Reference below the Observability standards table