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.

Source Files

View all Source files

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
pbutil
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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.