adds basic traces using open traces
This commit is contained in:
bergquist
+222
@@ -0,0 +1,222 @@
|
||||
[![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] [![OpenTracing 1.0 Enabled][ot-img]][ot-url]
|
||||
|
||||
# Jaeger Bindings for Go OpenTracing API
|
||||
|
||||
This is a client side library that implements an
|
||||
[OpenTracing](http://opentracing.io) Tracer,
|
||||
with Zipkin-compatible data model.
|
||||
|
||||
## Installation
|
||||
|
||||
We recommended using a dependency manager like [glide](https://github.com/Masterminds/glide)
|
||||
and [semantic versioning](http://semver.org/) when including this library into an application.
|
||||
For example, Jaeger backend imports this library like this:
|
||||
|
||||
```yaml
|
||||
- package: github.com/uber/jaeger-client-go
|
||||
version: ^2.7.0
|
||||
```
|
||||
|
||||
If you instead want to use the latest version in `master`, you can pull it via `go get`.
|
||||
Note that during `go get` you may see build errors due to incompatible dependencies, which is why
|
||||
we recommend using semantic versions for dependencioes. The error may be fixed by running
|
||||
`make install` (it will install `glide` if you don't have it):
|
||||
|
||||
```shell
|
||||
go get -u github.com/uber/jaeger-client-go/
|
||||
cd $GOPATH/src/github.com/uber/jaeger-client-go/
|
||||
git submodule update --init --recursive
|
||||
make install
|
||||
```
|
||||
|
||||
## Initialization
|
||||
|
||||
See tracer initialization examples in [godoc](https://godoc.org/github.com/uber/jaeger-client-go/config#pkg-examples)
|
||||
and [config/example_test.go](./config/example_test.go).
|
||||
|
||||
### Closing the tracer via `io.Closer`
|
||||
|
||||
The constructor functions for Jaeger Tracer return the tracer itself and an `io.Closer` instance.
|
||||
It is recommended to structure your `main()` so that it calls the `Close()` function on the closer
|
||||
before exiting, e.g.
|
||||
|
||||
```go
|
||||
tracer, closer, err := cfg.New(...)
|
||||
defer closer.Close()
|
||||
```
|
||||
|
||||
This is especially useful for command-line tools that enable tracing, as well as
|
||||
for the long-running apps that support graceful shutdown. For example, if your deployment
|
||||
system sends SIGTERM instead of killing the process and you trap that signal to do a graceful
|
||||
exit, then having `defer closer.Closer()` ensures that all buffered spans are flushed.
|
||||
|
||||
### Metrics & Monitoring
|
||||
|
||||
The tracer emits a number of different metrics, defined in
|
||||
[metrics.go](metrics.go). The monitoring backend is expected to support
|
||||
tag-based metric names, e.g. instead of `statsd`-style string names
|
||||
like `counters.my-service.jaeger.spans.started.sampled`, the metrics
|
||||
are defined by a short name and a collection of key/value tags, for
|
||||
example: `name:traces, state:started, sampled:true`.
|
||||
|
||||
The monitoring backend is represented by the
|
||||
[StatsReporter](stats_reporter.go) interface. An implementation
|
||||
of that interface should be passed to the `New` method during
|
||||
tracer initialization:
|
||||
|
||||
```go
|
||||
stats := // create StatsReporter implementation
|
||||
tracer := config.Tracing.New("your-service-name", stats)
|
||||
```
|
||||
|
||||
By default, a no-op `NullStatsReporter` is used.
|
||||
|
||||
### Logging
|
||||
|
||||
The tracer can be configured with an optional logger, which will be
|
||||
used to log communication errors, or log spans if a logging reporter
|
||||
option is specified in the configuration. The logging API is abstracted
|
||||
by the [Logger](logger.go) interface. A logger instance implementing
|
||||
this interface can be set on the `Config` object before calling the
|
||||
`New` method.
|
||||
|
||||
## Instrumentation for Tracing
|
||||
|
||||
Since this tracer is fully compliant with OpenTracing API 1.0,
|
||||
all code instrumentation should only use the API itself, as described
|
||||
in the [opentracing-go]
|
||||
(https://github.com/opentracing/opentracing-go) documentation.
|
||||
|
||||
## Features
|
||||
|
||||
### Reporters
|
||||
|
||||
A "reporter" is a component receives the finished spans and reports
|
||||
them to somewhere. Under normal circumstances, the Tracer
|
||||
should use the default `RemoteReporter`, which sends the spans out of
|
||||
process via configurable "transport". For testing purposes, one can
|
||||
use an `InMemoryReporter` that accumulates spans in a buffer and
|
||||
allows to retrieve them for later verification. Also available are
|
||||
`NullReporter`, a no-op reporter that does nothing, a `LoggingReporter`
|
||||
which logs all finished spans using their `String()` method, and a
|
||||
`CompositeReporter` that can be used to combine more than one reporter
|
||||
into one, e.g. to attach a logging reporter to the main remote reporter.
|
||||
|
||||
### Span Reporting Transports
|
||||
|
||||
The remote reporter uses "transports" to actually send the spans out
|
||||
of process. Currently two supported transports are Thrift over UDP
|
||||
and Thrift over TChannel. More transports will be added in the future.
|
||||
|
||||
The only data format currently used is Zipkin Thrift 1.x span format,
|
||||
which allows easy integration of the tracer with Zipkin backend.
|
||||
|
||||
### Sampling
|
||||
|
||||
The tracer does not record all spans, but only those that have the
|
||||
sampling bit set in the `flags`. When a new trace is started and a new
|
||||
unique ID is generated, a sampling decision is made whether this trace
|
||||
should be sampled. The sampling decision is propagated to all downstream
|
||||
calls via the `flags` field of the trace context. The following samplers
|
||||
are available:
|
||||
1. `RemotelyControlledSampler` uses one of the other simpler samplers
|
||||
and periodically updates it by polling an external server. This
|
||||
allows dynamic control of the sampling strategies.
|
||||
1. `ConstSampler` always makes the same sampling decision for all
|
||||
trace IDs. it can be configured to either sample all traces, or
|
||||
to sample none.
|
||||
1. `ProbabilisticSampler` uses a fixed sampling rate as a probability
|
||||
for a given trace to be sampled. The actual decision is made by
|
||||
comparing the trace ID with a random number multiplied by the
|
||||
sampling rate.
|
||||
1. `RateLimitingSampler` can be used to allow only a certain fixed
|
||||
number of traces to be sampled per second.
|
||||
|
||||
### Baggage Injection
|
||||
|
||||
The OpenTracing spec allows for [baggage](https://github.com/opentracing/specification/blob/master/specification.md#set-a-baggage-item),
|
||||
which are key value pairs that are added to the span context and propagated
|
||||
throughout the trace.
|
||||
An external process can inject baggage by setting the special
|
||||
HTTP Header `jaeger-baggage` on a request
|
||||
|
||||
```sh
|
||||
curl -H "jaeger-baggage: key1=value1, key2=value2" http://myhost.com
|
||||
```
|
||||
|
||||
Baggage can also be programatically set inside your service by doing
|
||||
the following
|
||||
|
||||
```go
|
||||
if span := opentracing.SpanFromContext(ctx); span != nil {
|
||||
span.SetBaggageItem("key", "value")
|
||||
}
|
||||
```
|
||||
|
||||
Another service downstream of that can retrieve the baggage in a similar way:
|
||||
|
||||
```go
|
||||
if span := opentracing.SpanFromContext(ctx); span != nil {
|
||||
val := span.BaggageItem("key")
|
||||
println(val)
|
||||
}
|
||||
```
|
||||
|
||||
### Debug Traces (Forced Sampling)
|
||||
|
||||
#### Programmatically
|
||||
|
||||
The OpenTracing API defines a `sampling.priority` standard tag that
|
||||
can be used to affect the sampling of a span and its children:
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/opentracing/opentracing-go"
|
||||
"github.com/opentracing/opentracing-go/ext"
|
||||
)
|
||||
|
||||
span := opentracing.SpanFromContext(ctx)
|
||||
ext.SamplingPriority.Set(span, 1)
|
||||
```
|
||||
|
||||
#### Via HTTP Headers
|
||||
|
||||
Jaeger Tracer also understands a special HTTP Header `jaeger-debug-id`,
|
||||
which can be set in the incoming request, e.g.
|
||||
|
||||
```sh
|
||||
curl -H "jaeger-debug-id: some-correlation-id" http://myhost.com
|
||||
```
|
||||
|
||||
When Jaeger sees this header in the request that otherwise has no
|
||||
tracing context, it ensures that the new trace started for this
|
||||
request will be sampled in the "debug" mode (meaning it should survive
|
||||
all downsampling that might happen in the collection pipeline), and the
|
||||
root span will have a tag as if this statement was executed:
|
||||
|
||||
```go
|
||||
span.SetTag("jaeger-debug-id", "some-correlation-id")
|
||||
```
|
||||
|
||||
This allows using Jaeger UI to find the trace by this tag.
|
||||
|
||||
### Zipkin HTTP B3 compatible header propagation
|
||||
|
||||
Jaeger Tracer supports Zipkin B3 Propagation HTTP headers, which are used
|
||||
by a lot of Zipkin tracers. This means that you can use Jaeger in conjunction with e.g. [these OpenZipkin tracers](https://github.com/openzipkin).
|
||||
|
||||
However it is not the default propagation format, see [here](zipkin/README.md#NewZipkinB3HTTPHeaderPropagator) how to set it up.
|
||||
|
||||
## License
|
||||
|
||||
[The MIT License](LICENSE).
|
||||
|
||||
|
||||
[doc-img]: https://godoc.org/github.com/uber/jaeger-client-go?status.svg
|
||||
[doc]: https://godoc.org/github.com/uber/jaeger-client-go
|
||||
[ci-img]: https://travis-ci.org/uber/jaeger-client-go.svg?branch=master
|
||||
[ci]: https://travis-ci.org/uber/jaeger-client-go
|
||||
[cov-img]: https://coveralls.io/repos/uber/jaeger-client-go/badge.svg?branch=master&service=github
|
||||
[cov]: https://coveralls.io/github/uber/jaeger-client-go?branch=master
|
||||
[ot-img]: https://img.shields.io/badge/OpenTracing--1.0-enabled-blue.svg
|
||||
[ot-url]: http://opentracing.io
|
||||
Reference in New Issue
Block a user