TopolearnOrchestrators and humans both need to probe gRPC services without generated code.
Binary protocols are harder to poke at than JSON, so the gRPC ecosystem standardizes a few services every server should consider exposing.
Health checking (grpc.health.v1.Health) has Check and Watch methods that return SERVING or NOT_SERVING for the whole server or a named service. Kubernetes supports gRPC probes natively (grpc: probe with a port), and load balancers use the same protocol. In Node, the grpc-health-check package implements it.
Server reflection lets a client ask the server for its proto descriptors at runtime. Tools then call any method without having the .proto file locally. In Node, use @grpc/reflection. Enable it in development and internal environments; consider disabling it on public endpoints.
grpcurl is the curl of gRPC:
grpcurl -plaintext localhost:50051 listlists services (needs reflection, or pass-proto file.proto).grpcurl -plaintext -d '{"name":"Ann"}' localhost:50051 hello.v1.Greeter/SayHellocalls a method with JSON that grpcurl converts to protobuf.-H 'authorization: Bearer ...'adds metadata;-max-timesets a deadline.
GUI options include Postman, Insomnia and grpcui. For logs, record the full method name, status code, duration and peer: that line answers most production questions.
Example
# list services (server reflection enabled)
grpcurl -plaintext localhost:50051 list
# grpc.health.v1.Health
# hello.v1.Greeter
# describe a method's request/response types
grpcurl -plaintext localhost:50051 describe hello.v1.Greeter.SayHello
# call it with JSON; grpcurl encodes protobuf for you
grpcurl -plaintext -d '{"name": "Ann"}' \
-H 'authorization: Bearer dev-token' \
localhost:50051 hello.v1.Greeter/SayHello
# { "message": "Hello, Ann" }
# without reflection: point at the .proto
grpcurl -plaintext -proto hello.proto -d '{"name":"Ann"}' \
localhost:50051 hello.v1.Greeter/SayHello
# health check
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check
# { "status": "SERVING" }Remember
- Implement grpc.health.v1.Health for probes and load balancers
- Server reflection lets tools discover methods at runtime
- grpcurl calls methods using JSON from the terminal
Watch out for
- Exposing reflection on a public endpoint you meant to keep undocumented.