traces

README

OTEL Observability Wrappers: 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/observability-traces

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 OTEL Observability Wrappers: 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. There is a built in helper for setting up an HTTP exporter via traces.NewHttpExporter.

package main

import (
	"context"
	"github.com/gin-gonic/gin"
	"github.com/twistingmercury/monitoring-traces"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	"go.opentelemetry.io/otel/trace"
	"log/slog"
	"os"
	"time"
)

const (
	serviceName  = "my-service" // build info will be set during the build process
	buildDate    = time.Now().String()
	buildVersion = "v0.0.1"
	buildCommit  = "f1g4b5c6"
)

func main() {
	opt := &slog.HandlerOptions{
		AddSource: false,
		Level:     slog.LevelDebug,
	}
	logger := slog.New(slog.NewJSONHandler(os.Stdout, opt))
	slog.SetDefault(logger)

	// in PRODUCTION, you most likely should use a secure connection
	exporter, err = traces.NewHTTPExporter(context.Background(), "localhost:4318", otlptracehttp.WithInsecure())
	if err != nil {
		slog.Error("failed to initialize exporter: %v", err)
		os.Exit(1)
	}

	// any trace.SpanExporter can be used here
	shutdown, err := traces.Initialize(exporter, buildVersion, serviceName, buildDate, buildCommit, "local")
	if err != nil {
		slog.Error("failed to initialize exporter: %v", err)
		os.Exit(2)
	}
	defer shutdown(context.Background())

	gin.SetMode(gin.DebugMode)
	r := gin.New()
	r.Use(traces.GinTracingMiddleware())
	r.GET("/", func(c *gin.Context) {
		c.JSON(200, gin.H{"message": "hello world"})
	})
	if err := r.Run(":8080"); err != nil {
		slog.Error("failed to run gin server: %v", err)
		os.Exit(3)
	}
}

Exporting via gRPC

If exporting via gRPC is desired, you can create a gRPC exporter using the otlptracegrpc.New func:

package main

import (
    // other imports ...
    "github.com/twistingmercury/monitoring-traces"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
 )
 
//
//...
//

func main(){
    // in PRODUCTION, you should handle errors appropriately, and depending on your use case, you should use 
    // a secure connection in production.
    
    grpcConn, _ := grpc.Dial("localhost:4317", grpc.WithTransportCredentials(insecure.NewCredentials()))
    grpcExporter, _ := otlptracegrpc.New(ctx, otlptracegrpc.WithGRPCConn(grpcConn))
    shutdown, _ := traces.Initialize(grpcExporter, buildVersion, serviceName, buildDate, buildCommit, "local")
    defer shutdown(context.Background())
    
    //
    // do more stuff...
    //
}

Documentation

Overview

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

Index

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

Functions

func EndError

func EndError(span trace.Span, err error)

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

func EndOK

func EndOK(span trace.Span)

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

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 with using 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.