lightstep

README

lightstep-tracer-go

The LightStep distributed tracing library for Go.

Installation

$ go get 'github.com/lightstep/lightstep-tracer-go'

Getting started

To initialize the LightStep library in particular, either retain a reference to the LightStep opentracing.Tracer implementation and/or set the global Tracer like so:

import (
    "github.com/opentracing/opentracing-go"
    "github.com/lightstep/lightstep-tracer-go"
)

func main() {
    // Initialize the LightStep Tracer; see lightstep.Options for tuning, etc.
    lightstepTracer := lightstep.NewTracer(lightstep.Options{
        AccessToken: "YourAccessToken",
    })

    // Optionally set the opentracing global Tracer to the above
    opentracing.SetGlobalTracer(lightstepTracer)

    ...
}

For instrumentation documentation, see the opentracing-go godocs.

Documentation

Index

• Constants
• func CloseTracer(tracer ot.Tracer) error
• func FlushLightStepTracer(lsTracer ot.Tracer) error
• func GetLightStepAccessToken(lsTracer ot.Tracer) (string, error)
• type Connection
• type ConnectorFactory
• type Endpoint
  • func (e Endpoint) HostPort() string
  • func (e Endpoint) URL() string
• type Options
  • func (opts *Options) Initialize() error
• type RawSpan
• type SetParentSpanID
  • func (sid SetParentSpanID) Apply(sso *ot.StartSpanOptions)
• type SetSpanID
  • func (sid SetSpanID) Apply(sso *ot.StartSpanOptions)
• type SetTraceID
  • func (sid SetTraceID) Apply(sso *ot.StartSpanOptions)
• type SpanContext
  • func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)
  • func (c SpanContext) WithBaggageItem(key, val string) SpanContext
• type SpanRecorder
• type Tracer
  • func NewTracer(opts Options) Tracer

Constants

const (
	DefaultCollectorPath       = "/_rpc/v1/reports/binary"
	DefaultPlainPort           = 80
	DefaultSecurePort          = 443
	DefaultThriftCollectorHost = "collector.lightstep.com"
	DefaultGRPCCollectorHost   = "collector-grpc.lightstep.com"

	DefaultMaxReportingPeriod = 2500 * time.Millisecond
	DefaultMinReportingPeriod = 500 * time.Millisecond
	DefaultMaxSpans           = 1000
	DefaultReportTimeout      = 30 * time.Second
	DefaultReconnectPeriod    = 5 * time.Minute

	DefaultMaxLogKeyLen   = 256
	DefaultMaxLogValueLen = 1024
	DefaultMaxLogsPerSpan = 500

	DefaultGRPCMaxCallSendMsgSizeBytes = math.MaxInt32
)

Default Option values.

const (
	ParentSpanGUIDKey = "parent_span_guid" // ParentSpanGUIDKey is the tag key used to record the relationship between child and parent spans.
	ComponentNameKey  = "lightstep.component_name"
	GUIDKey           = "lightstep.guid" // <- runtime guid, not span guid
	HostnameKey       = "lightstep.hostname"
	CommandLineKey    = "lightstep.command_line"

	TracerPlatformKey        = "lightstep.tracer_platform"
	TracerPlatformValue      = "go"
	TracerPlatformVersionKey = "lightstep.tracer_platform_version"
	TracerVersionKey         = "lightstep.tracer_version" // Note: TracerVersionValue is generated from ./VERSION
)

Tag and Tracer Attribute keys.

const BinaryCarrier = "lightstep_binary_carrier"

BinaryCarrier is used as the format parameter in inject/extract for lighstep binary propogation.

const TracerVersionValue = "0.14.0"

Functions

func CloseTracer

func CloseTracer(tracer ot.Tracer) error

CloseTracer synchronously flushes the tracer, then terminates it.

func FlushLightStepTracer

func FlushLightStepTracer(lsTracer ot.Tracer) error

FlushLightStepTracer forces a synchronous Flush.

func GetLightStepAccessToken

func GetLightStepAccessToken(lsTracer ot.Tracer) (string, error)

GetLightStepAccessToken returns the currently configured AccessToken.

Types

type Connection

type Connection interface {
	io.Closer
}

Connection describes a closable connection. Exposed for testing.

type ConnectorFactory

type ConnectorFactory func() (interface{}, Connection, error)

ConnectorFactory is for testing purposes.

type Endpoint

type Endpoint struct {
	Host      string `yaml:"host" usage:"host on which the endpoint is running"`
	Port      int    `yaml:"port" usage:"port on which the endpoint is listening"`
	Plaintext bool   `yaml:"plaintext" usage:"whether or not to encrypt data send to the endpoint"`
}

Endpoint describes a collector or web API host/port and whether or not to use plaintext communication.

func (Endpoint) HostPort

func (e Endpoint) HostPort() string

HostPort returns an address suitable for dialing grpc connections

func (Endpoint) URL

func (e Endpoint) URL() string

URL returns an address suitable for dialing thrift connections

type Options

type Options struct {
	// AccessToken is the unique API key for your LightStep project.  It is
	// available on your account page at https://app.lightstep.com/account
	AccessToken string `yaml:"access_token" usage:"access token for reporting to LightStep"`

	// Collector is the host, port, and plaintext option to use
	// for the collector.
	Collector Endpoint `yaml:"collector"`

	// Tags are arbitrary key-value pairs that apply to all spans generated by
	// this Tracer.
	Tags ot.Tags

	// LightStep is the host, port, and plaintext option to use
	// for the LightStep web API.
	LightStepAPI Endpoint `yaml:"lightstep_api"`

	// MaxBufferedSpans is the maximum number of spans that will be buffered
	// before sending them to a collector.
	MaxBufferedSpans int `yaml:"max_buffered_spans"`

	// MaxLogKeyLen is the maximum allowable size (in characters) of an
	// OpenTracing logging key. Longer keys are truncated.
	MaxLogKeyLen int `yaml:"max_log_key_len"`

	// MaxLogValueLen is the maximum allowable size (in characters) of an
	// OpenTracing logging value. Longer values are truncated. Only applies to
	// variable-length value types (strings, interface{}, etc).
	MaxLogValueLen int `yaml:"max_log_value_len"`

	// MaxLogsPerSpan limits the number of logs in a single span.
	MaxLogsPerSpan int `yaml:"max_logs_per_span"`

	// GRPCMaxCallSendMsgSizeBytes limits the size in bytes of grpc messages
	// sent by a client.
	GRPCMaxCallSendMsgSizeBytes int `yaml:"grpc_max_call_send_msg_size_bytes"`

	// ReportingPeriod is the maximum duration of time between sending spans
	// to a collector.  If zero, the default will be used.
	ReportingPeriod time.Duration `yaml:"reporting_period"`

	// MinReportingPeriod is the minimum duration of time between sending spans
	// to a collector.  If zero, the default will be used. It is strongly
	// recommended to use the default.
	MinReportingPeriod time.Duration `yaml:"min_reporting_period"`

	ReportTimeout time.Duration `yaml:"report_timeout"`

	// DropSpanLogs turns log events on all Spans into no-ops.
	DropSpanLogs bool `yaml:"drop_span_logs"`

	// Set Verbose to true to enable more text logging.
	Verbose bool `yaml:"verbose"`

	// DEPRECATED: set `UseThrift` to true if you do not want gRPC
	UseGRPC bool `yaml:"usegrpc"`

	// Switch to
	UseThrift bool `yaml:"use_thrift"`

	ReconnectPeriod time.Duration `yaml:"reconnect_period"`

	// a hook for recieving finished span events
	Recorder SpanRecorder `yaml:"-" json:"-"`

	// For testing purposes only
	ConnFactory ConnectorFactory `yaml:"-" json:"-"`
}

Options control how the LightStep Tracer behaves.

func (*Options) Initialize

func (opts *Options) Initialize() error

Initialize validates options, and sets default values for unset options. This is called automatically when creating a new Tracer.

type RawSpan

type RawSpan struct {
	// Those recording the RawSpan should also record the contents of its
	// SpanContext.
	Context SpanContext

	// The SpanID of this SpanContext's first intra-trace reference (i.e.,
	// "parent"), or 0 if there is no parent.
	ParentSpanID uint64

	// The name of the "operation" this span is an instance of. (Called a "span
	// name" in some implementations)
	Operation string

	// We store <start, duration> rather than <start, end> so that only
	// one of the timestamps has global clock uncertainty issues.
	Start    time.Time
	Duration time.Duration

	// Essentially an extension mechanism. Can be used for many purposes,
	// not to be enumerated here.
	Tags opentracing.Tags

	// The span's "microlog".
	Logs []opentracing.LogRecord
}

RawSpan encapsulates all state associated with a (finished) LightStep Span.

type SetParentSpanID

type SetParentSpanID uint64

SetParentSpanID is an opentracing.StartSpanOption that sets an explicit parent SpanID. It must be used in conjunction with SetTraceID or the result is undefined. If the value is zero, it will be disregarded. If a ChildOf or FollowsFrom span relation is also set in the start options, it will override this value.

func (SetParentSpanID) Apply

func (sid SetParentSpanID) Apply(sso *ot.StartSpanOptions)

Apply satisfies the StartSpanOption interface.

type SetSpanID

type SetSpanID uint64

SetSpanID is a opentracing.StartSpanOption that sets an explicit SpanID. It must be used in conjunction with SetTraceID or the result is undefined.

func (SetSpanID) Apply

func (sid SetSpanID) Apply(sso *ot.StartSpanOptions)

Apply satisfies the StartSpanOption interface.

type SetTraceID

type SetTraceID uint64

SetTraceID is an opentracing.StartSpanOption that sets an explicit TraceID. It must be used in order to set an explicit SpanID or ParentSpanID. If a ChildOf or FollowsFrom span relation is also set in the start options, it will override this value.

func (SetTraceID) Apply

func (sid SetTraceID) Apply(sso *ot.StartSpanOptions)

Apply satisfies the StartSpanOption interface.

type SpanContext

type SpanContext struct {
	// A probabilistically unique identifier for a [multi-span] trace.
	TraceID uint64

	// A probabilistically unique identifier for a span.
	SpanID uint64

	// The span's associated baggage.
	Baggage map[string]string // initialized on first use
}

SpanContext holds lightstep-specific Span metadata.

func (SpanContext) ForeachBaggageItem

func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem belongs to the opentracing.SpanContext interface

func (SpanContext) WithBaggageItem

func (c SpanContext) WithBaggageItem(key, val string) SpanContext

WithBaggageItem returns an entirely new basictracer SpanContext with the given key:value baggage pair set.

type SpanRecorder

type SpanRecorder interface {
	RecordSpan(RawSpan)
}

A SpanRecorder handles all of the `RawSpan` data generated via an associated `Tracer` instance.

type Tracer

type Tracer interface {
	ot.Tracer

	// Close flushes and then terminates the LightStep collector
	Close() error
	// Flush sends all spans currently in the buffer to the LighStep collector
	Flush()
	// Options gets the Options used in New() or NewWithOptions().
	Options() Options
	// Disable prevents the tracer from recording spans or flushing
	Disable()
}

Tracer extends the opentracing.Tracer interface with methods to probe implementation state, for use by basictracer consumers.

func NewTracer

func NewTracer(opts Options) Tracer

NewTracer creates and starts a new Lightstep Tracer.