opengintracing

README

tracing

trace requests using opentracing specification, Download:

go get -u github.com/gin-contrib/opengintracing

See opentracing/opentracing-go for more information.

Usage

For example you have architecture like this

To start requests tracing you have to:

• On "API Gateway": start span, inject headers and pass it to services

package main
import (
    ...
    "github.com/gin-gonic/gin"
    "github.com/gin-contrib/opengintracing"
    "github.com/opentracing/opentracing-go"
    ...
)

var trace = /* setup tracer */

func main() {
    ...
    app := gin.Default()

    app.POST("/service1",
        opengintracing.NewSpan(trace, "forward to service 1"),
        opengintracing.InjectToHeaders(trace, true),
        service1handler)
    app.POST("/service2",
        opengintracing.NewSpan(trace, "forward to service 2"),
        opengintracing.InjectToHeaders(trace, true),
        service2handler)
    ...
}

• On "Service 1", "Service 2" start span inherited from "API Gateway"`s span

package main
import (
    ...
    "github.com/gin-gonic/gin"
    "github.com/gin-contrib/opengintracing"
    "github.com/opentracing/opentracing-go"
    ...
)

var trace = /* setup tracer */

func main() {
    ...
    refFunc := opentracing.FollowsFrom
    app := gin.Default()

    app.POST("",
        opengintracing.SpanFromHeaders(trace, "operation", refFunc, true),
        // don`t forget to inject if you want continue tracing in other service
        opengintracing.InjectToHeaders(trace, true),
        handler)
    ...
}

Also don`t forget to forward headers from "Service 1" to "Service 3"

• On "Service 3" injecting to headers is not required

package main
import (
    ...
    "github.com/gin-gonic/gin"
    "github.com/gin-contrib/opengintracing"
    "github.com/opentracing/opentracing-go"
    ...
)

var trace = /* setup tracer */

func main() {
    ...
    refFunc := opentracing.ChildOf
    app := gin.Default()

    app.POST("",
        opengintracing.SpanFromHeaders(trace, "operation", refFunc, true),
        handler)
    ...
}

TODO

• add code sample
• maybe add sample with SpanFromContext
• add buildable example (needed simple logging tracer)

Documentation

Overview

Package opengintracing provides requests tracing functional using opentracing specification.

See https://github.com/opentracing/opentracing-go for more information

Index

• Variables
• func GetSpan(ctx *gin.Context) (span opentracing.Span, exists bool)
• func InjectToHeaders(tracer opentracing.Tracer, abortOnErrors bool) gin.HandlerFunc
• func MustGetSpan(ctx *gin.Context) opentracing.Span
• func NewSpan(tracer opentracing.Tracer, operationName string, ...) gin.HandlerFunc
• func SpanFromContext(tracer opentracing.Tracer, operationName string, abortOnErrors bool, ...) gin.HandlerFunc
• func SpanFromHeaders(tracer opentracing.Tracer, operationName string, psr ParentSpanReferenceFunc, ...) gin.HandlerFunc
• func SpanFromHeadersHTTPFmt(tracer opentracing.Tracer, operationName string, psr ParentSpanReferenceFunc, ...) gin.HandlerFunc
• type ParentSpanReferenceFunc

Variables

var (
	ErrSpanNotFound = errors.New("span was not found in context")
)

Errors which may occur at operation time.

Functions

func GetSpan

func GetSpan(ctx *gin.Context) (span opentracing.Span, exists bool)

GetSpan extracts span from context.

func InjectToHeaders

func InjectToHeaders(tracer opentracing.Tracer, abortOnErrors bool) gin.HandlerFunc

InjectToHeaders injects span meta-information to request headers.

It may be useful when you want to trace chained request (client->service 1->service 2). In this case you have to save request headers (ctx.Request.Header) and pass it to next level request.

Behaviour on errors determined by abortOnErrors option. If it set to true request handling will be aborted with error.

func MustGetSpan

func MustGetSpan(ctx *gin.Context) opentracing.Span

MustGetSpan extracts span from context. It panics if span was not set.

func NewSpan

func NewSpan(tracer opentracing.Tracer, operationName string, opts ...opentracing.StartSpanOption) gin.HandlerFunc

NewSpan returns gin.HandlerFunc (middleware) that starts a new span and injects it to request context.

It calls ctx.Next() to measure execution time of all following handlers.

func SpanFromContext

func SpanFromContext(tracer opentracing.Tracer, operationName string, abortOnErrors bool,
	advancedOpts ...opentracing.StartSpanOption,
) gin.HandlerFunc

SpanFromContext returns gin.HandlerFunc (middleware) that extracts parent span from request context and starts a new span as child of parent span.

It calls ctx.Next() to measure execution time of all following handlers.

Behaviour on errors determined by abortOnErrors option. If it set to true request handling will be aborted with error.

func SpanFromHeaders

func SpanFromHeaders(tracer opentracing.Tracer, operationName string, psr ParentSpanReferenceFunc,
	abortOnErrors bool, advancedOpts ...opentracing.StartSpanOption,
) gin.HandlerFunc

SpanFromHeaders returns gin.HandlerFunc (middleware) that extracts parent span data from HTTP headers in TextMap format and starts a new span referenced to parent with ParentSpanReferenceFunc.

It calls ctx.Next() to measure execution time of all following handlers.

Behaviour on errors determined by abortOnErrors option. If it set to true request handling will be aborted with error.

func SpanFromHeadersHTTPFmt

func SpanFromHeadersHTTPFmt(tracer opentracing.Tracer, operationName string, psr ParentSpanReferenceFunc,
	abortOnErrors bool, advancedOpts ...opentracing.StartSpanOption,
) gin.HandlerFunc

SpanFromHeadersHTTPFmt returns gin.HandlerFunc (middleware) that extracts parent span data from HTTP headers in HTTPHeaders format and starts a new span referenced to parent with ParentSpanReferenceFunc.

It calls ctx.Next() to measure execution time of all following handlers.

Behaviour on errors determined by abortOnErrors option. If it set to true request handling will be aborted with error.

Types

type ParentSpanReferenceFunc

type ParentSpanReferenceFunc func(opentracing.SpanContext) opentracing.StartSpanOption

ParentSpanReferenceFunc determines how to reference parent span

See opentracing.SpanReferenceType