traces

README

Observability Wrappers: OTEL Tracing

This repository contains a middleware for gin and gonic for services that are need tracing using the Open Telemetry framework for Go.

Installation

go get -u github.com/twistingmercury/monitoring

Collectors and Agents

This has been tested using the OTEL Collector and the Datadog Agent, with the destination being Datadog. Both agents were tested using both http and grpc protocols.

Trace and Log Correlation

This middleware pairs nicely with the Monitoring: Logging. When used together, the logs and traces will be correlated in by adding the trace id to the log entry.

Initialization

trace.SpanExporter

You will need to provide a trace.SpanExporter to the middleware. This can be any type that implements the trace.SpanExporter interface.

func main() {
	// create a exporter...
	exporter, err := stdouttrace.New(stdouttrace.WithPrettyPrint())
	if err != nil {
		panic(err)
	}

	// any trace.SpanExporter can be used here.
	shutdown, err := traces.Initialize(exporter, "0.0.1", "trace-example", time.Now().String(), "A12BC3", "localhost")
	if err != nil {
		panic(err)
	}
	defer func() {
		_ = shutdown(context.Background())
	}()

	gin.SetMode(gin.DebugMode)
	r := gin.New()
	r.Use(gin.Recovery(), traces.GinTracingMiddleware())
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(200, gin.H{"message": "pong"})
	})
	if err := r.Run(":8080"); err != nil {
		panic(err)
	}
}

A working example is here: examples.

Documentation

Overview

Package traces provides a wrapper around OpenTelemetry to add standard fields to the span.

Index

• func End(span trace.Span, status otelCodes.Code, err error)
• func EndError(span trace.Span, err error)
• func EndOK(span trace.Span)
• func GinTracingMiddleware() gin.HandlerFunc
• func Initialize(exporter sdktrace.SpanExporter, ...) (shutdown func(context.Context) error, err error)
• func NewHTTPExporter(ctx context.Context, url string, opts ...otlptracehttp.Option) (exporter sdktrace.SpanExporter, err error)
• func NewNoopExporter() sdktrace.SpanExporter
• func NewSpan(traceCtx context.Context, spanName string, kind trace.SpanKind, ...) (spanCtx context.Context, span trace.Span, err error)
• func Start(ctx context.Context, spanName string, kind trace.SpanKind, ...) (spanCtx context.Context, span trace.Span, err error)

Functions

func End

func End(span trace.Span, status otelCodes.Code, err error)

End ends the span with the supplied status and error. This is merely a convenience function that wraps the the trace.Span SetStatus and End functions of the span. in: span: The span. in: status: The status code. 0 is "unset", 1 is "error", and 2 is "ok". in: err: The error. Can be nil. If the status is "error", the error the error is used as the description for the status.

func EndError

func EndError(span trace.Span, err error)

EndError ends the span with a status of "error".

Deprecated: use traces.End(trace.Span, otel.Codes, string) instead. This function will be removed in v2.0.0.

func EndOK

func EndOK(span trace.Span)

EndOK ends the span with a status of "ok".

Deprecated: use traces.End(trace.Span, otel.Codes, string) instead. This function will be removed in v2.0.0.

func GinTracingMiddleware

func GinTracingMiddleware() gin.HandlerFunc

func Initialize

func Initialize(exporter sdktrace.SpanExporter, ver, apiName, buildDate, commitHash, env string) (shutdown func(context.Context) error, err error)

Initialize initializes the tracing system.

func NewHTTPExporter

func NewHTTPExporter(ctx context.Context, url string, opts ...otlptracehttp.Option) (exporter sdktrace.SpanExporter, err error)

NewHTTPExporter creates a new HTTP exporter.

func NewNoopExporter

func NewNoopExporter() sdktrace.SpanExporter

func NewSpan

func NewSpan(traceCtx context.Context, spanName string, kind trace.SpanKind, attributes ...attribute.KeyValue) (spanCtx context.Context, span trace.Span, err error)

NewSpan starts a new span that is a child of the existing span within the supplied context. in: ctx: The context. If nil, an error is returned. in: spanName: The name of the span. in: kind: The arg kind is used to set the span kind. The constant trace.SpanKind is defined here: https://pkg.go.dev/go.opentelemetry.io/otel/trace@v1.15. in: attributes: The attributes to add to the span. out: ctx: The context with the span added. out: span: The span. out: err: The error if the context is nil.

Deprecated: Use traces.Start(context.Context, string, trace.SpanKind, ...attribute.KeyValue) instead. This function will be removed in v2.0.0.

func Start

func Start(ctx context.Context, spanName string, kind trace.SpanKind, attributes ...attribute.KeyValue) (spanCtx context.Context, span trace.Span, err error)

Start starts a new span that has no parent. This is merely a convenience function that wraps the Start function of the tracer. in: ctx: The context. If nil, an error is returned. in: spanName: The name of the span. in: kind: The arg kind is used to set the span kind. The constant trace.SpanKind is defined here: https://pkg.go.dev/go.opentelemetry.io/otel/trace@v1.15. in: attributes: The attributes to add to the span. out: ctx: The context with the span added. out: span: The span. out: err: The error if the context is nil.