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[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ClientOption[Request, Response]
- func GRPCServerTrace[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ServerOption[Request, Response]
- func HTTPClientTrace[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kithttp.ClientOption[Request, Response]
- func HTTPServerTrace[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kithttp.ServerOption[Request, Response]
- func TraceEndpoint[Request, Response any](tracer *zipkin.Tracer, name string) endpoint.Middleware[Request, Response]
- type TracerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GRPCClientTrace ¶
func GRPCClientTrace[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ClientOption[Request, Response]
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[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kitgrpc.ServerOption[Request, Response]
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[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kithttp.ClientOption[Request, Response]
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[Request, Response any](tracer *zipkin.Tracer, options ...TracerOption) kithttp.ServerOption[Request, Response]
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[Request, Response any](tracer *zipkin.Tracer, name string) endpoint.Middleware[Request, Response]
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 RequestSampler ¶
func RequestSampler(sampleFunc func(r *http.Request) bool) TracerOption
RequestSampler allows one to set the sampling decision based on the details found in the http.Request.
func Tags ¶
func Tags(tags map[string]string) TracerOption
Tags adds default tags to our Zipkin transport spans.
Source Files