trace

Documentation

Overview

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.

All configuration is done via environment variables for the OpenTelemetry SDK. Please refer to https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/ for more information.

## Setting up and using the lib

Call trace.Setup to initialize the OpenTemetry SDK

```golang

traceShutdown := trace.Setup(ctx) 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

```golang

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

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

Recovering trace information and logging it

```golang

type TraceInfo struct {
	ID        string
	IsSampled bool
}

```

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

Refer to `examples/` directory for a working example.

## Propagating the trace

### API

Using in transport layer

Use the middleware to automatically handle traces from HTTP Requests.

```golang

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

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

    //(...)
	return r
}

```

The "SERVER-NAME" is optional and OpenTelemetry will default to the host's IP.

Using with go-kit endpoints

```golang

e := endpoint.Chain(
	trace.EndpointMiddleware("my-endpoint"),
	loggingmiddleware.MustNew(loggingConfig),
)(srv))

```

Using in a HTTP request

```golang request, err := http.NewRequestWithContext(

ctx,
"POST",
url,
bytes.NewReader(body),

)

if err != nil {
    return "", errors.E(op, err)
}

trace.SetTraceInRequest(request) ```

### Workers

For exporting the trace you can use `trace.ToMap` and `trace.FromMap` to export the necessary information to a `map[string]string` that could be marshaled into messages or used as message metadata if you broker supports it.

Index

• func EndpointMiddleware(name string) endpoint.Middleware
• func FromMap(ctx context.Context, m map[string]string) context.Context
• func MuxHTTPMiddleware(service string) mux.MiddlewareFunc
• func SetTraceInRequest(r *http.Request)
• func SetTraceInResponse(ctx context.Context, r http.ResponseWriter)
• func Setup(ctx context.Context) app.ShutdownFunc
• func Start(ctx context.Context, name string) (context.Context, trace.Span)
• func ToMap(ctx context.Context) map[string]string
• type TraceAttributer
• type TraceInfo
  • func GetTraceInfoFromContext(ctx context.Context) TraceInfo
  • func (t TraceInfo) MarshalZerologObject(e *zerolog.Event)

Functions

func EndpointMiddleware

func EndpointMiddleware(name string) endpoint.Middleware

EndpointMiddleware returns a new gokit endpoint.Middleware that wraps the next Endpoint with a span with the given name. The RequestID, if present, is injected as a tag and if the next Endpoint returns an error, it is registered in the span.

func FromMap

func FromMap(ctx context.Context, m map[string]string) context.Context

FromMap injects the trace context from the map into the context. This is the inverse of ToMap and could be used to extract trace context form json messages.

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. This will be set in the tag 'net.host.name'. It defaults to the ip.

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(ctx context.Context) app.ShutdownFunc

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

func Start

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

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

func ToMap

func ToMap(ctx context.Context) map[string]string

ToMap extracts the current trace from the context and put it on a map. This can be used to serialize the trace context on json messages.

Types

type TraceAttributer

type TraceAttributer interface {
	TraceAttributes() []attribute.KeyValue
}

TraceAttributer is a interface for returning OpenTelemetry span attributes. If the Request or Response (or both) implement this interface the EndpointMiddleware will set theses attributes on the span.

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")