zipkin

Documentation

Index

• Constants
• func AnnotateClient(newSpan NewSpanFunc, c Collector) endpoint.Middleware
• func AnnotateServer(newSpan NewSpanFunc, c Collector) endpoint.Middleware
• func ToContext(newSpan NewSpanFunc, logger log.Logger) func(ctx context.Context, r *http.Request) context.Context
• func ToGRPCContext(newSpan NewSpanFunc, logger log.Logger) func(ctx context.Context, md *metadata.MD) context.Context
• func ToGRPCRequest(newSpan NewSpanFunc) func(ctx context.Context, md *metadata.MD) context.Context
• func ToRequest(newSpan NewSpanFunc) func(ctx context.Context, r *http.Request) context.Context
• type CollectionError
• type Collector
  • func NewKafkaCollector(addrs []string, options ...KafkaOption) (Collector, error)
  • func NewScribeCollector(addr string, timeout time.Duration, options ...ScribeOption) (Collector, error)
• type KafkaCollector
  • func (c *KafkaCollector) Close() error
  • func (c *KafkaCollector) Collect(s *Span) error
• type KafkaOption
  • func KafkaLogger(logger log.Logger) KafkaOption
  • func KafkaProducer(p sarama.AsyncProducer) KafkaOption
  • func KafkaSampleRate(sr Sampler) KafkaOption
  • func KafkaTopic(t string) KafkaOption
• type MultiCollector
  • func (c MultiCollector) Close() error
  • func (c MultiCollector) Collect(s *Span) error
• type NewSpanFunc
  • func MakeNewSpanFunc(hostport, serviceName, methodName string) NewSpanFunc
• type NopCollector
  • func (NopCollector) Close() error
  • func (NopCollector) Collect(*Span) error
• type Sampler
  • func SampleRate(rate float64, salt int64) Sampler
• type ScribeCollector
  • func (c *ScribeCollector) Close() error
  • func (c *ScribeCollector) Collect(s *Span) error
• type ScribeOption
  • func ScribeBatchInterval(d time.Duration) ScribeOption
  • func ScribeBatchSize(n int) ScribeOption
  • func ScribeCategory(category string) ScribeOption
  • func ScribeLogger(logger log.Logger) ScribeOption
  • func ScribeSampleRate(sr Sampler) ScribeOption
• type Span
  • func FromContext(ctx context.Context) (*Span, bool)
  • func NewSpan(hostport, serviceName, methodName string, traceID, spanID, parentSpanID int64) *Span
  • func (s *Span) Annotate(value string)
  • func (s *Span) AnnotateBinary(key string, value interface{})
  • func (s *Span) AnnotateDuration(value string, duration time.Duration)
  • func (s *Span) AnnotateString(key, value string)
  • func (s *Span) Encode() *zipkincore.Span
  • func (s *Span) ParentSpanID() int64
  • func (s *Span) SpanID() int64
  • func (s *Span) TraceID() int64

Constants

const (
	// SpanContextKey holds the key used to store Zipkin spans in the context.
	SpanContextKey = "Zipkin-Span"

	// ClientSend is the annotation value used to mark a client sending a
	// request to a server.
	ClientSend = "cs"

	// ServerReceive is the annotation value used to mark a server's receipt
	// of a request from a client.
	ServerReceive = "sr"

	// ServerSend is the annotation value used to mark a server's completion
	// of a request and response to a client.
	ServerSend = "ss"

	// ClientReceive is the annotation value used to mark a client's receipt
	// of a completed request from a server.
	ClientReceive = "cr"
)

Functions

func AnnotateClient

func AnnotateClient(newSpan NewSpanFunc, c Collector) endpoint.Middleware

AnnotateClient returns a middleware that extracts a parent span from the context, produces a client (child) span from it, adds client-send and client-receive annotations at the boundaries, and submits the span to the collector. If no span is found in the context, a new span is generated and inserted.

func AnnotateServer

func AnnotateServer(newSpan NewSpanFunc, c Collector) endpoint.Middleware

AnnotateServer returns a server.Middleware that extracts a span from the context, adds server-receive and server-send annotations at the boundaries, and submits the span to the collector. If no span is found in the context, a new span is generated and inserted.

func ToContext

func ToContext(newSpan NewSpanFunc, logger log.Logger) func(ctx context.Context, r *http.Request) context.Context

ToContext returns a function that satisfies transport/http.BeforeFunc. It takes a Zipkin span from the incoming HTTP request, and saves it in the request context. It's designed to be wired into a server's HTTP transport Before stack. The logger is used to report errors.

func ToGRPCContext

func ToGRPCContext(newSpan NewSpanFunc, logger log.Logger) func(ctx context.Context, md *metadata.MD) context.Context

ToGRPCContext returns a function that satisfies transport/grpc.BeforeFunc. It takes a Zipkin span from the incoming GRPC request, and saves it in the request context. It's designed to be wired into a server's GRPC transport Before stack. The logger is used to report errors.

func ToGRPCRequest

func ToGRPCRequest(newSpan NewSpanFunc) func(ctx context.Context, md *metadata.MD) context.Context

ToGRPCRequest returns a function that satisfies transport/grpc.BeforeFunc. It takes a Zipkin span from the context, and injects it into the GRPC context. It's designed to be wired into a client's GRPC transport Before stack. It's expected that AnnotateClient has already ensured the span in the context is a child/client span.

func ToRequest

func ToRequest(newSpan NewSpanFunc) func(ctx context.Context, r *http.Request) context.Context

ToRequest returns a function that satisfies transport/http.BeforeFunc. It takes a Zipkin span from the context, and injects it into the HTTP request. It's designed to be wired into a client's HTTP transport Before stack. It's expected that AnnotateClient has already ensured the span in the context is a child/client span.

Types

type CollectionError

type CollectionError interface {
	Error() string
	GetErrors() []error
}

CollectionError represents an array of errors returned by one or more failed Collector methods.

type Collector

type Collector interface {
	Collect(*Span) error
	Close() error
}

Collector represents a Zipkin trace collector, which is probably a set of remote endpoints.

func NewKafkaCollector

func NewKafkaCollector(addrs []string, options ...KafkaOption) (Collector, error)

NewKafkaCollector returns a new Kafka-backed Collector. addrs should be a slice of TCP endpoints of the form "host:port".

func NewScribeCollector

func NewScribeCollector(addr string, timeout time.Duration, options ...ScribeOption) (Collector, error)

NewScribeCollector returns a new Scribe-backed Collector. addr should be a TCP endpoint of the form "host:port". timeout is passed to the Thrift dial function NewTSocketFromAddrTimeout. batchSize and batchInterval control the maximum size and interval of a batch of spans; as soon as either limit is reached, the batch is sent. The logger is used to log errors, such as batch send failures; users should provide an appropriate context, if desired.

type KafkaCollector

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

KafkaCollector implements Collector by publishing spans to a Kafka broker.

func (*KafkaCollector) Close

func (c *KafkaCollector) Close() error

Close implements Collector.

func (*KafkaCollector) Collect

func (c *KafkaCollector) Collect(s *Span) error

Collect implements Collector.

type KafkaOption

type KafkaOption func(c *KafkaCollector)

KafkaOption sets a parameter for the KafkaCollector

func KafkaLogger

func KafkaLogger(logger log.Logger) KafkaOption

KafkaLogger sets the logger used to report errors in the collection process. By default, a no-op logger is used, i.e. no errors are logged anywhere. It's important to set this option.

func KafkaProducer

func KafkaProducer(p sarama.AsyncProducer) KafkaOption

KafkaProducer sets the producer used to produce to Kafka.

func KafkaSampleRate

func KafkaSampleRate(sr Sampler) KafkaOption

KafkaSampleRate sets the sample rate used to determine if a trace will be sent to the collector. By default, the sample rate is 1.0, i.e. all traces are sent.

func KafkaTopic

func KafkaTopic(t string) KafkaOption

KafkaTopic sets the kafka topic to attach the collector producer on.

type MultiCollector

type MultiCollector []Collector

MultiCollector implements Collector by sending spans to all collectors.

func (MultiCollector) Close

func (c MultiCollector) Close() error

Close implements Collector.

func (MultiCollector) Collect

func (c MultiCollector) Collect(s *Span) error

Collect implements Collector.

type NewSpanFunc

type NewSpanFunc func(traceID, spanID, parentSpanID int64) *Span

NewSpanFunc takes trace, span, & parent span IDs to produce a Span object.

func MakeNewSpanFunc

func MakeNewSpanFunc(hostport, serviceName, methodName string) NewSpanFunc

MakeNewSpanFunc returns a function that generates a new Zipkin span.

type NopCollector

type NopCollector struct{}

NopCollector implements Collector but performs no work.

func (NopCollector) Close

func (NopCollector) Close() error

Close implements Collector.

func (NopCollector) Collect

func (NopCollector) Collect(*Span) error

Collect implements Collector.

type Sampler

type Sampler func(id int64) bool

Sampler functions return if a Zipkin span should be sampled, based on its traceID.

func SampleRate

func SampleRate(rate float64, salt int64) Sampler

SampleRate returns a sampler function using a particular sample rate and a sample salt to identify if a Zipkin span based on its spanID should be collected.

type ScribeCollector

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

ScribeCollector implements Collector by forwarding spans to a Scribe service, in batches.

func (*ScribeCollector) Close

func (c *ScribeCollector) Close() error

Close implements Collector.

func (*ScribeCollector) Collect

func (c *ScribeCollector) Collect(s *Span) error

Collect implements Collector.

type ScribeOption

type ScribeOption func(s *ScribeCollector)

ScribeOption sets a parameter for the StdlibAdapter.

func ScribeBatchInterval

func ScribeBatchInterval(d time.Duration) ScribeOption

ScribeBatchInterval sets the maximum duration we will buffer traces before emitting them to the collector. The default batch interval is 1 second.

func ScribeBatchSize

func ScribeBatchSize(n int) ScribeOption

ScribeBatchSize sets the maximum batch size, after which a collect will be triggered. The default batch size is 100 traces.

func ScribeCategory

func ScribeCategory(category string) ScribeOption

ScribeCategory sets the Scribe category used to transmit the spans.

func ScribeLogger

func ScribeLogger(logger log.Logger) ScribeOption

ScribeLogger sets the logger used to report errors in the collection process. By default, a no-op logger is used, i.e. no errors are logged anywhere. It's important to set this option in a production service.

func ScribeSampleRate

func ScribeSampleRate(sr Sampler) ScribeOption

ScribeSampleRate sets the sample rate used to determine if a trace will be sent to the collector. By default, the sample rate is 1.0, i.e. all traces are sent.

type Span

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

A Span is a named collection of annotations. It represents meaningful information about a single method call, i.e. a single request against a service. Clients should annotate the span, and submit it when the request that generated it is complete.

func FromContext

func FromContext(ctx context.Context) (*Span, bool)

FromContext extracts an existing Zipkin span if it is stored in the provided context. If you add context.Context as the first parameter in your service methods you can annotate spans from within business logic. Typical use case is to AnnotateDuration on interaction with resources like databases.

func NewSpan

func NewSpan(hostport, serviceName, methodName string, traceID, spanID, parentSpanID int64) *Span

NewSpan returns a new Span, which can be annotated and collected by a collector. Spans are passed through the request context to each middleware under the SpanContextKey.

func (*Span) Annotate

func (s *Span) Annotate(value string)

Annotate annotates the span with the given value.

func (*Span) AnnotateBinary

func (s *Span) AnnotateBinary(key string, value interface{})

AnnotateBinary annotates the span with a key and a value that will be []byte encoded.

func (*Span) AnnotateDuration

func (s *Span) AnnotateDuration(value string, duration time.Duration)

AnnotateDuration annotates the span with the given value and duration.

func (*Span) AnnotateString

func (s *Span) AnnotateString(key, value string)

AnnotateString annotates the span with a key and a string value.

func (*Span) Encode

func (s *Span) Encode() *zipkincore.Span

Encode creates a Thrift Span from the gokit Span.

func (*Span) ParentSpanID

func (s *Span) ParentSpanID() int64

ParentSpanID returns the ID of the span which invoked this span. It may be zero.

func (*Span) SpanID

func (s *Span) SpanID() int64

SpanID returns the ID of this span.

func (*Span) TraceID

func (s *Span) TraceID() int64

TraceID returns the ID of the trace that this span is a member of.