From 9374bdf93f57ab7cfd3872f93629ef4fe4e2c654 Mon Sep 17 00:00:00 2001 From: Chris Bono Date: Tue, 26 Nov 2024 10:48:11 -0600 Subject: [PATCH] Add docs for health feature This commit adds docs for the server-side portion of the health feature. See #56 Signed-off-by: Chris Bono --- .../antora/modules/ROOT/pages/health.adoc | 27 +++++++++++++++++++ .../antora/modules/ROOT/pages/server.adoc | 5 +++- 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 spring-grpc-docs/src/main/antora/modules/ROOT/pages/health.adoc diff --git a/spring-grpc-docs/src/main/antora/modules/ROOT/pages/health.adoc b/spring-grpc-docs/src/main/antora/modules/ROOT/pages/health.adoc new file mode 100644 index 0000000..d48b419 --- /dev/null +++ b/spring-grpc-docs/src/main/antora/modules/ROOT/pages/health.adoc @@ -0,0 +1,27 @@ += Health + +:spring-boot-docs: https://docs.spring.io/spring-boot/reference + +Spring gRPC autoconfigures the standard https://grpc.io/docs/guides/health-checking/[gRPC Health service] for performing health check calls against gRPC servers. +The health service is registered with the gRPC server and a `HealthStatusManager` bean is provided that can be used to update the health status of your services. + +== Actuator Health +When Spring Boot Actuator is added to your project and the {spring-boot-docs}/actuator/endpoints.html#actuator.endpoints.health[Health endpoint] is available, the framework will automatically periodically update the health status of a configured list of Spring Boot {spring-boot-docs}/actuator/endpoints.html#actuator.endpoints.health.auto-configured-health-indicators[health indicators], including any ({spring-boot-docs}/actuator/endpoints.html#actuator.endpoints.health.writing-custom-health-indicators[custom indicators]). +By default, the aggregate status of the individual indicators is also used to update the overall server status (`""`). + +The following example uses `application.yml` to include the health status of the `db` and `redis` autoconfigured health indicators. + +[source,yaml,indent=0,subs="verbatim"] +---- +spring: + grpc: + server: + health: + actuator: + health-indicator-paths: + - db + - redis +---- +NOTE: The items in the `health-indicator-paths` are the identifiers of the indicator which is typically the name of the indicator bean without the `HealthIndicator` suffix. + +You can use the xref:appendix.adoc#common-application-properties["spring.grpc.server.health.*"] application properties to further configure the health feature. diff --git a/spring-grpc-docs/src/main/antora/modules/ROOT/pages/server.adoc b/spring-grpc-docs/src/main/antora/modules/ROOT/pages/server.adoc index 80ebdd2..33422b5 100644 --- a/spring-grpc-docs/src/main/antora/modules/ROOT/pages/server.adoc +++ b/spring-grpc-docs/src/main/antora/modules/ROOT/pages/server.adoc @@ -138,6 +138,9 @@ However, by setting the `blendWithGlobalInterceptors` attribute on the `@GrpcSer You can use this option if you want to add a per-service interceptor between global interceptors. ==== +[[health]] +include::health.adoc[leveloffset=+1] + == Observability Spring gRPC provides an autoconfigured interceptor that can be used to provide observability to your gRPC services. @@ -154,4 +157,4 @@ A `GrpcExceptionHandler` can be used to handle exceptions of a specific type, re If you include `spring-grpc-test` in your project, your gRPC server in a `@SpringBootTest` will be started in-process (i.e. not listening on a network port). All clients that connect to any server via the autoconfigured `GrpcChannelFactory` will be able to connect to it. -You can switch the in-process server off by setting `spring.grpc.in-process.enabled` to `false`. \ No newline at end of file +You can switch the in-process server off by setting `spring.grpc.in-process.enabled` to `false`.