ctxtrace

README

CtxTrace

The ctxtrace provides tracing methods that simplify the task of keeping a trace id between HTTP clients and services by handling the conversion between HTTP header and context.Context.

Documentation

Overview

Package ctxtrace provides tracing methods that simplify the task of keeping a trace id between HTTP clients and services by handling the conversion between HTTP header and context.Context.

Index

• Constants
• func Handler(h http.Handler) http.Handler
• func IsTestingTraceID(id string) bool
• func NewTraceID() string
• func TraceIDFromContext(ctx context.Context) string
• func WithTestingTraceID(ctx context.Context, id string) context.Context
• func WithTraceID(ctx context.Context, id string) context.Context
• type Transport
  • func (t Transport) RoundTrip(req *http.Request) (*http.Response, error)

Constants

const (
	// TraceIDHeader holds the header key that should be used when setting a
	// http.Request or http.ResponseWriter. It is used internally so when
	// using working with trace headers outside the library aiming to integrate
	// with it, use this constant.
	TraceIDHeader = "X-Trace-Id"
	// Similar to TraceIDHeader, it holds the context key for logging as a reference
	// so that one does not need to replicate it on the different services using
	// trace in their logging context.
	TraceIDCtx = "trace_id"
)

Functions

func Handler

func Handler(h http.Handler) http.Handler

Handler is a handler that get the trace id from the request, if empty generate a new one, put it in the context and set it on the response.

func IsTestingTraceID

func IsTestingTraceID(id string) bool

IsTestingTraceID returns whether a trace id is specially crafted for testing purposes only.

func NewTraceID

func NewTraceID() string

NewTraceID generates a new uuid v4 trace ID string.

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) string

TraceIDFromContext returns the trace ID for a given context, or an empty string if not set.

func WithTestingTraceID

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

WithTestingTraceID attaches the given ID to the given context set with a fixed testing prefix value indicating that this request should be considered for testing purposes only. If the given ID is "" then an new random ID will be created. This ID will be used by the Transport to provide the X-Trace-Id header for requests containing a context with this value. This method could be used to discard testing requests from the auditing process.

func WithTraceID

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

WithTraceID attaches the given ID to the given context. This ID will be used by the Transport to provide the X-Trace-Id header for requests containing a context with this value. If the given ID is "" then an new random ID will be created.

Types

type Transport

type Transport struct {
	// RoundTripper is an optional http.RoundTripper that will be called after
	// Transport.RoundTrip has enriched the incoming request with the trace id
	// header.
	RoundTripper http.RoundTripper
}

Transport implements http.RoundTripper. It transmits the trace id from the incoming request to the next one. If the incoming request header does not contain a trace id value, it will generate a new one then set it to the following request header. This RoundTipper is ideally placed into a http client that will transmit the internal context's trace id through the X-Trace-Id parameter to an external service:

 client := &Client{
		Params: p,
		client: &http.Client{Transport: ctxtrace.Transport{}},
	}

By default, Transport RoundTripper will be following by the http.DefaultTransport. An optional next http.RoundTripper can be given as Transport attribute so that it can be composed with other http.RoundTripper.

func (Transport) RoundTrip

func (t Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper interface to transfer the trace id, or creating a new one if it is empty, from the incoming request to the following http.RoundTripper. It is followed by http.DefaultTransport or a given RoundTripper when declaring Transport.