zipkin

README

Zipkin

Development and Testing Set-up

Great efforts have been made to make Zipkin easier to test, develop and experiment against. Zipkin can now be run from a single Docker container or by running its self-contained executable jar without extensive configuration. In its default configuration you will run Zipkin with a HTTP collector, In memory Span storage backend and web UI on port 9411.

Example:

docker run -d -p 9411:9411 openzipkin/zipkin

Middleware Usage

Follow the addsvc example to check out how to wire the Zipkin Middleware. The changes should be relatively minor.

The zipkin-go package has Reporters to send Spans to the Zipkin HTTP and Kafka Collectors.

Configuring the Zipkin HTTP Reporter

To use the HTTP Reporter with a Zipkin instance running on localhost you bootstrap zipkin-go like this:

var (
  serviceName        = "MyService"
  serviceHostPort    = "localhost:8000"
  zipkinHTTPEndpoint = "http://localhost:9411/api/v2/spans"
)

// create an instance of the HTTP Reporter.
reporter := zipkin.NewReporter(zipkinHTTPEndpoint)

// create our tracer's local endpoint (how the service is identified in Zipkin).
localEndpoint, err := zipkin.NewEndpoint(serviceName, serviceHostPort)

// create our tracer instance.
tracer, err = zipkin.NewTracer(reporter, zipkin.WithLocalEndpoint(localEndpoint))
  ...

Tracing Resources

Here is an example of how you could trace resources and work with local spans.

import (
	zipkin "github.com/openzipkin/zipkin-go"
)

func (svc *Service) GetMeSomeExamples(ctx context.Context, ...) ([]Examples, error) {
  // Example of annotating a database query:
  var (
    spanContext model.SpanContext
    serviceName = "MySQL"
    serviceHost = "mysql.example.com:3306"
    queryLabel  = "GetExamplesByParam"
    query       = "select * from example where param = :value"
  )

  // retrieve the parent span from context to use as parent if available.
  if parentSpan := zipkin.SpanFromContext(ctx); parentSpan != nil {
    spanContext = parentSpan.Context()
  }

  // create the remote Zipkin endpoint
  ep, _ := zipkin.NewEndpoint(serviceName, serviceHost)

  // create a new span to record the resource interaction
  span := zipkin.StartSpan(
    queryLabel,
    zipkin.Parent(parentSpan.Context()),
    zipkin.WithRemoteEndpoint(ep),
  )

	// add interesting key/value pair to our span
	span.SetTag("query", query)

	// add interesting timed event to our span
	span.Annotate(time.Now(), "query:start")

	// do the actual query...

	// let's annotate the end...
	span.Annotate(time.Now(), "query:end")

	// we're done with this span.
	span.Finish()

	// do other stuff
	...
}

Documentation

Overview

Package zipkin provides Go kit integration to the OpenZipkin project through the use of zipkin-go, the official OpenZipkin tracer implementation for Go. OpenZipkin is the most used open source distributed tracing ecosystem with many different libraries and interoperability options.

Index

• func GRPCClientTrace(tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ClientOption
• func GRPCServerTrace(tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ServerOption
• func HTTPClientTrace(tracer *zipkin.Tracer, options ...TracerOption) kithttp.ClientOption
• func HTTPServerTrace(tracer *zipkin.Tracer, options ...TracerOption) kithttp.ServerOption
• func TraceEndpoint(tracer *zipkin.Tracer, name string) endpoint.Middleware
• type TracerOption
  • func AllowPropagation(propagate bool) TracerOption
  • func Logger(logger log.Logger) TracerOption
  • func Name(name string) TracerOption
  • func Tags(tags map[string]string) TracerOption

Functions

func GRPCClientTrace

func GRPCClientTrace(tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ClientOption

GRPCClientTrace enables native Zipkin tracing of a Go kit gRPC transport Client.

Go kit creates gRPC transport clients per remote endpoint. This middleware can be set-up individually by adding the endpoint name for each of the Go kit transport clients using the Name() TracerOption. If wanting to use the gRPC FullMethod (/service/method) as Span name you can create a global client tracer omitting the Name() TracerOption, which you can then feed to each Go kit gRPC transport client. If instrumenting a client to an external (not on your platform) service, you will probably want to disallow propagation of SpanContext using the AllowPropagation TracerOption and setting it to false.

func GRPCServerTrace

func GRPCServerTrace(tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ServerOption

GRPCServerTrace enables native Zipkin tracing of a Go kit gRPC transport Server.

Go kit creates gRPC transport servers per gRPC method. This middleware can be set-up individually by adding the method name for each of the Go kit method servers using the Name() TracerOption. If wanting to use the gRPC FullMethod (/service/method) as Span name you can create a global server tracer omitting the Name() TracerOption, which you can then feed to each Go kit method server. For this to work you will need to wire the Go kit gRPC Interceptor too. If instrumenting a service to external (not on your platform) clients, you will probably want to disallow propagation of a client SpanContext using the AllowPropagation TracerOption and setting it to false.

func HTTPClientTrace

func HTTPClientTrace(tracer *zipkin.Tracer, options ...TracerOption) kithttp.ClientOption

HTTPClientTrace enables native Zipkin tracing of a Go kit HTTP transport Client.

Go kit creates HTTP transport clients per remote endpoint. This middleware can be set-up individually by adding the endpoint name for each of the Go kit transport clients using the Name() TracerOption. If wanting to use the HTTP Method (Get, Post, Put, etc.) as Span name you can create a global client tracer omitting the Name() TracerOption, which you can then feed to each Go kit transport client. If instrumenting a client to an external (not on your platform) service, you will probably want to disallow propagation of SpanContext using the AllowPropagation TracerOption and setting it to false.

func HTTPServerTrace

func HTTPServerTrace(tracer *zipkin.Tracer, options ...TracerOption) kithttp.ServerOption

HTTPServerTrace enables native Zipkin tracing of a Go kit HTTP transport Server.

Go kit creates HTTP transport servers per HTTP endpoint. This middleware can be set-up individually by adding the method name for each of the Go kit method servers using the Name() TracerOption. If wanting to use the HTTP method (Get, Post, Put, etc.) as Span name you can create a global server tracer omitting the Name() TracerOption, which you can then feed to each Go kit method server.

If instrumenting a service to external (not on your platform) clients, you will probably want to disallow propagation of a client SpanContext using the AllowPropagation TracerOption and setting it to false.

func TraceEndpoint

func TraceEndpoint(tracer *zipkin.Tracer, name string) endpoint.Middleware

TraceEndpoint returns an Endpoint middleware, tracing a Go kit endpoint. This endpoint tracer should be used in combination with a Go kit Transport tracing middleware or custom before and after transport functions as propagation of SpanContext is not provided in this middleware.

Types

type TracerOption

type TracerOption func(o *tracerOptions)

TracerOption allows for functional options to our Zipkin tracing middleware.

func AllowPropagation

func AllowPropagation(propagate bool) TracerOption

AllowPropagation instructs the tracer to allow or deny propagation of the span context between this instrumented client or service and its peers. If the instrumented client connects to services outside its own platform or if the instrumented service receives requests from untrusted clients it is strongly advised to disallow propagation. Propagation between services inside your own platform benefit from propagation. Default for both TraceClient and TraceServer is to allow propagation.

func Logger

func Logger(logger log.Logger) TracerOption

Logger adds a Go kit logger to our Zipkin Middleware to log SpanContext extract / inject errors if they occur. Default is Noop.

func Name

func Name(name string) TracerOption

Name sets the name for an instrumented transport endpoint. If name is omitted at tracing middleware creation, the method of the transport or transport rpc name is used.

func Tags

func Tags(tags map[string]string) TracerOption

Tags adds default tags to our Zipkin transport spans.