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 (trCtx Context) Parent() Parent
  • func (trCtx Context) State() State
• type Flags
• type Parent
  • func ParseParent(s string) (Parent, error)
  • func (p Parent) String() string
• type State
  • func ParseState(traceStateValue string) (State, error)
  • func (st State) Add(vendor, data string) State
  • func (st State) Fetch(vendor string) (string, bool)
  • func (st State) Index(vendor string) int
  • func (st State) Remove(vendor string) State
  • func (st State) String() string
• type Version
  • func ParseVersion(s string) (Version, error)
  • func (ver Version) String() string

Constants

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

	// W3C trace context header names as defined by https://www.w3.org/TR/trace-context/
	TraceParentHeader = "traceparent"
	TraceStateHeader  = "tracestate"
)

const VendorInstana = "in"

Instana vendor key in the `tracestate` list

Variables

var (
	ErrContextNotFound    = errors.New("no w3c context")
	ErrContextCorrupted   = errors.New("corrupted w3c context")
	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 (trCtx 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 (trCtx Context) State() State

State parses RawState and returns the corresponding list. It silently discards malformed state. To check errors use ParseState().

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 []string

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

func ParseState

func ParseState(traceStateValue string) (State, error)

ParseState parses the value of `tracestate` header. It strips any optional white-space chararacters preceding or following the key=value pairs. Empty list items are omitted.

func (State) Add

func (st State) Add(vendor, data string) State

Put returns a new state prepended with provided vendor-specific data. It removes any existing entries for this vendor and returns the same state if vendor is empty. If the number of entries in a state reaches the MaxStateEntries, rest of the items will be truncated

func (State) Fetch

func (st State) Fetch(vendor string) (string, bool)

Fetch retrieves stored vendor-specific data for given vendor

func (State) Index

func (st State) Index(vendor string) int

Index returns the index of vendor-specific data for given vendor in the state. It returns -1 if the state does not contain data for this vendor.

func (State) Remove

func (st State) Remove(vendor string) State

Remove returns a new state without data for specified vendor. It returns the same state if vendor is empty

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

type Version

type Version uint8

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

const (
	// Invalid W3C Trace Context version
	Version_Invalid Version = iota
	// Supported versions of W3C Trace Context headers
	Version_0
	// The latest supported version of W3C Trace Context
	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