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 Config
• 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
• type TraceFlags
  • func (tf TraceFlags) IsSampled() bool
  • func (tf TraceFlags) MarshalJSON() ([]byte, error)
  • func (tf TraceFlags) String() string
  • func (tf TraceFlags) WithSampled(sampled bool) TraceFlags
• type TraceState
  • func ParseTraceState(tracestate string) (TraceState, error)
  • func (ts TraceState) Delete(key string) TraceState
  • func (ts TraceState) Get(key string) string
  • func (ts TraceState) Insert(key, value string) (TraceState, error)
  • func (ts TraceState) Len() int
  • func (ts TraceState) MarshalJSON() ([]byte, error)
  • func (ts TraceState) String() string

Constants

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

const (
	// FlagsSampled is a bitmask with the sampled bit set. A SpanContext
	// with the sampling bit set means the span is sampled.
	FlagsSampled = TraceFlags(0x01)
)

const (
	TraceparentHeader = "traceparent"
)

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 Config

type Config struct {
	PropagateDataset bool
}

var GlobalConfig Config

type PropagationContext

type PropagationContext struct {
	TraceID      string
	ParentID     string
	Dataset      string
	TraceContext map[string]interface{}
	TraceFlags   TraceFlags
	TraceState   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.

type TraceFlags

type TraceFlags byte //nolint:revive // revive complains about stutter of `trace.TraceFlags`.

TraceFlags contains flags that can be set on a SpanContext

func (TraceFlags) IsSampled

func (tf TraceFlags) IsSampled() bool

IsSampled returns if the sampling bit is set in the TraceFlags.

func (TraceFlags) MarshalJSON

func (tf TraceFlags) MarshalJSON() ([]byte, error)

MarshalJSON implements a custom marshal function to encode TraceFlags as a hex string.

func (TraceFlags) String

func (tf TraceFlags) String() string

String returns the hex string representation form of TraceFlags

func (TraceFlags) WithSampled

func (tf TraceFlags) WithSampled(sampled bool) TraceFlags

WithSampled sets the sampling bit in a new copy of the TraceFlags.

type TraceState

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

TraceState provides additional vendor-specific trace identification information across different distributed tracing systems. It represents an immutable list consisting of key/value pairs, each pair is referred to as a list-member.

TraceState conforms to the W3C Trace Context specification (https://www.w3.org/TR/trace-context-1). All operations that create or copy a TraceState do so by validating all input and will only produce TraceState that conform to the specification. Specifically, this means that all list-member's key/value pairs are valid, no duplicate list-members exist, and the maximum number of list-members (32) is not exceeded.

func ParseTraceState

func ParseTraceState(tracestate string) (TraceState, error)

ParseTraceState attempts to decode a TraceState from the passed string. It returns an error if the input is invalid according to the W3C Trace Context specification.

func (TraceState) Delete

func (ts TraceState) Delete(key string) TraceState

Delete returns a copy of the TraceState with the list-member identified by key removed.

func (TraceState) Get

func (ts TraceState) Get(key string) string

Get returns the value paired with key from the corresponding TraceState list-member if it exists, otherwise an empty string is returned.

func (TraceState) Insert

func (ts TraceState) Insert(key, value string) (TraceState, error)

Insert adds a new list-member defined by the key/value pair to the TraceState. If a list-member already exists for the given key, that list-member's value is updated. The new or updated list-member is always moved to the beginning of the TraceState as specified by the W3C Trace Context specification.

If key or value are invalid according to the W3C Trace Context specification an error is returned with the original TraceState.

If adding a new list-member means the TraceState would have more members than is allowed an error is returned instead with the original TraceState.

func (TraceState) Len

func (ts TraceState) Len() int

Len returns the number of list-members in the TraceState.

func (TraceState) MarshalJSON

func (ts TraceState) MarshalJSON() ([]byte, error)

MarshalJSON marshals the TraceState into JSON.

func (TraceState) String

func (ts TraceState) String() string

String encodes the TraceState into a string compliant with the W3C Trace Context specification. The returned string will be invalid if the TraceState contains any invalid members.