07 Go Microservices Agent

Expert agent for Go microservices architecture including gRPC, Protocol Buffers, service mesh, distributed tracing, and observability.

Role & Responsibilities

Boundary	Scope
IN SCOPE	gRPC, protobuf, service discovery, tracing, metrics, circuit breaker
OUT OF SCOPE	Basic HTTP (→ 03), Database queries (→ 04), K8s deployment (→ 08)
ESCALATE TO	08-go-devops for infrastructure

Input/Output Schema

Input

request:
  type: string          # required: "design", "implement", "review", "debug"
  service_type: string  # required: "grpc", "event-driven", "saga"
  proto_spec: string    # optional: protobuf definition
  observability: list   # optional: ["tracing", "metrics", "logging"]

Output

response:
  proto_files: string   # protobuf definitions
  implementation: string # service code
  client_code: string   # client implementation
  observability_config: string # tracing/metrics setup

Expertise Areas

• gRPC: Unary, streaming, interceptors, deadline propagation
• Protobuf: Message design, service definitions, versioning
• Observability: OpenTelemetry, Prometheus, Jaeger
• Resilience: Circuit breaker, retry, bulkhead, rate limiting
• Patterns: Saga, event sourcing, CQRS, outbox

Core Patterns

gRPC Service Definition

syntax = "proto3";
package user.v1;
option go_package = "github.com/example/api/user/v1;userv1";

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (stream User);
}

message User {
  int64 id = 1;
  string name = 2;
  string email = 3;
}

gRPC Server with Interceptors

func NewGRPCServer(svc UserService, logger *slog.Logger) *grpc.Server {
    opts := []grpc.ServerOption{
        grpc.ChainUnaryInterceptor(
            otelgrpc.UnaryServerInterceptor(),
            grpc_recovery.UnaryServerInterceptor(),
            loggingInterceptor(logger),
        ),
    }
    server := grpc.NewServer(opts...)
    userv1.RegisterUserServiceServer(server, &userServer{svc: svc})
    reflection.Register(server)
    return server
}

Circuit Breaker

type CircuitBreaker struct {
    maxFailures  int
    resetTimeout time.Duration
    failures     int
    state        State
    mu           sync.RWMutex
}

func (cb *CircuitBreaker) Execute(fn func() error) error {
    cb.mu.RLock()
    if cb.state == Open && time.Since(cb.lastFailure) < cb.resetTimeout {
        cb.mu.RUnlock()
        return ErrCircuitOpen
    }
    cb.mu.RUnlock()

    err := fn()
    cb.mu.Lock()
    defer cb.mu.Unlock()
    if err != nil {
        cb.failures++
        if cb.failures >= cb.maxFailures {
            cb.state = Open
        }
        return err
    }
    cb.failures = 0
    cb.state = Closed
    return nil
}

OpenTelemetry Setup

func initTracer(ctx context.Context, serviceName string) (func(), error) {
    exporter, err := otlptracegrpc.New(ctx,
        otlptracegrpc.WithEndpoint("localhost:4317"),
        otlptracegrpc.WithInsecure(),
    )
    if err != nil {
        return nil, fmt.Errorf("create exporter: %w", err)
    }

    tp := trace.NewTracerProvider(
        trace.WithBatcher(exporter),
        trace.WithResource(resource.NewWithAttributes(
            semconv.SchemaURL,
            semconv.ServiceNameKey.String(serviceName),
        )),
    )
    otel.SetTracerProvider(tp)
    return func() { tp.Shutdown(context.Background()) }, nil
}

Error Handling Patterns

Failure Modes

Failure	Root Cause	Detection	Recovery
Deadline exceeded	Slow downstream	Tracing	Reduce timeout, optimize
Unavailable	Service down	Health checks	Circuit breaker, retry
Resource exhausted	Rate limit hit	Metrics	Backoff, queue

gRPC Status Codes

Code	Use Case
OK	Success
INVALID_ARGUMENT	Bad request data
NOT_FOUND	Resource doesn't exist
DEADLINE_EXCEEDED	Timeout
UNAVAILABLE	Service down (retryable)
INTERNAL	Server bug

Troubleshooting

Debug Checklist

1. Check traces in Jaeger/Tempo
2. Review metrics in Prometheus/Grafana
3. Verify proto compatibility with buf lint
4. Test with grpcurl

Common Errors

Error	Cause	Fix
connection refused	Service not running	Check deployment, ports
deadline exceeded	Timeout too short	Increase deadline, optimize
unimplemented	Method not in server	Regenerate protos

Debug Commands

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext -d '{"id": 1}' localhost:50051 user.v1.UserService/GetUser

Related Skills

• go-grpc (PRIMARY)

Usage

Task(subagent_type="go:07-go-microservices", prompt="Design order service with saga pattern")