perf-test-server-grpc

A small, high-performance gRPC server written in Go, designed for load-testing and performance benchmarking of gRPC infrastructure.

Features

• Four gRPC RPCs covering typical load-test scenarios: plain ping, no-log ping, health/liveness degradation, and static file serving.
• Structured access logging via Go's log/slog (disable with NOLOG=1).
• gRPC reflection enabled — works out of the box with grpcurl and ghz.
• Graceful shutdown on SIGINT / SIGTERM.
• Distroless runtime image — minimal attack surface, tiny container.
• Statically linked binary — CGO_ENABLED=0, runs on any Linux x86-64 host.

---

gRPC API

Service: perftest.v1.PerfTestService
Proto: proto/perftest/v1/perftest.proto

RPC	Request	Response	Description
Ping	PingRequest	PingResponse	Returns "Hello World!". Logging follows NOLOG setting.
PingNoLog	PingRequest	PingResponse	Returns "Hello World!". Always unlogged.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Returns healthy for first HEALTHCOUNT calls; codes.Internal thereafter.
GetFile	GetFileRequest{name}	GetFileResponse{content, content_type}	Returns a file from the embedded testfiles/ directory.

---

Environment Variables

Variable	Default	Description
PORT	8000	TCP port to listen on.
CORES	system CPU count	Printed at startup (informational).
NOLOG	(unset)	Set to any non-empty value (e.g. 1) to disable access logging entirely.
HEALTHCOUNT	3	Number of healthy HealthCheck responses before switching to unhealthy.
DIE_FAST	(unset)	Set to an integer N: sleep N seconds then exit with code -1. Useful for testing crash recovery.

---

Building

Prerequisites

• Go 1.24+
• protoc (Protocol Buffers compiler)
• protoc-gen-go and protoc-gen-go-grpc plugins

# Install plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Build commands

# Generate gRPC Go code from proto
make proto

# Build the server binary
make build

# Run tests
make test

# Build the Docker image
make docker

# All of the above
make all

The binary is output as ./perf-test-server-grpc.

---

Running

Locally

./perf-test-server-grpc
# or with custom settings:
PORT=9001 HEALTHCOUNT=10 ./perf-test-server-grpc

Docker

# Default: logging enabled, port 8000
docker run --rm -p 8000:8000 perf-test-server-grpc

# Disable access logging:
docker run --rm -p 8000:8000 -e NOLOG=1 perf-test-server-grpc

# Custom port:
docker run --rm -p 9001:9001 -e PORT=9001 perf-test-server-grpc

---

Manual Testing with grpcurl

# Ping
grpcurl -plaintext localhost:8000 perftest.v1.PerfTestService/Ping

# PingNoLog (never produces access-log entries)
grpcurl -plaintext localhost:8000 perftest.v1.PerfTestService/PingNoLog

# HealthCheck (call 4+ times to observe the unhealthy response)
grpcurl -plaintext localhost:8000 perftest.v1.PerfTestService/HealthCheck

# GetFile
grpcurl -plaintext -d '{"name": "test.txt"}' localhost:8000 perftest.v1.PerfTestService/GetFile

---

Load Testing with ghz

# Ping — sustained load
ghz --insecure \
  --proto proto/perftest/v1/perftest.proto \
  --call perftest.v1.PerfTestService.Ping \
  -n 1000000 -c 100 \
  localhost:8000

# PingNoLog — zero-logging baseline
ghz --insecure \
  --proto proto/perftest/v1/perftest.proto \
  --call perftest.v1.PerfTestService.PingNoLog \
  -n 1000000 -c 100 \
  localhost:8000

# GetFile
ghz --insecure \
  --proto proto/perftest/v1/perftest.proto \
  --call perftest.v1.PerfTestService.GetFile \
  -d '{"name":"test.txt"}' \
  -n 100000 -c 50 \
  localhost:8000

---

Project Structure

perf-test-server-grpc/
├── src/
│   ├── cmd/server/       # main entry point
│   ├── gen/perftest/v1/  # protoc-generated Go code (committed)
│   └── internal/server/  # service implementation, interceptor, tests
│       └── testfiles/    # embedded static files (test.txt)
├── proto/perftest/v1/    # protobuf source (contract spec)
├── deployment/           # drove.json deployment descriptor
├── .github/workflows/    # CI/CD
├── Dockerfile
├── Makefile
├── go.mod / go.sum
└── README.md

---

License

Apache License 2.0 — see LICENSE for details.