The LightStep distributed tracing library for Go
Go Python Makefile C
Permalink
Failed to load latest commit information.
cmd Events (#119) Oct 26, 2017
collectorpb Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
examples Exercise more of the logging API Oct 9, 2016
lightstep-tracer-common @ 3943f3f Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
lightstep_thrift Refactor and Ginkgo Tests (#88) Jul 5, 2017
lightstepfakes Refactor and Ginkgo Tests (#88) Jul 5, 2017
lightsteppb Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
thrift_0_9_2 Refactor and Ginkgo Tests (#88) Jul 5, 2017
.gitignore Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
.gitmodules Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
CHANGELOG.md Add changelog for v0.15.0 (#132) Nov 16, 2017
Gopkg.lock Add Gopkg setup (#139) Dec 9, 2017
Gopkg.toml Add Gopkg setup (#139) Dec 9, 2017
LICENSE Initial commit Mar 4, 2016
Makefile Makefile changes to fix building/testing (#143) Feb 13, 2018
README.md Update README to reflect alpha http support. (#142) Jan 25, 2018
VERSION Update version.go and VERSION to 0.15.3 (#151) Jul 16, 2018
bench_test.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
benchmark_test.go Refactor and Ginkgo Tests (#88) Jul 5, 2017
collector_client.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
collector_client_grpc.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
collector_client_http.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
collector_client_thrift.go Code organization (#126) Oct 30, 2017
event_handlers.go Events (#119) Oct 26, 2017
event_handlers_test.go Events (#119) Oct 26, 2017
events.go Add EventTracerDisabled (#127) Oct 30, 2017
lightstep_tracer_go_suite_test.go Refactor and Ginkgo Tests (#88) Jul 5, 2017
options.go Code organization (#126) Oct 30, 2017
propagation_binary.go support io.Writer/io.Reader for Inject/Extract (#148) Jul 16, 2018
propagation_text.go Small clean up and typo fixes. (#110) Sep 26, 2017
proto_converter.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
proto_logencoder.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
raw_span.go Refactor and Ginkgo Tests (#88) Jul 5, 2017
report_buffer.go Buffer recovery on flushing error (#100) Aug 17, 2017
span.go Refactor and Ginkgo Tests (#88) Jul 5, 2017
tag_version.sh Add a newline in tag_version.sh for gofmt (#94) Jul 14, 2017
test_utils_test.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
thrift_logencoder.go Refactor and Ginkgo Tests (#88) Jul 5, 2017
tracer.go support io.Writer/io.Reader for Inject/Extract (#148) Jul 16, 2018
tracer_0_14._test.go Add GetLightStepReporterID helper (#141) Jan 17, 2018
tracer_0_14.go Events (#119) Oct 26, 2017
tracer_helpers.go Add GetLightStepReporterID helper (#141) Jan 17, 2018
tracer_test.go Add GetLightStepReporterID helper (#141) Jan 17, 2018
tracer_transport_grpc_test.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
tracer_transport_options_test.go Add http test. (#121) Oct 23, 2017
tracer_transport_proto_test.go Revert "v0.16.0 development branch (#137)" (#138) Dec 7, 2017
tracer_transport_test.go support io.Writer/io.Reader for Inject/Extract (#148) Jul 16, 2018
tracer_transport_thrift_test.go Add http test. (#121) Oct 23, 2017
util.go Events (#119) Oct 26, 2017
version.go Update version.go and VERSION to 0.15.3 (#151) Jul 16, 2018

README.md

lightstep-tracer-go

Circle CI MIT license GoDoc

The LightStep distributed tracing library for Go.

Installation

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

API Documentation

Godoc: https://godoc.org/github.com/lightstep/lightstep-tracer-go

Initialization: Starting a new tracer

To initialize a tracer, configure it with a valid Access Token and optional tuning parameters. Register the tracer as the OpenTracing global tracer so that it will become available to your installed intstrumentations libraries.

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

func main() {
  lightstepTracer := lightstep.NewTracer(lightstep.Options{
    AccessToken: "YourAccessToken",
  })

  opentracing.SetGlobalTracer(lightstepTracer)
}

Instrumenting Code: Using the OpenTracing API

All instrumentation should be done through the OpenTracing API, rather than using the lightstep tracer type directly. For API documentation and advice on instrumentation in general, see the opentracing godocs and the opentracing website.

Flushing and Closing: Managing the tracer lifecycle

As part of managaing your application lifecycle, the lightstep tracer extends the opentracing.Tracer interface with methods for manual flushing and closing. To access these methods, you can take the global tracer and typecast it to a lightstep.Tracer. As a convenience, the lightstep package provides static methods which perform the typecasting.

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

func shutdown(ctx context.Context) {
  // access the running tracer
  tracer := opentracing.GlobalTracer()
    
  // typecast from opentracing.Tracer to lightstep.Tracer
  lsTracer, ok := tracer.(lightstep.Tracer)
  if (!ok) { 
    return 
  }
  lsTracer.Close(ctx)

  // or use static methods
  lightstep.Close(ctx, tracer)
}

Event Handling: Observing the LightStep tracer

In order to connect diagnostic information from the lightstep tracer into an application's logging and metrics systems, inject an event handler using the OnEvent static method. Events may be typecast to check for errors or specific events such as status reports.

import (
  "example/logger"
  "example/metrics"
  "github.com/lightstep/lightstep-tracer-go"
)

logAndMetricsHandler := func(event lightstep.Event){
  switch event := event.(type) {
  case EventStatusReport:
    metrics.Count("tracer.dropped_spans", event.DroppedSpans())
  case ErrorEvent:
    logger.Error("LS Tracer error: %s", event)
  default:
    logger.Info("LS Tracer info: %s", event)
  }
}

func main() {
  // setup event handler first to catch startup errors
  lightstep.OnEvent(logAndMetricsHandler)
  
  lightstepTracer := lightstep.NewTracer(lightstep.Options{
    AccessToken: "YourAccessToken",
  })

  opentracing.SetGlobalTracer(lightstepTracer)
}

Event handlers will receive events from any active tracers, as well as errors in static functions. It is suggested that you set up event handling before initializing your tracer to catch any errors on initialization.

Advanced Configuration: Transport and Serialization Protocols

By default, the tracer will send information to LightStep using GRPC and Protocol Buffers which is the recommended configuration. If there are no specific transport protocol needs you have, there is no need to change this default.

There are three total options for transport protocols:

  • Protocol Buffers over GRPC - The recommended, default, and most performant solution.
  • Thrift over HTTP - A legacy implementation not recommended for new deployments.
  • [ EXPERIMENTAL ] Protocol Buffers over HTTP - New transport protocol supported for use cases where GRPC isn't an option. In order to enable HTTP you will need to configure the LightStep collectors receiving the data to accept HTTP traffic. Reach out to LightStep for support in this.

You can configure which transport protocol the tracer uses using the UseGRPC, UseThrift, and UseHttp flags in the options.