tracer

package module
v0.0.0-...-4d84f8c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 21, 2016 License: MIT Imports: 20 Imported by: 0

README

Tracer – Zipping through time

Tracer is a distributed tracing system, designed after Dapper. The instrumentation is compatible with the OpenTracing specification.

Status

Tracer is currently in alpha state. It is in a working state, but very much unfinished, hardly tested and will contain bugs. You're welcome to test it, though!

Quickstart

The following steps will install Tracer, the Tracer UI and set up PostgreSQL to be used as a storage backend.

The following software is required:

  • Go 1.6 or later for building Tracer
  • PostgreSQL 9.5 or later for the storage engine
Installation
go get github.com/lygo/tracer/cmd/tracer
go get github.com/tracer/tracer-ui/cmd/tracer-ui
Configuration

Create a PostgreSQL user and schema for Tracer and import the file $GOPATH/src/github.com/lygo/tracer/storage/postgres/schema.sql.

Example:

$ createuser -s -P tracer // pass tracer
$ createdb testtracer -O tracer
$ psql testtracer tracer < $GOPATH/src/github.com/lygo/tracer/storage/postgres/schema.sql

Now you can start Tracer and its UI:

cp $GOPATH/src/github.com/lygo/tracer/cmd/tracer/example.conf .
# possibly edit example.conf
$GOPATH/bin/tracer -c example.conf &
$GOPATH/bin/tracer-ui -t $GOPATH/src/github.com/tracer/tracer-ui/zipkin-ui &

To insert a basic demo trace, run

go run $GOPATH/src/github.com/lygo/tracer/cmd/demo/demo.go

To view the UI, point your browser at http://localhost:9997/.

If you want to add instrumentation to your own code, check out OpenTracing and opentracing-go for the API. To instantiate a Tracer instance that logs to the server you just started, write something like this:

import "github.com/lygo/tracer"

...

storage, err := tracer.NewGRPC("localhost:9999", &tracer.GRPCOptions{
	QueueSize:     1024,
   	FlushInterval: 1 * time.Second,
}, grpc.WithInsecure())
if err != nil {
	log.Fatal(err)
}
t := tracer.NewTracer("frontend", storage, tracer.RandomID{})

This will create a tracer t that sends traces via gRPC to your server.

For more information on Tracer's instrumentation API check godoc.org.

Documentation

Overview

Package tracer implements a Dapper-style tracing system. It is compatible with the OpenTracing specification.

Sampling

To keep the overhead incurred by tracing low, only a subset of requests should be traced. This is achieved by a sampler. Each tracer has a sampler that may sample requests based on chance, a rate, or possibly other mechanisms. The default sampler samples all requests, which is useful for testing, and viable for low-traffic systems.

Only root spans make sampling decisions. Child spans will inherit the sampling decisions of the root spans.

Errors and logging

The instrumentation is defensive and will never purposefully panic. At the same time, most functions do not return errors, because they'll be called by automatic instrumentation, hidden from the user. Instead, errors will be logged.

Index

Constants

View Source
const (
	// The Span has been sampled.
	FlagSampled = 1 << iota
)

The various flags of a Span.

Variables

This section is empty.

Functions

func RegisterExtracter

func RegisterExtracter(format interface{}, extracter Extracter)

RegisterExtracter registers an Extracter.

func RegisterInjecter

func RegisterInjecter(format interface{}, injecter Injecter)

RegisterInjecter registers an Injecter.

Types

type Extracter

type Extracter func(carrier interface{}) (SpanContext, error)

An Extracter extracts a SpanContext from carrier.

type Flusher

type Flusher interface {
	Flush() error
}

Flusher is an optional interface that when implemented allows a Storer to flush buffered spawns.

type GRPC

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

GRPC is a gRPC-based transport for sending spans to a server.

func (*GRPC) Flush

func (g *GRPC) Flush() error

func (*GRPC) Store

func (g *GRPC) Store(sp RawSpan) error

Store implements the tracer.Storer interface.

type GRPCOptions

type GRPCOptions struct {
	// How many spans to queue before sending them to the server.
	// Additionally, a buffer the size of 2*QueueSize will be used to
	// process new spans. If this buffer runs full, new spans will be
	// dropped.
	QueueSize int
	// How often to flush spans, even if the queue isn't full yet.
	FlushInterval time.Duration
	// Where to log errors. If nil, the default logger will be used.
	Logger Logger
}

GRPCOptions are options for the GRPC storer.

type IDGenerator

type IDGenerator interface {
	GenerateID() uint64
}

IDGenerator generates IDs for traces and spans. The ID with value 0 is reserved to mean "no parent span" and should not be generated.

type Injecter

type Injecter func(sm SpanContext, carrier interface{}) error

An Injecter injects a SpanContext into carrier.

type Logger

type Logger interface {
	// Printf logs a single message, given a format and values. The
	// format is documented in the fmt package.
	Printf(format string, values ...interface{})
}

A Logger logs messages.

type RandomID

type RandomID struct{}

RandomID generates random IDs by using crypto/rand.

func (RandomID) GenerateID

func (RandomID) GenerateID() uint64

GenerateID generates an ID.

type RawRelation

type RawRelation struct {
	ParentID uint64 `json:"parent_id"`
	ChildID  uint64 `json:"child_id"`
	Kind     string `json:"kind"`
}

A RawRelation represents the relation between two spans.

type RawSpan

type RawSpan struct {
	SpanContext
	ServiceName   string    `json:"service_name"`
	OperationName string    `json:"operation_name"`
	StartTime     time.Time `json:"start_time"`
	FinishTime    time.Time `json:"finish_time"`

	Tags map[string]interface{} `json:"tags"`
	Logs []opentracing.LogData  `json:"logs"`
}

A RawSpan contains all the data associated with a span.

type RawTrace

type RawTrace struct {
	TraceID   uint64        `json:"trace_id"`
	Spans     []RawSpan     `json:"spans"`
	Relations []RawRelation `json:"relations"`
}

A RawTrace contains all the data associated with a trace.

type Sampler

type Sampler interface {
	Sample(id uint64) bool
}

A Sampler determines whether a span should be sampled or not by returning true or false.

func NewConstSampler

func NewConstSampler(decision bool) Sampler

NewConstSampler returns a constant sampler that always returns the same decision.

func NewProbabilisticSampler

func NewProbabilisticSampler(chance float64) Sampler

NewProbabilisticSampler returns a sampler that samples spans with a certain chance, which should be in [0, 1].

func NewRateSampler

func NewRateSampler(n int) Sampler

NewRateSampler returns a sampler that samples up to n samples per second.

type Span

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

Span is an implementation of the OpenTracing Span interface.

func (*Span) BaggageItem

func (sp *Span) BaggageItem(key string) string

BaggageItem implements the opentracing.Tracer interface.

func (*Span) Context

func (sp *Span) Context() opentracing.SpanContext

Context implements the opentracing.Span interface.

func (*Span) Finish

func (sp *Span) Finish()

Finish implements the opentracing.Span interface.

func (*Span) FinishWithOptions

func (sp *Span) FinishWithOptions(opts opentracing.FinishOptions)

FinishWithOptions implements the opentracing.Span interface.

func (*Span) Log

func (sp *Span) Log(data opentracing.LogData)

Log implements the opentracing.Span interface.

func (*Span) LogEvent

func (sp *Span) LogEvent(event string)

LogEvent implements the opentracing.Span interface.

func (*Span) LogEventWithPayload

func (sp *Span) LogEventWithPayload(event string, payload interface{})

LogEventWithPayload implements the opentracing.Span interface.

func (*Span) LogFields

func (sp *Span) LogFields(fields ...tracinglog.Field)

func (*Span) LogKV

func (sp *Span) LogKV(keyValues ...interface{})

func (*Span) RawSpan

func (sp *Span) RawSpan() RawSpan

RawSpan returns a deep copy of the span's underlying data.

func (*Span) Sampled

func (sp *Span) Sampled() bool

Sampled reports whether this span was sampled.

func (*Span) SetBaggageItem

func (sp *Span) SetBaggageItem(key, value string) opentracing.Span

SetBaggageItem implements the opentracing.Tracer interface.

func (*Span) SetOperationName

func (sp *Span) SetOperationName(name string) opentracing.Span

SetOperationName implements the opentracing.Span interface.

func (*Span) SetTag

func (sp *Span) SetTag(key string, value interface{}) opentracing.Span

SetTag implements the opentracing.Span interface.

func (*Span) Tracer

func (sp *Span) Tracer() opentracing.Tracer

Tracer implements the opentracing.Span interface.

type SpanContext

type SpanContext struct {
	TraceID  uint64            `json:"trace_id"`
	ParentID uint64            `json:"parent_id"`
	SpanID   uint64            `json:"span_id"`
	Flags    uint64            `json:"flags"`
	Baggage  map[string]string `json:"baggage"`
}

SpanContext contains the parts of a span that will be sent to downstream services.

func (SpanContext) ForeachBaggageItem

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

ForeachBaggageItem implements the opentracing.Tracer interface.

type Storer

type Storer interface {
	Store(sp RawSpan) error
}

A Storer stores a finished span. "Storing" a span may either mean saving it in a storage engine, or sending it to a remote collector.

If a span with the same ID and the same trace ID already exists, the existing and new spans should be merged into one span.

Because spans are only stored once they're done, children will be stored before their parents.

func NewGRPC

func NewGRPC(address string, grpcOpts *GRPCOptions, opts ...grpc.DialOption) (Storer, error)

NewGRPC returns a new Storer that sends spans via gRPC to a server.

type Tracer

type Tracer struct {
	ServiceName string
	Logger      Logger
	Sampler     Sampler
	// contains filtered or unexported fields
}

Tracer is an implementation of the OpenTracing Tracer interface.

func NewTracer

func NewTracer(serviceName string, storer Storer, idGenerator IDGenerator) *Tracer

NewTracer returns a new tracer.

func (*Tracer) Extract

func (tr *Tracer) Extract(format interface{}, carrier interface{}) (opentracing.SpanContext, error)

Extract implements the opentracing.Tracer interface.

func (*Tracer) Flush

func (tr *Tracer) Flush() error

func (*Tracer) Inject

func (tr *Tracer) Inject(sm opentracing.SpanContext, format interface{}, carrier interface{}) error

Inject implements the opentracing.Tracer interface.

func (*Tracer) StartSpan

func (tr *Tracer) StartSpan(operationName string, opts ...opentracing.StartSpanOption) opentracing.Span

StartSpan implements the opentracing.Tracer interface.

Directories

Path Synopsis
Package client is a client for the HTTP query transport.
Package client is a client for the HTTP query transport.
cmd
demo
Command demo creates an example trace.
Command demo creates an example trace.
tracer
Command tracer is the Tracer query and storage server.
Command tracer is the Tracer query and storage server.
tracer-cli
Command tracer-cli provides a CLI query client.
Command tracer-cli provides a CLI query client.
tracer/config
Package config parses Tracer configuration files.
Package config parses Tracer configuration files.
internal
Package pb is a generated protocol buffer package.
Package pb is a generated protocol buffer package.
Package server implements the Tracer server.
Package server implements the Tracer server.
storage
null
Package null is a null storage.
Package null is a null storage.
postgres
Package postgres is a PostgreSQL storage.
Package postgres is a PostgreSQL storage.
Package tracerutil provides helpers for tracing various components.
Package tracerutil provides helpers for tracing various components.
transport
grpc
Package grpc is a gRPC-based storage transport.
Package grpc is a gRPC-based storage transport.
http
Package http is an HTTP-based query transport.
Package http is an HTTP-based query transport.
zipkinhttp
Package zipkinhttp is an HTTP-based query transport that implements the Zipkin v1 API.
Package zipkinhttp is an HTTP-based query transport that implements the Zipkin v1 API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL