opentelemetry

README

Azugo OpenTelemetry

Azugo framework OpenTelemetry support.

Features

• Tracing support for router handlers, HTTP client and cache.

Usage

	t, err := opentelemetry.Use(app, config)
	if err != nil {
		panic(err)
	}

	app.AddTask(t)

If tracing context needs to be used to get current span from *azugo.Context use special helper to access it:

span := trace.SpanFromContext(opentelemetry.FromContext(ctx))

Environment variables used by the Azugo framework

Special

• OTEL_SDK_DISABLED - Disable tracing.
• OTEL_EXPORTER_OTLP_INSECURE_SKIP_VERIFY - Insecure skip verify HTTPS certificates.
• OTEL_RESOURCE_ATTRIBUTES - Set of custom resource attributes for OpenTelemetry. This is a comma-separated list of key-value pairs, e.g. deployment.environment=local.
• ELASTIC_APM_SECRET_TOKEN - Support Elastic APM server authentification secret token.
• ELASTIC_APM_SECRET_TOKEN_FILE - Read Elastic APM secret token from specified file.

Default

• OTEL_EXPORTER_OTLP_ENDPOINT - OpenTelemetry server endpoint address. If endpoint is not provided tracing will be disabled.
• OTEL_EXPORTER_OTLP_PROTOCOL - OTLP transport protocol (defaults to http/protobuf, allowed values are http/protobuf and grpc). For grpc the endpoint scheme selects channel security: http:// is insecure, https:// uses TLS.
• OTEL_SERVICE_NAME - Override default service name defined in Azugo app.

For other configuration environment variables see OpenTelemetry documentation.

Documentation

Overview

Package opentelemetry provides OpenTelemetry integration for Azugo applications.

Index

• Constants
• func FromContext(ctx context.Context) context.Context
• func Recording(ctx context.Context) bool
• func Use(app *azugo.App, config *Configuration, opts ...Option) (core.Tasker, error)
• func Version() string
• type Configuration
  • func (c *Configuration) Bind(prefix string, v *viper.Viper)
  • func (c *Configuration) IsDisabled() bool
  • func (c *Configuration) Validate(valid *validation.Validate) error
• type Filter
• type InstrumentationRecorderFunc
• type InstrumentationSpanNameFormatter
• type Option
  • func InstrumentationRecorder(name string, recorder InstrumentationRecorderFunc, ops ...string) Option
  • func MeterProvider(provider metric.MeterProvider) Option
  • func TextMapPropagator(propagators propagation.TextMapPropagator) Option
  • func TracerProvider(provider trace.TracerProvider) Option
• type PublicEndpoint
• type PublicEndpointFilter
• type RouteSpanNameFormatter
• type Span
  • func StartSpan(ctx context.Context, tracer trace.Tracer, name string, ...) (context.Context, Span)
  • func (s Span) End(...trace.SpanEndOption)

Constants

const (
	ProtocolGRPC         = "grpc"
	ProtocolHTTPProtobuf = "http/protobuf"
)

OTLP transport protocol values as defined by OTEL_EXPORTER_OTLP_PROTOCOL.

const (
	// ScopeName is the instrumentation scope name.
	ScopeName = "azugo.io/opentelemetry"
)

Functions

func FromContext

func FromContext(ctx context.Context) context.Context

FromContext returns a context carrying the active span for the request, suitable as the parent for new spans.

func Recording

func Recording(ctx context.Context) bool

Recording reports whether a span started for ctx would be part of active tracing, and therefore eventually exported. Use it to guard custom instrumentation so it does not emit orphan spans for untraced requests:

if opentelemetry.Recording(ctx) {
	ctx, span := tracer.Start(ctx, "my-operation")
	defer span.End()
	// ...
}

Outside of a request context it always returns true.

func Use

func Use(app *azugo.App, config *Configuration, opts ...Option) (core.Tasker, error)

Use OpenTelemetry for tracing in Azugo application.

func Version

func Version() string

Version is the current release version of the azugo OpenTracing support.

Types

type Configuration

type Configuration struct {
	Disabled              bool     `mapstructure:"disabled"`
	Endpoint              string   `mapstructure:"endpoint"`
	Protocol              string   `mapstructure:"protocol" validate:"omitempty,oneof=grpc http/protobuf"`
	InsecureSkipVerify    bool     `mapstructure:"insecure_skip_verify"`
	ServiceName           string   `mapstructure:"service_name"`
	ElasticAPMSecretToken string   `mapstructure:"elastic_apm_secret_token"`
	ResourceAttributes    []string `mapstructure:"resource_attributes"`
}

Configuration section for OpenTracing.

func (*Configuration) Bind

func (c *Configuration) Bind(prefix string, v *viper.Viper)

Bind OpenTracing configuration section.

func (*Configuration) IsDisabled

func (c *Configuration) IsDisabled() bool

IsDisabled returns true if the tracing is disabled.

func (*Configuration) Validate

func (c *Configuration) Validate(valid *validation.Validate) error

Validate OpenTracing configuration section.

type Filter

type Filter func(ctx *azugo.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.

Multiple filters can be proviaded and are applied in the order they are added. 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.

type InstrumentationRecorderFunc

type InstrumentationRecorderFunc func(ctx context.Context, tracer trace.Tracer, propagator propagation.TextMapPropagator, spfmt InstrumentationSpanNameFormatter, op string, args ...any) (func(err error), bool)

InstrumentationRecorderFunc specifies a function to use for handling instrumentation events. The function should return a function that can be used to finish the span and a boolean indicating if specific instrumentation has been recorded.

type InstrumentationSpanNameFormatter

type InstrumentationSpanNameFormatter func(ctx context.Context, op string, args ...any) string

InstrumentationSpanNameFormatter specifies a function to use for generating a custom span name. By default, the span name is formatted based on the operation type and the arguments. If the provided function returns an empty string, the default span name will be used.

type Option

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

Option specifies instrumentation configuration options.

func InstrumentationRecorder

func InstrumentationRecorder(name string, recorder InstrumentationRecorderFunc, ops ...string) Option

InstrumentationRecorder specifies a function to use for handling instrumentation events for specific instrumentation operations. Multiple recorders can be provided and are applied in the order they are added.

func MeterProvider

func MeterProvider(provider metric.MeterProvider) Option

MeterProvider specifies a meter provider to use for creating metric instruments. If none is specified, the global provider is used.

func TextMapPropagator

func TextMapPropagator(propagators propagation.TextMapPropagator) Option

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

func TracerProvider

func TracerProvider(provider trace.TracerProvider) Option

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

type PublicEndpoint

type PublicEndpoint bool

PublicEndpoint configures the Handler to link the span with an incoming span context. If this option is not provided, then the association is a child association instead of a link.

type PublicEndpointFilter

type PublicEndpointFilter func(ctx *azugo.Context) bool

PublicEndpointFilter runs with every request, and allows conditionnally configuring the Handler to link the span with an incoming span context. If this option is not provided or returns false, then the association is a child association instead of a link. Note: PublicEndpoint takes precedence over PublicEndpointFilter.

type RouteSpanNameFormatter

type RouteSpanNameFormatter func(ctx *azugo.Context, routeName string) string

RouteSpanNameFormatter specifies a function to use for generating a custom span name. By default, the route name (path template or regexp) is used. The route name is provided so you can use it in the span name without needing to duplicate the logic for extracting it from the request.

type Span

type Span struct {
	trace.Span
	// contains filtered or unexported fields
}

Span wraps an OpenTelemetry span whose End is deferred to the end of the request. It is dropped together with the request if the request opts out of tracing.

Create one with StartSpan.

func StartSpan

func StartSpan(ctx context.Context, tracer trace.Tracer, name string, opts ...trace.SpanStartOption) (context.Context, Span)

StartSpan starts a span with tracer as a child of the active request span, and returns it wrapped so that End is deferred. Use it from custom instrumentation so the spans you create are dropped together with the request just like the built-in ones:

ctx, span := opentelemetry.StartSpan(ctx, otel.Tracer("myapp"), "work")
defer span.End()

func (Span) End

func (s Span) End(...trace.SpanEndOption)

End completes the Span. The Span is considered complete and ready to be delivered through the rest of the telemetry pipeline after this method is called. Therefore, updates to the Span are not allowed after this method has been called.