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 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 (
	// 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. 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

Add 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 (
	// 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