Skip to main content Link Menu Expand (external link) Document Search Copy Copied

ColdBrew

A Kubernetes-native Go microservice framework for building production-grade gRPC services with built-in observability, resilience, and HTTP gateway support. Follows 12-factor principles out of the box.

Production-proven: Powers 100+ microservices, handling peaks of ~70k QPS per service at Gojek.

Get Started View Packages How To GitHub

What You Get Out of the Box

Feature Description
gRPC + REST Gateway Define your API once in protobuf — get gRPC, REST, and Swagger docs automatically via grpc-gateway
Structured Logging Pluggable backends (go-kit, zap, logrus) with per-request context fields and trace ID propagation
Distributed Tracing OpenTelemetry, Jaeger, and New Relic support with automatic span creation in interceptors
Prometheus Metrics Built-in request latency, error rate, and circuit breaker metrics at /metrics
Error Tracking Stack traces, gRPC status codes, and async notification to Sentry, Rollbar, or Airbrake
Resilience Client-side circuit breaking and retries via interceptors
Fast Serialization vtprotobuf codec enabled by default — faster gRPC marshalling with automatic fallback to standard protobuf
Kubernetes-native Health/ready probes, graceful SIGTERM shutdown, structured JSON logs, Prometheus metrics — all wired automatically
Swagger / OpenAPI Interactive API docs auto-served at /swagger/ from your protobuf definitions
Profiling Go pprof endpoints at /debug/pprof/ for CPU, memory, goroutine, and trace profiling
gRPC Reflection Server reflection enabled by default — works with grpcurl, grpcui, and Postman
HTTP Compression Automatic gzip compression for all HTTP gateway responses
Container-aware Runtime Auto-tunes GOMAXPROCS to match container CPU limits via automaxprocs

Quick Start

Generate a new service in seconds:

# Install cookiecutter
brew install cookiecutter  # or: pip install cookiecutter

# Generate a new service
cookiecutter gh:go-coldbrew/cookiecutter-coldbrew

# Build and run
cd MyService/
make run

Your service starts with all of these endpoints ready:

Endpoint Description
localhost:9090 gRPC server
localhost:9091 HTTP/REST gateway (auto-mapped from gRPC)
localhost:9091/metrics Prometheus metrics
localhost:9091/healthcheck Liveness probe — returns build/version info as JSON
localhost:9091/readycheck Readiness probe — returns version JSON when ready
localhost:9091/swagger/ Swagger UI
localhost:9091/debug/pprof/ Go pprof profiling

Define Once, Get Everything

Your API is defined once in protobuf — ColdBrew generates everything else:

rpc Echo(EchoRequest) returns (EchoResponse) {
    option (google.api.http) = {
        post: "/api/v1/echo"
        body: "*"
    };
}

This single definition gives you:

  • gRPC endpoint on :9090 — with reflection for grpcurl and Postman
  • REST endpoint at POST /api/v1/echo on :9091 — via grpc-gateway
  • Swagger UI at /swagger/ — interactive API docs from your proto
  • Prometheus metrics — per-method latency, error rate, and request count
  • Distributed tracing — automatic span creation through the interceptor chain

Run buf generate — it creates typed Go interfaces from your proto definitions. The compiler ensures every RPC method is implemented, so API changes are caught at build time, not runtime. Just fill in your business logic and make run. Logging, tracing, metrics, health checks, and graceful shutdown are wired automatically. See the full pipeline for details.

How It Works 

                    ┌─────────────────────────────────────────┐
                    │              ColdBrew Core               │
   HTTP Request ──► │  ┌─────────┐    ┌────────────────────┐  │
                    │  │  HTTP    │    │  Interceptor Chain  │  │
                    │  │ Gateway  │──► │                     │  │
                    │  │ (grpc-  │    │  ► Response Time    │  │
   gRPC Request ──► │  │ gateway)│    │  ► Trace ID         │  │
                    │  └─────────┘    │  ► Context Tags     │  │
                    │       │         │  ► OpenTelemetry     │  │
                    │       ▼         │  ► Prometheus        │  │
                    │  ┌─────────┐    │  ► Error Notify      │  │
                    │  │  gRPC   │──► │  ► Panic Recovery    │  │──► Your Handler
                    │  │ Server  │    │                     │  │
                    │  └─────────┘    └────────────────────┘  │
                    │                                         │
                    │  /metrics  /healthcheck  /debug/pprof   │
                    └─────────────────────────────────────────┘

Packages

ColdBrew is modular — use the full framework or pick individual packages:

Package What It Does
core gRPC server + HTTP gateway, health checks, graceful shutdown
interceptors Server/client interceptors for logging, tracing, metrics, retries
errors Enhanced errors with stack traces and gRPC status codes
log Structured logging with pluggable backends
tracing Distributed tracing (OpenTelemetry, Jaeger, New Relic)
options Request-scoped key-value store via context
grpcpool Round-robin gRPC connection pool
data-builder Dependency injection with parallel execution

Each package can be used independently — you don’t need core to use errors or log.

Don’t Repeat Yourself

ColdBrew integrates with the tools you already use:

Next Steps