sdk

README

go-sdk

Shared logging, error handling, HTTP client, metrics and health-check building blocks for Go services built on Gin.

This consolidates what tends to end up as nearly-identical, independently copy-pasted logging middleware and error-handling code into one maintained module, and adds a piece that's easy to skip when each service is on its own: a correlation ID that actually survives a request across service boundaries.

Packages

• apperr — the canonical AppError type (HTTP status + public message + wrapped internal error with a stack trace via github.com/pkg/errors).
• logging — Gin middleware: reads an inbound X-Trace-Id header if present (otherwise mints one), injects a zerolog logger carrying it into the request context, logs method/path/status/duration/client_ip per request, and attaches a stack trace to the log line for any error raised via apperr.
• httpclient — httpclient.New(timeout) builds an *http.Client whose transport automatically forwards the correlation ID from the request context as X-Trace-Id on outbound calls. Use this instead of &http.Client{} in every internal service resource client — this is what makes cross-service correlation actually work.
• metrics — HTTPRequestsTotal/HTTPRequestDuration Prometheus metrics and an Instrument() Gin middleware, plus Serve(addr) to start the /metrics listener.
• health — Liveness() (always OK) and Readiness(db) (pings a *sql.DB/*sqlx.DB) Gin handlers.

Usage

import (
    sdk "github.com/lolmourne/go-sdk"
    "github.com/lolmourne/go-sdk/apperr"
    "github.com/lolmourne/go-sdk/health"
    "github.com/lolmourne/go-sdk/httpclient"
    "github.com/lolmourne/go-sdk/logging"
    "github.com/lolmourne/go-sdk/metrics"
)

engine := gin.New()
engine.Use(gin.Recovery())
engine.Use(logging.Middleware(logging.Config{
    ServiceName:  "your-service",
    ModulePrefix: "example.com/your-org/your-service/",
}))
engine.Use(metrics.Instrument())

engine.GET("/health", health.Liveness())
engine.GET("/ready", health.Readiness(db)) // db: *sqlx.DB or *sql.DB

metrics.Serve(cfg.Server.MetricsPort)

// in a resource client:
client := httpclient.New(10 * time.Second)
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
resp, err := client.Do(req) // X-Trace-Id forwarded automatically if present on ctx

sdk.TraceIDFromContext(ctx) / sdk.WithTraceID(ctx, id) are the low-level primitives logging and httpclient share, exported in case a service needs to read/set the correlation ID somewhere outside a Gin handler (e.g. a background job).

Compatibility

Requires Go 1.25 (a transitive dependency of gin/prometheus/client_golang at any currently maintained version now requires it). Services still on an older Go version will need to bump their go directive and Docker build image to adopt this — GOTOOLCHAIN=auto (Go's default) should fetch 1.25 transparently during a networked build even without changing the base image, but bumping the declared go directive and Docker base image explicitly is the safer, more predictable option.

Documentation

Overview

Package sdk holds the primitives shared by the logging, httpclient, metrics and health subpackages: the correlation ID that lets a single request be grepped across every service it touches, before any real distributed tracing backend is in place.

Index

• Constants
• func TraceIDFromContext(ctx context.Context) (string, bool)
• func WithTraceID(ctx context.Context, id string) context.Context

Constants

const TraceIDHeader = "X-Trace-Id"

TraceIDHeader is the header a service reads an inbound correlation ID from, and the header httpclient.New's transport sets on outbound requests so the ID survives service boundaries.

Functions

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) (string, bool)

TraceIDFromContext returns the correlation ID stored on ctx, if any.

func WithTraceID

func WithTraceID(ctx context.Context, id string) context.Context

WithTraceID returns a context carrying the given correlation ID.