instracer

Documentation

Overview

Package instracer contains helpers for opencesus tracer.

Example:

import (
	"github.com/insolar/insolar/configuration"
	"github.com/insolar/insolar/log"
)

// on client side
//
entryvalue := "entryvalue"
ctx := context.Background()
jaegerflush = instracer.ShouldRegisterJaeger(ctx, "insolard", "localhost:6831", "")
ctx = instracer.SetBaggage(ctx, instracer.Entry{Key: "someentry", Value: entryvalue})
defer jaegerflush() // wait all trace data to send on jaeger server

// serialize clientctx
spanbindata := instracer.MustSerialize(ctx)

// send spanbindata on wire with request
// someSendMethod(ctxdata, request)

// on server side
//
// deserialized from wire
// spanbindata := someRecieverMethod()
ctx := context.Background()
instracer.MustDeserialize(spanbindata)

ctx = instracer.WithParentSpan(ctx, parentspan)
donefn := instracer.ShouldRegisterJaeger(ctx, "server", "localhost:6831", "")
defer donefn()

servctx, servspan := instracer.StartSpan(ctx, "server")
defer servspan.End()
// call subrequests with servctx, and use instracer.StartSpan

Hints:

Use environment variables for log level setup:

INSOLAR_TRACER_JAEGER_AGENTENDPOINT="localhost:6831"

How to run Jaeger locally:

docker run --rm --name jaeger \
	-p 6831:6831/udp \
	-p 16686:16686 \
	jaegertracing/all-in-one:1.7 --log-level=debug

Index

• Variables
• func MustSerialize(ctx context.Context) []byte
• func RegisterJaeger(servicename string, nodeRef string, agentendpoint string, ...) (*jaeger.Exporter, error)
• func Serialize(ctx context.Context) ([]byte, error)
• func SetBaggage(ctx context.Context, e ...Entry) context.Context
• func ShouldRegisterJaeger(ctx context.Context, servicename string, nodeRef string, agentendpoint string, ...) (flusher func())
• func StartSpan(ctx context.Context, name string) (context.Context, *trace.Span)
• func WithParentSpan(ctx context.Context, pspan TraceSpan) context.Context
• type Entry
  • func GetBaggage(ctx context.Context) []Entry
• type TraceSpan
  • func Deserialize(b []byte) (TraceSpan, error)
  • func MustDeserialize(b []byte) TraceSpan
  • func (ts TraceSpan) Serialize() (b []byte, err error)

Variables

var ErrJagerConfigEmpty = errors.New("can't create jaeger exporter, config not provided")

ErrJagerConfigEmpty is returned if jaeger configuration has empty endpoint values.

Functions

func MustSerialize

func MustSerialize(ctx context.Context) []byte

MustSerialize encode baggage entries from bytes, panics on error.

func RegisterJaeger

func RegisterJaeger(
	servicename string,
	nodeRef string,
	agentendpoint string,
	collectorendpoint string,
	probabilityRate float64,
) (*jaeger.Exporter, error)

RegisterJaeger creates jaeger exporter and registers it in opencensus trace lib.

func Serialize

func Serialize(ctx context.Context) ([]byte, error)

Serialize encode baggage entries to bytes.

func SetBaggage

func SetBaggage(ctx context.Context, e ...Entry) context.Context

SetBaggage stores provided entries as context baggage and returns new context.

Baggage is set of entries that should be attached to all new spans.

func ShouldRegisterJaeger

func ShouldRegisterJaeger(
	ctx context.Context,
	servicename string,
	nodeRef string,
	agentendpoint string,
	collectorendpoint string,
	probabilityRate float64,
) (flusher func())

ShouldRegisterJaeger calls RegisterJaeger and returns flush function.

func StartSpan

func StartSpan(ctx context.Context, name string) (context.Context, *trace.Span)

StartSpan starts span with stored baggage and with parent span if find in context.

func WithParentSpan

func WithParentSpan(ctx context.Context, pspan TraceSpan) context.Context

WithParentSpan returns new context with provided parent span.

Types

type Entry

type Entry struct {
	// Key is an opaque string up to 256 characters printable. It MUST begin with a lowercase letter,
	// and can only contain lowercase letters a-z, digits 0-9, underscores _, dashes -, asterisks *, and
	// forward slashes /.
	Key string
	// Value is an opaque string up to 256 characters printable ASCII RFC0020 characters (i.e., the
	// range 0x20 to 0x7E) except comma , and =.
	Value string
}

Entry represents one key-value pair in a list of key-value pair of Tracestate.

func GetBaggage

func GetBaggage(ctx context.Context) []Entry

GetBaggage returns trace entries have set as trace baggage.

type TraceSpan

type TraceSpan struct {
	TraceID []byte
	SpanID  []byte
	Entries []Entry
}

TraceSpan represents all span context required for propagating between services.

func Deserialize

func Deserialize(b []byte) (TraceSpan, error)

Deserialize decode baggage entries from bytes.

func MustDeserialize

func MustDeserialize(b []byte) TraceSpan

MustDeserialize decode baggage entries from bytes, panics on error.

func (TraceSpan) Serialize

func (ts TraceSpan) Serialize() (b []byte, err error)

Serialize method encodes TraceSpan to bytes.