gRPC Health Checks

Monitor gRPC services with configurable host, port, service name, and TLS settings.

Overview

gRPC health checks in upti.my use the standard gRPC Health Checking Protocol to verify that your gRPC services are operational. This protocol is the recommended way to monitor gRPC services and is supported by most gRPC frameworks out of the box.

The check establishes a connection to your gRPC server, sends a health check RPC call, and validates the response status. You can monitor the overall server health or check individual service names for more granular visibility.

Configuration

Parameter	Description	Default
Host	The hostname or IP address of your gRPC server	Required
Port	The port number your gRPC server listens on	`9090`
Service Name	The specific gRPC service to check. Leave empty to check the overall server health.	Empty (server-level check)
TLS Enabled	Toggle TLS encryption for the gRPC connection	Off

💡 Service Name

If your gRPC server hosts multiple services, specify the service name to check each one independently. This lets you detect when a specific service is unhealthy while the server itself is still accepting connections.

How It Works

The gRPC health check follows the standard Health Checking Protocol defined in the grpc.health.v1 package. When a check runs, upti.my performs these steps:

Establishes a TCP connection to the specified host and port
Performs a TLS handshake if TLS is enabled
Sends a Check RPC to the grpc.health.v1.Health service
Evaluates the response status (SERVING, NOT_SERVING, UNKNOWN, or SERVICE_UNKNOWN)

The check is considered successful only when the response status is SERVING. Any other status, connection failure, or timeout is treated as a failure.

Response Data

Each gRPC health check execution captures the following data:

Field	Description
gRPC Status	The health check response status (SERVING, NOT_SERVING, UNKNOWN, SERVICE_UNKNOWN)
Service Name	The service name that was checked
Connection Time	Time taken to establish the TCP connection and optional TLS handshake
RPC Call Time	Time taken to complete the health check RPC call
Connect Error	Details if the connection could not be established
Check Error	Details if the health check RPC failed after connecting

Example Configuration

gRPC Check Configuration

{
  "host": "grpc.example.com",
  "port": 9090,
  "service_name": "my.package.MyService",
  "tls_enabled": true,
  "timeout_seconds": 10,
  "interval_seconds": 30
}

Implementing the Health Check Protocol

Your gRPC server must implement the standard health checking service to work with upti.my. Here is a minimal example using Go:

main.go

import (
    "google.golang.org/grpc/health"
    healthpb "google.golang.org/grpc/health/grpc_health_v1"
)

// Register the health service on your gRPC server
healthServer := health.NewServer()
healthpb.RegisterHealthServer(grpcServer, healthServer)

// Set the serving status for a specific service
healthServer.SetServingStatus(
    "my.package.MyService",
    healthpb.HealthCheckResponse_SERVING,
)

ℹ️ Framework Support

Most gRPC frameworks provide built-in support for the health checking protocol. Check your framework's documentation for specific implementation details. Popular frameworks like Go gRPC, Java gRPC, and Python grpcio all include health check utilities.

⚠️ Firewall and Network Access

Ensure that the gRPC port is accessible from upti.my's monitoring nodes. If your service is behind a firewall or in a private network, consider using an upti.my agent for local monitoring.