model

Documentation

Overview

Package model contains the Zipkin V2 model which is used by the Zipkin Go tracer implementation.

Third party instrumentation libraries can use the model and transport packages found in this Zipkin Go library to directly interface with the Zipkin Server or Zipkin Collectors without the need to use the tracer implementation itself.

Index

• Variables
• type Annotation
  • func (a *Annotation) MarshalJSON() ([]byte, error)
  • func (a *Annotation) UnmarshalJSON(b []byte) error
• type BaggageFields
• type Endpoint
  • func (e *Endpoint) Empty() bool
  • func (e Endpoint) MarshalJSON() ([]byte, error)
• type ID
  • func (i ID) MarshalJSON() ([]byte, error)
  • func (i ID) String() string
  • func (i *ID) UnmarshalJSON(b []byte) (err error)
• type Kind
• type SpanContext
• type SpanModel
  • func (s SpanModel) MarshalJSON() ([]byte, error)
  • func (s *SpanModel) UnmarshalJSON(b []byte) error
• type TraceID
  • func TraceIDFromHex(h string) (t TraceID, err error)
  • func (t TraceID) Empty() bool
  • func (t TraceID) MarshalJSON() ([]byte, error)
  • func (t TraceID) String() string
  • func (t *TraceID) UnmarshalJSON(traceID []byte) error

Variables

var (
	ErrValidTraceIDRequired  = errors.New("valid traceId required")
	ErrValidIDRequired       = errors.New("valid span id required")
	ErrValidDurationRequired = errors.New("valid duration required")
)

unmarshal errors

var ErrValidTimestampRequired = errors.New("valid annotation timestamp required")

ErrValidTimestampRequired error

Types

type Annotation

type Annotation struct {
	Timestamp time.Time
	Value     string
}

Annotation associates an event that explains latency with a timestamp.

func (*Annotation) MarshalJSON

func (a *Annotation) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON encoding

func (*Annotation) UnmarshalJSON

func (a *Annotation) UnmarshalJSON(b []byte) error

UnmarshalJSON implements custom JSON decoding

type BaggageFields

type BaggageFields interface {
	// Get returns the values for a field identified by its key.
	Get(key string) []string
	// Add adds the provided values to a header designated by key. If not
	// accepted by the baggage implementation, it will return false.
	Add(key string, value ...string) bool
	// Set sets the provided values to a header designated by key. If not
	// accepted by the baggage implementation, it will return false.
	Set(key string, value ...string) bool
	// Delete removes the field data designated by key. If not accepted by the
	// baggage implementation, it will return false.
	Delete(key string) bool
	// Iterate will iterate over the available fields and for each one it will
	// trigger the callback function.
	Iterate(f func(key string, values []string))
}

BaggageFields holds the interface for consumers needing to interact with the fields in application logic.

type Endpoint

type Endpoint struct {
	ServiceName string
	IPv4        net.IP
	IPv6        net.IP
	Port        uint16
}

Endpoint holds the network context of a node in the service graph.

func (*Endpoint) Empty

func (e *Endpoint) Empty() bool

Empty returns if all Endpoint properties are empty / unspecified.

func (Endpoint) MarshalJSON

func (e Endpoint) MarshalJSON() ([]byte, error)

MarshalJSON exports our Endpoint into the correct format for the Zipkin V2 API.

type ID

type ID uint64

ID type

func (ID) MarshalJSON

func (i ID) MarshalJSON() ([]byte, error)

MarshalJSON serializes an ID type (SpanID, ParentSpanID) to HEX.

func (ID) String

func (i ID) String() string

String outputs the 64-bit ID as hex string.

func (*ID) UnmarshalJSON

func (i *ID) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON deserializes an ID type (SpanID, ParentSpanID) from HEX.

type Kind

type Kind string

Kind clarifies context of timestamp, duration and remoteEndpoint in a span.

const (
	Undetermined Kind = ""
	Client       Kind = "CLIENT"
	Server       Kind = "SERVER"
	Producer     Kind = "PRODUCER"
	Consumer     Kind = "CONSUMER"
)

Available Kind values

type SpanContext

type SpanContext struct {
	TraceID  TraceID       `json:"traceId"`
	ID       ID            `json:"id"`
	ParentID *ID           `json:"parentId,omitempty"`
	Debug    bool          `json:"debug,omitempty"`
	Sampled  *bool         `json:"-"`
	Err      error         `json:"-"`
	Baggage  BaggageFields `json:"-"`
}

SpanContext holds the context of a Span.

type SpanModel

type SpanModel struct {
	SpanContext
	Name           string            `json:"name,omitempty"`
	Kind           Kind              `json:"kind,omitempty"`
	Timestamp      time.Time         `json:"-"`
	Duration       time.Duration     `json:"-"`
	Shared         bool              `json:"shared,omitempty"`
	LocalEndpoint  *Endpoint         `json:"localEndpoint,omitempty"`
	RemoteEndpoint *Endpoint         `json:"remoteEndpoint,omitempty"`
	Annotations    []Annotation      `json:"annotations,omitempty"`
	Tags           map[string]string `json:"tags,omitempty"`
}

SpanModel structure.

If using this library to instrument your application you will not need to directly access or modify this representation. The SpanModel is exported for use cases involving 3rd party Go instrumentation libraries desiring to export data to a Zipkin server using the Zipkin V2 Span model.

func (SpanModel) MarshalJSON

func (s SpanModel) MarshalJSON() ([]byte, error)

MarshalJSON exports our Model into the correct format for the Zipkin V2 API.

func (*SpanModel) UnmarshalJSON

func (s *SpanModel) UnmarshalJSON(b []byte) error

UnmarshalJSON imports our Model from a Zipkin V2 API compatible span representation.

type TraceID

type TraceID struct {
	High uint64
	Low  uint64
}

TraceID is a 128 bit number internally stored as 2x uint64 (high & low). In case of 64 bit traceIDs, the value can be found in Low.

func TraceIDFromHex

func TraceIDFromHex(h string) (t TraceID, err error)

TraceIDFromHex returns the TraceID from a hex string.

func (TraceID) Empty

func (t TraceID) Empty() bool

Empty returns if TraceID has zero value.

func (TraceID) MarshalJSON

func (t TraceID) MarshalJSON() ([]byte, error)

MarshalJSON custom JSON serializer to export the TraceID in the required zero padded hex representation.

func (TraceID) String

func (t TraceID) String() string

String outputs the 128-bit traceID as hex string.

func (*TraceID) UnmarshalJSON

func (t *TraceID) UnmarshalJSON(traceID []byte) error

UnmarshalJSON custom JSON deserializer to retrieve the traceID from the hex encoded representation.