README.md
1# lightstep-tracer-go
2
3[](https://circleci.com/gh/lightstep/lightstep-tracer-go)
4[](http://opensource.org/licenses/MIT)
5[](https://godoc.org/github.com/lightstep/lightstep-tracer-go)
6
7The LightStep distributed tracing library for Go.
8
9**Looking for the LightStep OpenCensus exporter? Check out the [`lightstepoc` package](./lightstepoc).**
10
11## Installation
12
13```
14$ go get 'github.com/lightstep/lightstep-tracer-go'
15```
16
17## API Documentation
18
19Godoc: https://godoc.org/github.com/lightstep/lightstep-tracer-go
20
21## Initialization: Starting a new tracer
22To 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 instrumentation libraries.
23
24```go
25import (
26 "github.com/opentracing/opentracing-go"
27 "github.com/lightstep/lightstep-tracer-go"
28)
29
30func main() {
31 lightstepTracer := lightstep.NewTracer(lightstep.Options{
32 AccessToken: "YourAccessToken",
33 })
34
35 opentracing.SetGlobalTracer(lightstepTracer)
36}
37```
38
39## Instrumenting Code: Using the OpenTracing API
40
41All 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.
42
43- https://godoc.org/github.com/opentracing/opentracing-go
44- http://opentracing.io
45
46## Flushing and Closing: Managing the tracer lifecycle
47
48As part of managing 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.
49
50```go
51import (
52 "context"
53 "github.com/opentracing/opentracing-go"
54 "github.com/lightstep/lightstep-tracer-go"
55)
56
57func shutdown(ctx context.Context) {
58 // access the running tracer
59 tracer := opentracing.GlobalTracer()
60
61 // typecast from opentracing.Tracer to lightstep.Tracer
62 lsTracer, ok := tracer.(lightstep.Tracer)
63 if (!ok) {
64 return
65 }
66 lsTracer.Close(ctx)
67
68 // or use static methods
69 lightstep.Close(ctx, tracer)
70}
71```
72
73## Event Handling: Observing the LightStep tracer
74In 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.
75
76```go
77import (
78 "example/logger"
79 "example/metrics"
80 "github.com/lightstep/lightstep-tracer-go"
81)
82
83logAndMetricsHandler := func(event lightstep.Event){
84 switch event := event.(type) {
85 case EventStatusReport:
86 metrics.Count("tracer.dropped_spans", event.DroppedSpans())
87 case ErrorEvent:
88 logger.Error("LS Tracer error: %s", event)
89 default:
90 logger.Info("LS Tracer info: %s", event)
91 }
92}
93
94func main() {
95 // setup event handler first to catch startup errors
96 lightstep.SetGlobalEventHandler(logAndMetricsHandler)
97
98 lightstepTracer := lightstep.NewTracer(lightstep.Options{
99 AccessToken: "YourAccessToken",
100 })
101
102 opentracing.SetGlobalTracer(lightstepTracer)
103}
104```
105
106Event 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.
107
108## Advanced Configuration: Transport and Serialization Protocols
109
110By following the above configuration, the tracer will send information to LightStep using HTTP 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.
111
112There are two options for transport protocols:
113
114- [Protocol Buffers](https://developers.google.com/protocol-buffers/) over HTTP - The recommended and default solution.
115- [Protocol Buffers](https://developers.google.com/protocol-buffers/) over [GRPC](https://grpc.io/) - This is a more advanced solution that might be desirable if you already have gRPC networking configured.
116
117You can configure which transport protocol the tracer uses using the `UseGRPC` and `UseHttp` flags in the options.
118
){kind=link}
){kind=link}
){kind=link}