README
¶
httptrace -Zipkin tracing integration for HTTP services.
Status: Production
This project contains middleware for HTTP services and clients that uses openzipkin-go and logevent to both propagate traces between HTTP services and emit traces to the service logs.
Usage
HTTP Service
The middleware exported is a func(http.Handler) http.Handler and should
work with virtually any router/mux implementation that supports middleware.
var middleware = httptrace.NewMiddleware(
httptrace.MiddlewareOptionServiceName("my-service"),
)
The middleware uses
opentracing-go to manage
spans and should interoperate with other uses of opentracing that leverage the
context as a source of the tracer. If no trace is found in the incoming
request then the middleware will generate a new trace and root span using the
given service name. If the incoming request does contain a trace, via zipkin
headers, then the middleware generate a span within that trace that is a child
of the incoming span.
If you need the identifier of the active trace at any point within a request,
you can use the TraceIDFromContext or SpanIDFromContext helpers which will
return the ID in a hex encoded string which is what typically ships over via
headers to other services.
HTTP Client
In addition to an HTTP middleware, there is also an http.RoundTripper wrapper
included that will properly manage spans for outgoing HTTP requests. To apply:
var client = &http.Client{
Transport: httptrace.NewTransport(
httptrace.TransportOptionSpanName("outgoing_http_request"),
httptrace.TransportOptionPeerName("remote-service-name"),
)(http.DefaultTransport),
}
Span Logs
As each span is marked as complete the middlewares will use the
logevent.Logger contained within the request context to emit a line like:
{"message": "span-complete", "zipkin": {"traceId": "", "id": "", "parentId": "", "name": "", "timestamp": "", "duration": "", "annotations": [{"timestamp": "", "value": ""}], "binaryAnnotations": [{"key": "", "value": ""}]}}
Contributing
License
This project is licensed under Apache 2.0. See LICENSE.txt for details.
Contributing Agreement
Atlassian requires signing a contributor's agreement before we can accept a patch. If you are an individual you can fill out the individual CLA. If you are contributing on behalf of your company then please fill out the corporate CLA.
Documentation
¶
Index ¶
- func NewMiddleware(options ...MiddlewareOption) func(http.Handler) http.Handler
- func NewTracer(logger logevent.Logger, serviceName string, hostPort string) (opentracing.Tracer, error)
- func NewTransport(options ...TransportOption) func(c http.RoundTripper) http.RoundTripper
- func SpanIDFromContext(ctx context.Context) string
- func TraceIDFromContext(ctx context.Context) string
- type Middleware
- type MiddlewareOption
- type Transport
- type TransportOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewMiddleware ¶
func NewMiddleware(options ...MiddlewareOption) func(http.Handler) http.Handler
NewMiddleware creates a middleware.
func NewTracer ¶
func NewTracer(logger logevent.Logger, serviceName string, hostPort string) (opentracing.Tracer, error)
NewTracer generates an opentracing.Tracer implementation that uses the given Logger and metadata when generating and emitting spans.
func NewTransport ¶
func NewTransport(options ...TransportOption) func(c http.RoundTripper) http.RoundTripper
NewTransport creats an http.RoundTripper wrapper that injects zipkin headers into all outgoing requests.
func SpanIDFromContext ¶
SpanIDFromContext returns the active TraceID value as a string.
func TraceIDFromContext ¶
TraceIDFromContext returns the active TraceID value as a string.
Types ¶
type Middleware ¶
type Middleware struct {
// contains filtered or unexported fields
}
Middleware adds zipkin style request tracing.
func (*Middleware) ServeHTTP ¶
func (h *Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request)
type MiddlewareOption ¶
type MiddlewareOption func(*Middleware) *Middleware
MiddlewareOption is a configuration setting for the HTTP middleware.
func MiddlewareOptionHostPort ¶
func MiddlewareOptionHostPort(hostPort string) MiddlewareOption
MiddlewareOptionHostPort sets host:port annotation used to represent the service in spans associated with the incoming request. The default value of this option is 0.0.0.0:80.
func MiddlewareOptionServiceName ¶
func MiddlewareOptionServiceName(name string) MiddlewareOption
MiddlewareOptionServiceName sets the service name annotation of the spans associated with the incoming request. The default value of this option is HTTPService.
type Transport ¶
type Transport struct {
// contains filtered or unexported fields
}
Transport adds zipkin style request tracing headers to outgoing requests.
type TransportOption ¶
TransportOption is a configuration setting for the Transport wrapper.
func TransportOptionPeerName ¶
func TransportOptionPeerName(name string) TransportOption
TransportOptionPeerName sets the name of the remote peer being called. This setting establishes a single name for the peer being used in all outgoing calls. The default value for peers is dependency.
func TransportOptionPeerNamer ¶
func TransportOptionPeerNamer(namer func(*http.Request) string) TransportOption
TransportOptionPeerNamer is similar to TransportOptionPeerName but allows for mapping an outgoing request object to a particular peer name. This can be used for cases when an HTTP transport is used to call multiple dependencies instead of a single one.
func TransportOptionSpanName ¶
func TransportOptionSpanName(name string) TransportOption
TransportOptionSpanName sets the name of the zipkin span for the outgoing request. The default value for this is OutgoingHTTPRequest.
Source Files