otelfox

README

Otelfox

Otelfox is a middleware for Fox that provides distributed tracing using OpenTelemetry.

Disclaimer

Otelfox's API is linked to Fox router, and it will only reach v1 when the router is stabilized. During the pre-v1 phase, breaking changes may occur and will be documented in the release notes.

Getting started

Installation

go get -u github.com/tigerwill90/otelfox

Features

• Automatically creates spans for incoming HTTP requests
• Extracts and propagates trace context from incoming requests
• Annotates spans with HTTP-specific attributes, such as method, route, and status code

Usage

package main

import (
	"github.com/tigerwill90/fox"
	"github.com/tigerwill90/otelfox"
	"log"
	"net/http"
)

func main() {
	r := fox.New(
		fox.WithMiddleware(otelfox.Middleware("fox")),
	)

	r.MustHandle(http.MethodGet, "/hello/{name}", func(c fox.Context) {
		_ = c.String(http.StatusOK, "hello %s\n", c.Param("name"))
	})

	log.Fatalln(http.ListenAndServe(":8080", r))
}

Documentation

Index

• func Middleware(service string, opts ...Option) fox.MiddlewareFunc
• func SemVersion() string
• func Version() string
• type Filter
• type Option
  • func WithFilter(f ...Filter) Option
  • func WithPropagators(propagators propagation.TextMapPropagator) Option
  • func WithSpanAttributes(fn SpanAttributesFunc) Option
  • func WithSpanNameFormatter(fn SpanNameFormatter) Option
  • func WithTextMapCarrier(fn func(r *http.Request) propagation.TextMapCarrier) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
• type SpanAttributesFunc
• type SpanNameFormatter
• type Tracer
  • func New(service string, opts ...Option) *Tracer
  • func (t *Tracer) Trace(next fox.HandlerFunc) fox.HandlerFunc

Functions

func Middleware

func Middleware(service string, opts ...Option) fox.MiddlewareFunc

Middleware is a convenience function that creates a new Tracer middleware instance for the specified service and returns the Trace middleware function. Options can be provided to configure the tracer.

func SemVersion

func SemVersion() string

func Version

func Version() string

Types

type Filter

type Filter func(c fox.Context) bool

Filter is a function that determines whether a given HTTP request should be traced. It returns true to indicate the request should not be traced.

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithFilter

func WithFilter(f ...Filter) Option

WithFilter appends the provided filters to the middleware's filter list. A filter returning true will exclude the request from being traced. If no filters are provided, all requests will be traced. Keep in mind that filters are invoked for each request, so they should be simple and efficient.

func WithPropagators

func WithPropagators(propagators propagation.TextMapPropagator) Option

WithPropagators specifies propagators to use for extracting information from the HTTP requests. If none are specified, global ones will be used.

func WithSpanAttributes

func WithSpanAttributes(fn SpanAttributesFunc) Option

WithSpanAttributes specifies a function for generating span attributes. The function will be invoked for each request, and its return attributes will be added to the span. For example, you can use this option to add the http.target attribute to the span.

func WithSpanNameFormatter

func WithSpanNameFormatter(fn SpanNameFormatter) Option

WithSpanNameFormatter takes a function that will be called on every request and the returned string will become the Span Name.

func WithTextMapCarrier

func WithTextMapCarrier(fn func(r *http.Request) propagation.TextMapCarrier) Option

WithTextMapCarrier specify a carrier to use for extracting information from http request. If none is specified, propagation.HeaderCarrier is used.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider specifies a tracer provider to use for creating a tracer. If none is specified, the global provider is used.

type SpanAttributesFunc

type SpanAttributesFunc func(c fox.Context) []attribute.KeyValue

SpanAttributesFunc is a function type that can be used to dynamically generate span attributes for a given HTTP request. It is used in conjunction with the WithSpanAttributes middleware option.

type SpanNameFormatter

type SpanNameFormatter func(c fox.Context) string

SpanNameFormatter is a function that formats the span name given the HTTP request. This allows for dynamic naming of spans based on attributes of the request.

type Tracer

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

Tracer is a Fox middleware that traces HTTP requests using OpenTelemetry.

func New

func New(service string, opts ...Option) *Tracer

New creates a new Tracer middleware for the given service. Options can be provided to configure the tracer.

func (*Tracer) Trace

func (t *Tracer) Trace(next fox.HandlerFunc) fox.HandlerFunc

Trace is a middleware function that wraps the provided HandlerFunc with tracing capabilities. It captures and records HTTP request information using OpenTelemetry.