w3ctrace

Documentation

Index

• Constants
• Variables
• func Inject(trCtx Context, headers http.Header)
• func TracingHandlerFunc(handler http.HandlerFunc) http.HandlerFunc
• type Context
  • func Extract(headers http.Header) (Context, error)
  • func New(parent Parent) Context
  • func (c Context) IsZero() bool
  • func (c Context) Parent() Parent
  • func (c Context) State() State
• type Flags
• type Parent
  • func ParseParent(s string) (Parent, error)
  • func (p Parent) String() string
• type State
  • func FormStateWithInstanaTraceStateValue(st State, instanaTraceStateValue string) State
  • func NewState(listMembers []string, instanaTraceStateValue string) State
  • func ParseState(traceStateValue string) State
  • func (st State) FetchInstanaTraceStateValue() (string, bool)
  • func (st State) String() string
• type Version
  • func ParseVersion(s string) (Version, error)
  • func (ver Version) String() string

Constants

const (
	// MaxStateEntries is the maximum number of items in `tracestate` as defined by
	// https://www.w3.org/TR/trace-context/#tracestate-header-field-values
	MaxStateEntries = 32

	// TraceParentHeader is the W3C trace parent header name as defined by https://www.w3.org/TR/trace-context/
	TraceParentHeader = "traceparent"
	// TraceStateHeader is the W3C trace state header name as defined by https://www.w3.org/TR/trace-context/
	TraceStateHeader = "tracestate"
)

const VendorInstana = "in"

VendorInstana is the Instana vendor key in the `tracestate` list

Variables

var (
	// ErrContextNotFound is an error retuned by w3ctrace.Extract() if provided HTTP headers does not contain W3C trace context
	ErrContextNotFound = errors.New("no w3c context")
	// ErrContextCorrupted is an error retuned by w3ctrace.Extract() if provided HTTP headers contain W3C trace context in unexpected format
	ErrContextCorrupted = errors.New("corrupted w3c context")
	// ErrUnsupportedVersion is an error retuned by w3ctrace.Extract() if the version of provided W3C trace context is not supported
	ErrUnsupportedVersion = errors.New("unsupported w3c context version")
)

Functions

func Inject

func Inject(trCtx Context, headers http.Header)

Inject adds the w3c trace context headers, overriding any previously set values

func TracingHandlerFunc

func TracingHandlerFunc(handler http.HandlerFunc) http.HandlerFunc

TracingHandlerFunc is an HTTP middleware that forwards the W3C context found in request with the response

Types

type Context

type Context struct {
	RawParent string
	RawState  string
}

Context represents the W3C trace context

func Extract

func Extract(headers http.Header) (Context, error)

Extract extracts the W3C trace context from HTTP headers. Returns ErrContextNotFound if provided value doesn't contain traceparent header.

func New

func New(parent Parent) Context

New initializes a new W3C trace context from given parent

func (Context) IsZero

func (c Context) IsZero() bool

IsZero returns whether a context is a zero value

func (Context) Parent

func (c Context) Parent() Parent

Parent parses RawParent and returns the corresponding list. It silently discards malformed value. To check errors use ParseParent().

func (Context) State

func (c Context) State() State

State parses RawState and returns the corresponding list.

type Flags

type Flags struct {
	Sampled bool
}

Flags contains the trace flags as defined by https://www.w3.org/TR/trace-context/#trace-flags

type Parent

type Parent struct {
	Version  Version
	TraceID  string
	ParentID string
	Flags    Flags
}

Parent represents trace parent extracted from `traceparent` header

func ParseParent

func ParseParent(s string) (Parent, error)

ParseParent parses the value of `traceparent` header according to the version defined in the first field

func (Parent) String

func (p Parent) String() string

String returns string representation of a trace parent. The returned value is compatible with the `traceparent` header format

type State

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

State is list of key=value pairs representing vendor-specific data in the trace context

func FormStateWithInstanaTraceStateValue

func FormStateWithInstanaTraceStateValue(st State, instanaTraceStateValue string) State

FormStateWithInstanaTraceStateValue returns a new state prepended with the provided Instana value. If the original state had an Instana list member pair, it is discarded/overwritten.

func NewState

func NewState(listMembers []string, instanaTraceStateValue string) State

NewState creates a new State with the given values

func ParseState

func ParseState(traceStateValue string) State

ParseState parses the value of `tracestate` header. Empty list items are omitted.

func (State) FetchInstanaTraceStateValue

func (st State) FetchInstanaTraceStateValue() (string, bool)

FetchInstanaTraceStateValue retrieves the value of the Instana tracestate list member, if any.

func (State) String

func (st State) String() string

String returns string representation of a trace state. The returned value is compatible with the `tracestate` header format. If the state has an Instana-specific list member, that one is always rendered first. This is optimized for the use case of injecting the string representation of the tracestate header into downstream requests.

type Version

type Version uint8

Version represents the W3C trace context version. It defines the format of `traceparent` header

const (
	// Version_Invalid represend an invalid  W3C Trace Context version
	Version_Invalid Version = iota
	// Version_0 represent the W3C Trace Context version 00
	Version_0
	// Version_Max is the latest version of W3C Trace Context supported by this package
	Version_Max = Version_0
)

func ParseVersion

func ParseVersion(s string) (Version, error)

ParseVersion parses the version part of a `traceparent` header value. It returns ErrContextCorrupted if the version is malformed

func (Version) String

func (ver Version) String() string

String returns string representation of a trace parent version. The returned value is compatible with the `traceparent` header format. The caller should take care of handling the Version_Unknown, otherwise this method will return "ff" which is considered invalid