From 87393ab6d0c61e76bda7cbc66f093d0cda0021bd Mon Sep 17 00:00:00 2001 From: Marcos Huck Date: Tue, 17 Dec 2024 00:30:33 -0300 Subject: [PATCH 1/2] Add List endpoint to gRPC Health service This proposal introduces a new `List` RPC endpoint for the Health service, allowing clients to retrieve the statuses of all monitored services or a filtered list of specific services. This feature simplifies integration with status-reporting dashboards and enhances observability for microservices. --- A##-list-health.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 A##-list-health.md diff --git a/A##-list-health.md b/A##-list-health.md new file mode 100644 index 000000000..b4ad46a72 --- /dev/null +++ b/A##-list-health.md @@ -0,0 +1,59 @@ +# Add List endpoint to gRPC Health service + +* **Author(s):** Marcos Huck. +* **Approver:** TBD +* **Status:** Draft +* **Implemented in:** TBD +* **Last updated:** 2024-12-17 +* **Discussion at:** TBD + + +## Abstract + +This proposal introduces a new `List` RPC endpoint for the Health service, allowing clients to retrieve the statuses of all monitored services or a filtered list of specific services. This feature simplifies integration with status-reporting dashboards and enhances observability for microservices. + +## Background + +The existing Health service provides basic health check functionality but lacks a mechanism to retrieve a comprehensive list of all monitored servicesand their statuses. + +This limitation makes it challenging for clients to aggregate health information across multiple services, particularly for use cases like publishing service statuses to dashboards such as [Cachet](https://cachethq.io/) or [Statuspage](https://www.atlassian.com/software/statuspage). + +Kubernetes provides a similar capability with its `/readyz?verbose` endpoint, which lists the status of all components.This proposal aims to bring analogous functionality to the Health service, providing a unified view of service health. + +### Related Proposals + +N/A + +## Proposal + +Introduce a new `List` RPC endpoint in the Health service with the following features: + +- Retrieve the health statuses of all monitored services or a filtered list of specified services. +- Ensure the implementation is idempotent and side-effect free. +- Provide a clear schema for the request and response to facilitate integration with external tools. + +### Proposed API Changes + +https://github.com/grpc/grpc-proto/pull/143 + +### Temporary environment variable protection + +N/A + +## Rationale + +Adding the List RPC endpoint to the Health service strikes a balance between functionality and simplicity. + +### Alternative approaches +- Separate Service: Extract the new functionality into a standalone service. This avoids altering the existing Health service API but increases complexity by introducing another service for clients to interact with. + +## Implementation + +1. Add the `List` RPC endpoint and the associated request/response messages in the Health service .proto file. +2. Update client libraries to support the `List` endpoint. Provide examples demonstrating how to call the endpoint and handle its response. +3. Unit tests to validate the behavior of the new endpoint. +4. Update API documentation to describe the new endpoint, its use cases, and sample requests/responses. + +## Open issues (if applicable) + +N/A From e0f503e5054760802818052207a1c580f64614c1 Mon Sep 17 00:00:00 2001 From: Marcos Huck Date: Thu, 19 Dec 2024 00:03:58 -0300 Subject: [PATCH 2/2] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Benjamin Krämer --- A##-list-health.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/A##-list-health.md b/A##-list-health.md index b4ad46a72..dea2866a9 100644 --- a/A##-list-health.md +++ b/A##-list-health.md @@ -1,6 +1,6 @@ # Add List endpoint to gRPC Health service -* **Author(s):** Marcos Huck. +* **Author(s):** Marcos Huck * **Approver:** TBD * **Status:** Draft * **Implemented in:** TBD @@ -14,11 +14,11 @@ This proposal introduces a new `List` RPC endpoint for the Health service, allow ## Background -The existing Health service provides basic health check functionality but lacks a mechanism to retrieve a comprehensive list of all monitored servicesand their statuses. +The existing Health service provides basic health check functionality but lacks a mechanism to retrieve a comprehensive list of all monitored services and their statuses. This limitation makes it challenging for clients to aggregate health information across multiple services, particularly for use cases like publishing service statuses to dashboards such as [Cachet](https://cachethq.io/) or [Statuspage](https://www.atlassian.com/software/statuspage). -Kubernetes provides a similar capability with its `/readyz?verbose` endpoint, which lists the status of all components.This proposal aims to bring analogous functionality to the Health service, providing a unified view of service health. +Kubernetes provides a similar capability with its `/readyz?verbose` endpoint, which lists the status of all components. This proposal aims to bring analogous functionality to the Health service, providing a unified view of service health. ### Related Proposals