linkin

README

linkin

Opencensus Trace propagation for linkerd.

Opencensus is a single distribution of libraries that automatically collects traces and metrics from your app, displays them locally, and sends them to any analysis tool.

Opencensus supports the Zipkin request tracing system, among others. Zipkin is a popular distributed tracing system, allowing requests to be traced through a distributed system. A request is broken into 'spans', each representing one part of the greater request path. Software that wishes to leverage Zipkin must be instrumented to do so (for example via Opencensus).

linkerd is a popular service mesh. One of linkerd's selling points is that it provides Zipkin request tracing 'for free'. Software need not be 'fully' instrumented, and instead need only copy linkerd's l5d-ctx-trace HTTP headers from incoming HTTP requests to any outgoing HTTP requests they spawn. Unfortunately while linkerd emits traces to Zipkin, it propagates trace data along the request path via a non-standard header. This package may be used as a drop-in replacement for Opencensus's standard Zipkin propagation in environments that use linkerd for part or all of their request tracing needs.

In addition to propagating linkerd trace context from incoming to outgoing HTTP requests via the ochttp library, Opencensus may be used to add spans representing in-application method or database calls to a linkerd trace.

Usage

// ochttp will automatically inject a span into the context of requests handled
// by usersHandler. If incoming requests contain a valid l5d-ctx-trace header
// the injected span will be a child of the calling span.
http.Handle("/users", usersHandler)
log.Fatal(http.ListenAndServe("localhost:8080", &ochttp.Handler{Propagation: &linkin.HTTPFormat{}}))

// ochttp will automatically inject a span into the context of outgoing requests
// sent by the client. Span metadata will be propagated via outgoing requests'
// l5d-ctx-trace header.
client := http.Client{Transport: &ochttp.Transport{Propagation: &linkin.HTTPFormat{}}}

// Create a relationship between the incoming and outgoing requests by
// propagating the incoming request's context to the child. If the incoming
// request's context contains a span the outgoing request's span will be its
// child.
outgoingRequest, _ := http.NewRequest("GET", d, nil)
outgoingRequest = out.WithContext(incomingRequest.Context())
rsp, _ := client.Do(out)

A more complete example exists at example/. The ochttp godoc may also be illustrative.

Documentation

Overview

Package linkin provides linkerd trace propagation for Opencensus.

Opencensus is a single distribution of libraries that automatically collects traces and metrics from your app, displays them locally, and sends them to any analysis tool. Opencensus supports the Zipkin request tracing system.

Zipkin is a popular distributed tracing system, allowing requests to be traced through a distributed system. A request is broken into 'spans', each representing one part of the greater request path. Software that wishes to leverage Zipkin must be instrumented to do so (for example via Opencensus).

linkerd is a popular service mesh. One of linkerd's selling points is that it provides Zipkin request tracing 'for free'. Software need not be 'fully' instrumented, and instead need only copy linkerd's l5d-ctx-* HTTP headers from incoming HTTP requests to any outgoing HTTP requests they spawn.

Unfortunately while linkerd emits traces to Zipkin, it propagates trace data via a non-standard header. This package may be used as a drop-in replacement for https://godoc.org/go.opencensus.io/plugin/ochttp/propagation/b3 in environments that use linkerd for part or all of their request tracing needs.

linkerd trace headers are base64 encoded 32 or 40 byte arrays (depending on whether the trace ID is 64 or 128bit) with the following Finagle serialization format:

spanID:8 parentID:8 traceIDLow:8 flags:8 traceIDHigh:8

https://github.com/twitter/finagle/blob/345d7a2/finagle-core/src/main/scala/com/twitter/finagle/tracing/Id.scala#L113 https://github.com/twitter/finagle/blob/345d7a2/finagle-core/src/main/scala/com/twitter/finagle/tracing/Flags.scala

Index

• type HTTPFormat
  • func (f *HTTPFormat) SpanContextFromRequest(r *http.Request) (trace.SpanContext, bool)
  • func (f *HTTPFormat) SpanContextToRequest(sc trace.SpanContext, r *http.Request)

Types

type HTTPFormat

type HTTPFormat struct{}

HTTPFormat implements propagation.HTTPFormat to propagate traces in HTTP headers in linkerd propagation format. HTTPFormat omits the parent ID because it is not represented in the OpenCensus span context. Spans created from the incoming header will be the direct children of the client-side span. Similarly, the receiver of the outgoing spans should use client-side span created by OpenCensus as the parent.

func (*HTTPFormat) SpanContextFromRequest

func (f *HTTPFormat) SpanContextFromRequest(r *http.Request) (trace.SpanContext, bool)

SpanContextFromRequest extracts linkerd span context from incoming requests.

func (*HTTPFormat) SpanContextToRequest

func (f *HTTPFormat) SpanContextToRequest(sc trace.SpanContext, r *http.Request)

SpanContextToRequest modifies the given request to include an l5d-ctx-trace HTTP header derived from the given SpanContext.