propagation

Documentation

Overview

Package propagation includes types and functions for marshalling and unmarshalling trace context headers between various supported formats and an internal representation. It provides support for traces that cross process boundaries with support for interoperability between various kinds of trace context header formats.

Index

• Constants
• func MarshalAmazonTraceContext(prop *PropagationContext) string
• func MarshalB3TraceContext(ctx context.Context, prop *PropagationContext) (context.Context, map[string]string)
• func MarshalHoneycombTraceContext(prop *PropagationContext) string
• func MarshalW3CTraceContext(ctx context.Context, prop *PropagationContext) (context.Context, map[string]string)
• type PropagationContext
  • func UnmarshalAmazonTraceContext(header string) (*PropagationContext, error)
  • func UnmarshalB3TraceContext(ctx context.Context, headers map[string]string) (context.Context, *PropagationContext, error)
  • func UnmarshalHoneycombTraceContext(header string) (*PropagationContext, error)
  • func UnmarshalW3CTraceContext(ctx context.Context, headers map[string]string) (context.Context, *PropagationContext, error)
  • func (prop PropagationContext) IsValid() bool
• type PropagationError
  • func (p *PropagationError) Error() string

Constants

const (
	TracePropagationGRPCHeader = "x-honeycomb-trace" // difference in case matters here
	TracePropagationHTTPHeader = "X-Honeycomb-Trace"
	TracePropagationVersion    = 1
)

Functions

func MarshalAmazonTraceContext

func MarshalAmazonTraceContext(prop *PropagationContext) string

MarshalAmazonTraceContext uses the information in prop to create a trace context header in the Amazon AWS trace header format. It returns the serialized form of the trace context, ready to be inserted into the headers of an outbound HTTP request.

If prop is nil, the returned value will be an empty string.

func MarshalB3TraceContext

func MarshalB3TraceContext(ctx context.Context, prop *PropagationContext) (context.Context, map[string]string)

MarshalB3TraceContext uses the information in prop to create trace context headers that conform to the B3 Trace Context specification. The header values are set in headers, which is an HTTPSupplier, an interface to which http.Header is an implementation. The headers are also returned as a map[string]string.

Context is passed into this function and returned so that we can maintain the value of the tracestate header. This is required in order to use the Propagator interface exported by the OpenTelemetry Go SDK and avoid writing our own B3 Trace Context parser and serializer.

If prop is empty or nil, the return value will be an empty map.

func MarshalHoneycombTraceContext

func MarshalHoneycombTraceContext(prop *PropagationContext) string

MarshalHoneycombTraceContext uses the information in prop to create a trace context header in the Honeycomb trace header format. It returns the serialized form of the trace context, ready to be inserted into the headers of an outbound HTTP request.

If prop is nil, the returned value will be an empty string.

func MarshalW3CTraceContext

func MarshalW3CTraceContext(ctx context.Context, prop *PropagationContext) (context.Context, map[string]string)

MarshalHoneycombTraceContext uses the information in prop to create trace context headers that conform to the W3C Trace Context specification. The header values are set in headers, which is an HTTPSupplier, an interface to which http.Header is an implementation. The headers are also returned as a map[string]string.

Context is passed into this function and returned so that we can maintain the value of the tracestate header. This is required in order to use the Propagator interface exported by the OpenTelemetry Go SDK and avoid writing our own W3C Trace Context parser and serializer.

If prop is empty or nil, the return value will be an empty map.

Types

type PropagationContext

type PropagationContext struct {
	TraceID      string
	ParentID     string
	Dataset      string
	TraceContext map[string]interface{}
	TraceFlags   trace.TraceFlags
	TraceState   trace.TraceState
}

PropagationContext contains information about a trace that can cross process boundaries. Typically this information is parsed from an incoming trace context header.

func UnmarshalAmazonTraceContext

func UnmarshalAmazonTraceContext(header string) (*PropagationContext, error)

UnmarshalAmazonTraceContext parses the information provided in the headers and creates a PropagationContext instance. The provided headers is expected to contain an X-Amzn-Trace-Id key which will contain the value of the Amazon header.

According to the documentation for load balancer request tracing: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-request-tracing.html An application can add arbitrary fields for its own purposes. The load balancer preserves these fields but does not use them. In our implementation, we stick these fields in the TraceContext field of the PropagationContext. We only support strings, so if the header contains foo=32,baz=true, both 32 and true will be put into the map as strings. Note that this differs from the Honeycomb header, where trace context fields are stored as a base64 encoded JSON object and unmarshaled into ints, bools, etc.

If the header cannot be used to construct a valid PropagationContext, an error will be returned.

func UnmarshalB3TraceContext

func UnmarshalB3TraceContext(ctx context.Context, headers map[string]string) (context.Context, *PropagationContext, error)

UnmarshalB3TraceContext parses the information provided in the appropriate headers and creates a PropagationContext instance. Headers are passed in via an HTTPSupplier, which is an interface that defines Get and Set methods, http.Header is an implementation.

Context is passed into this function and returned so that we can maintain the value of the tracestate header. This is required in order to use the Propagator interface exported by the OpenTelemetry Go SDK and avoid writing our own B3 Trace Context parser and serializer.

If the headers contain neither a trace id or parent id, an error will be returned.

func UnmarshalHoneycombTraceContext

func UnmarshalHoneycombTraceContext(header string) (*PropagationContext, error)

UnmarshalHoneycombTraceContext parses the information provided in header and creates a PropagationContext instance.

If the header cannot be used to construct a PropagationContext with a trace id and parent id, an error will be returned.

func UnmarshalW3CTraceContext

func UnmarshalW3CTraceContext(ctx context.Context, headers map[string]string) (context.Context, *PropagationContext, error)

UnmarshalW3CTraceContext parses the information provided in the appropriate headers and creates a PropagationContext instance. Headers are passed in via an HTTPSupplier, which is an interface that defines Get and Set methods, http.Header is an implementation.

Context is passed into this function and returned so that we can maintain the value of the tracestate header. This is required in order to use the Propagator interface exported by the OpenTelemetry Go SDK and avoid writing our own W3C Trace Context parser and serializer.

If the headers contain neither a trace id or parent id, an error will be returned.

func (PropagationContext) IsValid

func (prop PropagationContext) IsValid() bool

IsValid checks if the PropagationContext is valid. A valid PropagationContext has a valid trace ID and parent ID.

type PropagationError

type PropagationError struct {
	// contains filtered or unexported fields
}

PropagationError wraps any error encountered while parsing or serializing trace propagation contexts.

func (*PropagationError) Error

func (p *PropagationError) Error() string

Error returns a formatted message containing the error.