propagation

package
v1.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2022 License: Apache-2.0 Imports: 10 Imported by: 29

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

View Source
const (
	TracePropagationGRPCHeader = "x-honeycomb-trace" // difference in case matters here
	TracePropagationHTTPHeader = "X-Honeycomb-Trace"
	TracePropagationVersion    = 1
)
View Source
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)
)
View Source
const (
	TraceparentHeader = "traceparent"
)

Variables

This section is empty.

Functions

func MarshalAmazonTraceContext added in v0.6.0

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 added in v0.8.0

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 added in v0.6.0

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 added in v0.6.0

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 added in v1.7.0

type Config struct {
	PropagateDataset bool
}
var GlobalConfig Config

type PropagationContext added in v0.6.0

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 added in v0.6.0

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 added in v0.8.0

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 added in v0.6.0

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 added in v0.6.0

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 added in v0.6.0

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 added in v1.3.0

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 added in v1.3.0

func (tf TraceFlags) IsSampled() bool

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

func (TraceFlags) MarshalJSON added in v1.3.0

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

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

func (TraceFlags) String added in v1.3.0

func (tf TraceFlags) String() string

String returns the hex string representation form of TraceFlags

func (TraceFlags) WithSampled added in v1.3.0

func (tf TraceFlags) WithSampled(sampled bool) TraceFlags

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

type TraceState added in v1.3.0

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 added in v1.3.0

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 added in v1.3.0

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 added in v1.3.0

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 added in v1.3.0

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 added in v1.3.0

func (ts TraceState) Len() int

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

func (TraceState) MarshalJSON added in v1.3.0

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

MarshalJSON marshals the TraceState into JSON.

func (TraceState) String added in v1.3.0

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL