Skip to content

Open-source status page, incident response and uptime monitoring

grpc: small improvment (#2647)

Thibault Le Ouay7b5b4e71cd5e
diff --git a/apps/dashboard/src/components/forms/monitor/form-general.tsx b/apps/dashboard/src/components/forms/monitor/form-general.tsx
index 7ecbc4250..efc5b6602 100644
--- a/apps/dashboard/src/components/forms/monitor/form-general.tsx
+++ b/apps/dashboard/src/components/forms/monitor/form-general.tsx
@@ -856,7 +856,9 @@ export function FormGeneral({
<FormMessage />
<FormDescription>
The service name passed to grpc.health.v1.Health/Check.
- Leave empty to check overall server health.
+ Leave empty to check overall server health. This is a
+ service name, not a method path: entering
+ grpc.health.v1.Health itself returns SERVICE_UNKNOWN.
</FormDescription>
</FormItem>
)}
diff --git a/apps/web/src/content/pages/docs/reference/grpc-monitor.mdx b/apps/web/src/content/pages/docs/reference/grpc-monitor.mdx
index 39eed154c..5eccffd01 100644
--- a/apps/web/src/content/pages/docs/reference/grpc-monitor.mdx
+++ b/apps/web/src/content/pages/docs/reference/grpc-monitor.mdx
@@ -52,6 +52,12 @@ The service name sent in the health check request. Leave it empty to check the s
**Example:** `checkout.v1.CheckoutService`
+<Aside type="caution">
+This is a service name, not a method path. `grpc.health.v1.Health` is the health service the monitor already calls — putting it here asks the server whether it has registered a service *called* `grpc.health.v1.Health`, which almost no server does, and the check comes back `SERVICE_UNKNOWN`. Leave the field empty unless you register per-service health status.
+</Aside>
+
+Servers differ on how they answer for a name they do not know: the reference implementations return the `NOT_FOUND` status code, while some return the `SERVICE_UNKNOWN` enum value. Both are reported as `SERVICE_UNKNOWN`.
+
### TLS
**Type:** Enum (optional)
@@ -135,6 +141,27 @@ The OTLP endpoint URL where metrics are exported. gRPC monitors export the total
Custom headers to include when sending metrics to your OTLP endpoint, commonly used for authentication or tenant identification.
+## Checking with grpcurl
+
+Every monitor configuration maps onto a [`grpcurl`](https://github.com/fullstorydev/grpcurl) command, so you can confirm a target answers before creating the monitor — and reproduce a failing check from your own terminal.
+
+| Monitor configuration | Equivalent command |
+| --- | --- |
+| Default (TLS, no service) | `grpcurl example.com:443 grpc.health.v1.Health/Check` |
+| A named service | `grpcurl -d '{"service":"checkout.v1.CheckoutService"}' example.com:443 grpc.health.v1.Health/Check` |
+| TLS (skip verification) | `grpcurl -insecure example.com:443 grpc.health.v1.Health/Check` |
+| Plaintext (h2c) | `grpcurl -plaintext example.com:50051 grpc.health.v1.Health/Check` |
+
+A serving target answers:
+
+```json
+{
+ "status": "SERVING"
+}
+```
+
+If `grpcurl` succeeds and the monitor does not, the difference is almost always the TLS mode: pointing a plaintext monitor at a TLS endpoint fails the connection before any health request is sent, and is reported as `UNAVAILABLE`.
+
## Related resources
- **[Create your first monitor](/docs/tutorial/create-your-first-monitor)** — step-by-step tutorial on setting up a monitor.