oteltracing

README

Oteltracing

[!NOTE] This repository has been transferred from github.com/tigerwill90/otelfox to github.com/fox-toolkit/oteltracing. Existing users should update their imports and go.mod accordingly.

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

Disclaimer

Oteltracing'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/fox-toolkit/oteltracing

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 (
	"errors"
	"fmt"
	"log"
	"net/http"

	"github.com/fox-toolkit/fox"
	"github.com/fox-toolkit/oteltracing"
)

func main() {
	f := fox.MustRouter(
		fox.WithMiddleware(oteltracing.Middleware("fox")),
	)

	f.MustAdd(fox.MethodGet, "/hello/{name}", func(c *fox.Context) {
		_ = c.String(http.StatusOK, fmt.Sprintf("hello %s\n", c.Param("name")))
	})

	if err := http.ListenAndServe(":8080", f); err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatalln(err)
	}
}

Documentation

Index

• Constants
• Variables
• func Middleware(service string, opts ...Option) fox.MiddlewareFunc
• type Filter
• type MetricAttributesFunc
• type Option
  • func WithClientIPResolver(resolver fox.ClientIPResolver) Option
  • func WithFilter(f ...Filter) Option
  • func WithMeterProvider(provider metric.MeterProvider) Option
  • func WithMetricsAttributes(fn MetricAttributesFunc) Option
  • func WithPropagators(propagators propagation.TextMapPropagator) Option
  • func WithSpanNameFormatter(fn SpanNameFormatter) Option
  • func WithSpanStartOptions(opts ...trace.SpanStartOption) Option
  • func WithTextMapCarrier(fn func(r *http.Request) propagation.TextMapCarrier) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
• type SpanNameFormatter

Constants

const (
	// ScopeName is the instrumentation scope name.
	ScopeName = "github.com/fox-toolkit/oteltracing"
)

const Version = "0.65.0"

Variables

var (
	// DefaultClientIPResolver attempts to resolve client IP addresses in the following order:
	// 1. Leftmost non-private IP in X-Forwarded-For header
	// 2. Leftmost non-private IP in Forwarded header
	// 3. X-Real-IP header
	// 4. CF-Connecting-IP header
	// 5. True-Client-IP header
	// 6. Fastly-Client-IP header
	// 7. X-Azure-ClientIP header
	// 8. X-Azure-SocketIP header
	// 9. X-Appengine-Remote-Addr header
	// 10. Fly-Client-IP header
	// 11. RemoteAddr from the request
	//
	// The DefaultClientIPResolver uses resolvers (particularly Leftmost in X-Forwarded-For/Forwarded headers,
	// and X-Azure-ClientIP) that are trivially spoofable by clients. For security-critical applications
	// where IP addresses must be trusted, consider using a Rightmost resolver or implementing
	// your own strategy tailored to your infrastructure.
	DefaultClientIPResolver = clientip.DefaultResolver
)

Functions

func Middleware

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

Middleware returns middleware that will trace incoming requests. The service parameter should describe the name of the (virtual) server handling the request.

Types

type Filter

type Filter func(c *fox.Context) bool

Filter is a predicate used to determine whether a given http.request should be traced. A Filter must return true if the request should be traced.

type MetricAttributesFunc

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

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

type Option

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

func WithClientIPResolver

func WithClientIPResolver(resolver fox.ClientIPResolver) Option

WithClientIPResolver sets a custom resolver to derive the client IP address. This is for advanced use cases. Most users should configure the resolver with Fox's router option using fox.WithClientIPResolver instead.

Priority order for resolvers: 1. Resolver set with this option (highest priority) 2. Resolver configured at the route level in Fox 3. Resolver configured globally in Fox 4. If no resolver is configured anywhere, DefaultClientIPResolver is used as fallback.

Only use this option when you need different IP resolution logic specifically for OpenTelemetry attributes than what's used by the rest of your application.

func WithFilter

func WithFilter(f ...Filter) Option

WithFilter adds a filter to the list of filters used by the handler. If any filter indicates to exclude a request then the request will not be traced. All filters must allow a request to be traced for a Span to be created. If no filters are provided then all requests are traced. Filters will be invoked for each processed request, it is advised to make them simple and fast.

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider specifies a meter provider to use for tracing http request. If none is specified, the global meter provider is used.

func WithMetricsAttributes

func WithMetricsAttributes(fn MetricAttributesFunc) Option

WithMetricsAttributes specifies a function for generating metric attributes. The function will be invoked for each request, and its returned attributes will be added to the metric record.

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 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 WithSpanStartOptions

func WithSpanStartOptions(opts ...trace.SpanStartOption) Option

WithSpanStartOptions configures an additional set of trace.SpanStartOptions, which are applied to each new span.

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 tracing http request. If none is specified, the global tracer provider is used.

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.