trace

README

Trace v2

This guide will help you to setup and use the trace/v2 lib. We have a usage example in examples folder.

Configuring

This lib provides a Config struct and this section will explain how to properly configure.

Provider

1. stackdriver to export the trace to stackdriver
2. Empty string to not export the trace, but the trace will be created

Probability sample

1. 0 will not sample or export (if provider was set)
2. Float between 0 and 1 will use the number as a probability for sampling and export (if provider was set)
3. 1 will sample and export (if provider was set)

Stackdriver

Information to connect in stackdriver

Setting up and using the lib

Using in your config.go file

var config struct {
    // (...)

	Trace trace.Config
}

Creating a setup method

func setupTrace() {
	traceShutdown := trace.Setup(config.Trace)
	app.RegisterShutdownHandler(
		&app.ShutdownHandler{
			Name:     "opentelemetry_trace",
			Priority: app.ShutdownPriority(shutdownPriorityTrace),
			Handler:  traceShutdown,
			Policy:   app.ErrorPolicyAbort,
		})
}

Setting the trace up AFTER create a new App in main.go

func main() {
	app.SetupConfig(&config)

    // (...)

	if err := app.NewDefaultApp(ctx); err != nil {
		log.Ctx(ctx).Fatal().Err(err).Msg("Failed to create app")
	}

	setupTrace()

    // (...)
}

Starting a span

ctx, span := trace.Start(ctx, "SPAN-NAME")
defer span.End()

Recovering trace informations and logging it

type TraceInfo struct {
	ID        string
	IsSampled bool
}

t := trace.GetTraceInfoFromContext(ctx)
log.Ctx(ctx).Info().EmbedObject(t).Msg("Hello")

Propagating the trace

API

Using in transport layer

func MakeHTTPHandler(e endpoint.Endpoint) http.Handler {
    // (...)

	r := mux.NewRouter()
	r.Use(trace.MuxHTTPMiddleware("SERVER-NAME"))

    //(...)
	return r
}

Using in a HTTP request

request, err := http.NewRequestWithContext(
    ctx,
    "POST",
    url,
    bytes.NewReader(body),
)
if err != nil {
    return "", errors.E(op, err)
}

trace.SetTraceInRequest(request)

Using in a HTTP response

func encodeResponse(
	ctx context.Context,
	w http.ResponseWriter,
	r interface{},
) error {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	trace.SetTraceInResponse(ctx, w)
	return json.NewEncoder(w).Encode(r)
}

Workers

[WIP]

Documentation

Index

• func MuxHTTPMiddleware(service string) mux.MiddlewareFunc
• func SetTraceInRequest(r *http.Request)
• func SetTraceInResponse(ctx context.Context, r http.ResponseWriter)
• func Setup(c Config) app.ShutdownFunc
• type Config
• type Span
  • func Start(ctx context.Context, name string) (context.Context, Span)
  • func (s Span) End()
• type TraceInfo
  • func GetTraceInfoFromContext(ctx context.Context) TraceInfo
  • func (t TraceInfo) MarshalZerologObject(e *zerolog.Event)

Functions

func MuxHTTPMiddleware

func MuxHTTPMiddleware(service string) mux.MiddlewareFunc

MuxHTTPMiddleware sets up a handler to start tracing the incoming requests. The service parameter should describe the name of the (virtual) server handling the request.

func SetTraceInRequest

func SetTraceInRequest(r *http.Request)

SetTraceInRequest will put the trace in @r headers

func SetTraceInResponse

func SetTraceInResponse(ctx context.Context, r http.ResponseWriter)

SetTraceInResponse will put the trace in @r headers

func Setup

func Setup(c Config) app.ShutdownFunc

Setup use Config to setup an trace exporter and returns a shutdown handler

Types

type Config

type Config struct {
	Exporter          string  `default:""`
	ProbabilitySample float64 `default:"0"`
	Stackdriver       struct {
		ProjectID string
	}
}

Config represents all trace's configuration

type Span

type Span struct {
	// contains filtered or unexported fields
}

Span is the individual component of a trace. It represents a single named and timed operation of a workflow that is traced

func Start

func Start(ctx context.Context, name string) (context.Context, Span)

Start creates a new span. If other spans were created using @ctx, this method will bind them all

func (Span) End

func (s Span) End()

End stops an span sampling

type TraceInfo

type TraceInfo struct {
	ID        string
	IsSampled bool
}

TraceInfo carries the trace informations

func GetTraceInfoFromContext

func GetTraceInfoFromContext(ctx context.Context) TraceInfo

GetTraceInfoFromContext returns a TraceInfo from the context @ctx or logs if there is no TraceInfo in context

func (TraceInfo) MarshalZerologObject

func (t TraceInfo) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements the zerolog marshaler so it can be logged using: log.With().EmbededObject(t).Msg("Some message")