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
• Variables
• func AssembleTraceForSpan(span basictracer.Span) error
• func CloseTracer(tracer ot.Tracer) error
• func FlushLightStepTracer(lsTracer ot.Tracer) error
• func GetLightStepAccessToken(lsTracer ot.Tracer) (string, error)
• func NewTracer(opts Options) ot.Tracer
• type Endpoint
• type Options
• type Recorder
  • func NewRecorder(opts Options) *Recorder
  • func (r *Recorder) Close() error
  • func (r *Recorder) Disable()
  • func (r *Recorder) Flush()
  • func (r *Recorder) RecordSpan(raw basictracer.RawSpan)
  • func (r *Recorder) ReporterID() uint64
• type SetParentSpanID
  • func (sid SetParentSpanID) Apply(sso *opentracing.StartSpanOptions)
  • func (sid SetParentSpanID) ApplyLS(sso *basictracer.StartSpanOptions)
• type SetSpanID
  • func (sid SetSpanID) Apply(sso *opentracing.StartSpanOptions)
  • func (sid SetSpanID) ApplyLS(sso *basictracer.StartSpanOptions)
• type SetTraceID
  • func (sid SetTraceID) Apply(sso *opentracing.StartSpanOptions)
  • func (sid SetTraceID) ApplyLS(sso *basictracer.StartSpanOptions)

Constants

const (

	// ParentSpanGUIDKey is the tag key used to record the relationship
	// between child and parent spans.
	ParentSpanGUIDKey = "parent_span_guid"

	TracerPlatformValue = "go"

	TracerPlatformKey        = "lightstep.tracer_platform"
	TracerPlatformVersionKey = "lightstep.tracer_platform_version"
	TracerVersionKey         = "lightstep.tracer_version"
	ComponentNameKey         = "lightstep.component_name"
	GUIDKey                  = "lightstep.guid" // <- runtime guid, not span guid
	HostnameKey              = "lightstep.hostname"
	CommandLineKey           = "lightstep.command_line"
)

Variables

var (
	ErrNotLightStepTracer = errors.New("not a LightStep tracer")
	ErrSpanIsTooOld       = errors.New("span is too old to assemble")
)

var (
	BinaryCarrier = basictracer.BinaryCarrier
)

var TracerVersionValue = "0.11.0"

Functions

func AssembleTraceForSpan

func AssembleTraceForSpan(span basictracer.Span) error

AssembleTraceForSpan requests trace assembly given a span of interest to the caller. The span may not have had Finish() called.

func CloseTracer

func CloseTracer(tracer ot.Tracer) error

func FlushLightStepTracer

func FlushLightStepTracer(lsTracer ot.Tracer) error

func GetLightStepAccessToken

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

func NewTracer

func NewTracer(opts Options) ot.Tracer

NewTracer returns a new Tracer that reports spans to a LightStep collector.

Types

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 collection or web API host/port and whether or not to use plaintext communicatation.

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"`

	// 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"`

	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"`
}

Options control how the LightStep Tracer behaves.

type Recorder

type Recorder struct {
	// contains filtered or unexported fields
}

Recorder buffers spans and forwards them to a LightStep collector.

func NewRecorder

func NewRecorder(opts Options) *Recorder

func (*Recorder) Close

func (r *Recorder) Close() error

func (*Recorder) Disable

func (r *Recorder) Disable()

func (*Recorder) Flush

func (r *Recorder) Flush()

func (*Recorder) RecordSpan

func (r *Recorder) RecordSpan(raw basictracer.RawSpan)

func (*Recorder) ReporterID

func (r *Recorder) ReporterID() uint64

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 *opentracing.StartSpanOptions)

func (SetParentSpanID) ApplyLS

func (sid SetParentSpanID) ApplyLS(sso *basictracer.StartSpanOptions)

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 *opentracing.StartSpanOptions)

func (SetSpanID) ApplyLS

func (sid SetSpanID) ApplyLS(sso *basictracer.StartSpanOptions)

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 *opentracing.StartSpanOptions)

just kidding these aren't real OT start span options

func (SetTraceID) ApplyLS

func (sid SetTraceID) ApplyLS(sso *basictracer.StartSpanOptions)