Documentation
¶
Overview ¶
Package correlation propagates a per-request correlation ID through http.Request contexts, gRPC metadata and log entries.
An ID is taken from the incoming X-Correlation-ID or X-Request-ID header (gRPC: x-correlation-id / x-request-id metadata), truncated to IDSize characters, or generated randomly when absent. The ID is stored in the context (see ID, Value), attached to xlog context fields as "ctx", and echoed back in the X-Correlation-ID response header.
h := correlation.NewHandler(next) // HTTP middleware srv := grpc.NewServer(grpc.UnaryInterceptor(correlation.NewAuthUnaryInterceptor())) id := correlation.ID(ctx) // read it later ctx = correlation.WithMetaFromContext(ctx) // outgoing gRPC call
Both gRPC interceptors also recover panics from downstream handlers, log them with a stack trace and return a generic "unhandled exception" error.
Index ¶
- Constants
- Variables
- func ID(ctx context.Context) string
- func NewAuthUnaryInterceptor() grpc.UnaryServerInterceptor
- func NewFromContext(ctx context.Context) context.Context
- func NewHandler(delegate http.Handler) http.Handler
- func NewStreamServerInterceptor() grpc.StreamServerInterceptor
- func WithID(ctx context.Context) context.Context
- func WithMetaFromContext(ctx context.Context) context.Context
- func WithMetaFromRequest(req *http.Request) context.Context
- type Correlator
- type RequestContext
Constants ¶
const IDSize = 12
IDSize is the length in characters of generated correlation IDs; incoming IDs longer than this are truncated.
Variables ¶
var CorrelationIDgRPCHeaderName = "x-correlation-id"
CorrelationIDgRPCHeaderName is the gRPC metadata key used to carry the correlation ID on outgoing calls and read it on incoming ones. It is a process-global that may be changed at startup, before any traffic.
Functions ¶
func NewAuthUnaryInterceptor ¶
func NewAuthUnaryInterceptor() grpc.UnaryServerInterceptor
NewAuthUnaryInterceptor returns a grpc.UnaryServerInterceptor that adds the correlation ID (from incoming metadata or newly generated) to the context and xlog fields, and recovers panics from the handler, logging them and returning an "unhandled exception" error.
func NewFromContext ¶
NewFromContext returns a fresh context.Background (detached from ctx's cancellation and deadline) that carries ctx's correlation ID, or a new one, both as a context value and as outgoing gRPC metadata. Use it for background work that should outlive the request.
func NewHandler ¶
NewHandler returns middleware that reads the correlation ID from the X-Correlation-ID or X-Request-ID request header (or generates one), stores it in the request context, adds it to the xlog context as "ctx" and sets the X-Correlation-ID response header before calling delegate. An ID already present in the context is reused.
func NewStreamServerInterceptor ¶ added in v0.33.319
func NewStreamServerInterceptor() grpc.StreamServerInterceptor
NewStreamServerInterceptor returns the streaming counterpart of NewAuthUnaryInterceptor; the stream is wrapped with streamctx.WithContext so handlers see the enriched context.
func WithID ¶
WithID returns a context carrying a newly generated correlation ID (also added to the xlog fields). If ctx already has one, ctx is returned as is.
func WithMetaFromContext ¶
WithMetaFromContext ensures the outgoing gRPC metadata of ctx carries the correlation ID under CorrelationIDgRPCHeaderName, generating and storing a new ID in the context when none exists. Use it before making a gRPC client call.
Types ¶
type Correlator ¶
type Correlator interface {
// CorrelationID returns the correlation ID, or "" when unknown.
CorrelationID() string
}
Correlator is implemented by values (such as httperror.Error) that carry a correlation ID.
type RequestContext ¶
type RequestContext struct {
// ID is the correlation ID.
ID string
}
RequestContext is the value stored in the context by this package; it holds the request ID, aka Request-ID or Correlation-ID (for cross system request correlation). Retrieve it with Value or ID.
func Value ¶
func Value(ctx context.Context) *RequestContext
Value returns the RequestContext stored in ctx, or nil if none.
Source Files