correlation

Documentation

Overview

Package correlation owns the project correlation model — the single concern no upstream library can own.

On every inbound request the Middleware reads (or issues) a correlation_id, adopts the OpenTelemetry trace_id/span_id from azugo.io/opentelemetry, binds all three to *azugo.Context, and ensures they appear on every log line. The same ids are then propagated on outbound HTTP (package httpclient), stamped onto every broker event (package broker), and copied into the audit event envelope by the audit emitter libraries — so one incident can be reconstructed end-to-end across logs, traces, and all three audit regimes by a single id.

Index

• Constants
• func ID(ctx *azugo.Context) string
• func Middleware() azugo.RequestHandlerFunc
• func ValidID(s string) bool
• type IDs
  • func FromContext(ctx *azugo.Context) IDs

Constants

const (
	LogKeyCorrelationID = "correlation_id"
	LogKeyTraceID       = "trace_id"
	LogKeySpanID        = "span_id"
)

Log field keys. These are the canonical names that appear in every log line and in the audit event envelope.

const (
	// HeaderCorrelationID is the inbound/outbound correlation id header. It is
	// defined by the dependency-free propagation leaf so the request middleware
	// and every outbound client (including the on-behalf/background client that
	// cannot import this package) share one name.
	HeaderCorrelationID = propagation.HeaderCorrelationID
)

Header names carrying correlation across HTTP hops. The W3C `traceparent` header is injected/extracted by azugo.io/opentelemetry; correlation_id is ours.

const MaxIDLength = 128

MaxIDLength bounds an accepted inbound correlation id. Longer (or otherwise invalid) inbound values are ignored and a fresh id is used instead — the correlation id rides every log line, audit envelope, and outbound call, so it must never be an attacker-controlled free-text channel.

Functions

func ID

func ID(ctx *azugo.Context) string

ID returns the correlation id bound to the request, or "" if Middleware has not run.

func Middleware

func Middleware() azugo.RequestHandlerFunc

Middleware resolves the correlation triple for each inbound request and binds it to the context and the request logger.

It must run after the azugo.io/opentelemetry middleware (so the active span is available) — platform.Setup guarantees this ordering by enabling tracing before installing this middleware.

func ValidID

func ValidID(s string) bool

ValidID reports whether s is acceptable as an inbound correlation id: 1 to MaxIDLength characters from [A-Za-z0-9._-]. Anything else (empty, oversized, exotic characters, header-injection attempts) is rejected and replaced by a locally minted id.

Types

type IDs

type IDs struct {
	CorrelationID string
	TraceID       string
	SpanID        string
}

IDs is the correlation triple carried on a request: the project correlation_id plus the OpenTelemetry trace_id/span_id (empty when tracing is inactive).

func FromContext

func FromContext(ctx *azugo.Context) IDs

FromContext returns the correlation triple bound to the request. The correlation_id is always present once Middleware has run; trace_id/span_id are present only when tracing is active for the request.