tracing

README

Tracing

There are two main folders in this directory:

• cloudtrace
• otel

These are for tracing providers, though Otel is probably all you'll ever need.

Documentation

Overview

Package tracing provides distributed tracing utilities. No registration helpers are needed here; use observability/tracing/config.RegisterTracerProvider instead.

Index

• Variables
• func AttachErrorToSpan(span trace.Span, description string, err error)
• func AttachQueryFilterToSpan(span trace.Span, filter *filtering.QueryFilter)
• func AttachRequestToSpan(span trace.Span, req *http.Request)
• func AttachResponseToSpan(span trace.Span, res *http.Response)
• func AttachSessionContextDataToSpan(span trace.Span, sessionCtxData SessionContextDataForTracing)
• func AttachToSpan[T any](span trace.Span, attachmentKey string, x T)
• func AttachUserAgentDataToSpan(span trace.Span, req *http.Request)
• func FormatSpan(operation string, req *http.Request) string
• func GetCallerName() string
• func NewInstrumentedSQLTracer(tracerProvider Provider, name string) instrumentedsql.Tracer
• func SetGlobalErrorHandler(logger logging.Logger) bool
• func StartCustomSpan(ctx context.Context, name string) (context.Context, trace.Span)
• func StartSpan(ctx context.Context) (context.Context, trace.Span)
• type ErrorHandler
  • func NewErrorHandler(logger logging.Logger) *ErrorHandler
  • func (h *ErrorHandler) Handle(err error)
• type Provider
  • func EnsureTracerProvider(tracerProvider Provider) Provider
• type ServicePermissionChecker
• type SessionContextDataForTracing
• type Span
• type Tracer
  • func NewNamedTracer(tracerProvider Provider, name string) Tracer
  • func NewTracerForTest(name string) Tracer

Variables

var (
	PackagePrefix = "github.com/primandproper/platform-go/v12/"
)

Functions

func AttachErrorToSpan

func AttachErrorToSpan(span trace.Span, description string, err error)

AttachErrorToSpan attaches a given error to a span.

Like every other attacher here it tolerates a nil or non-recording span. It was the one that did not, which made it the only one whose contract changed depending on whether the caller had a span — and error paths are exactly where callers are least likely to have checked.

func AttachQueryFilterToSpan

func AttachQueryFilterToSpan(span trace.Span, filter *filtering.QueryFilter)

AttachQueryFilterToSpan attaches a given query filter to a span.

func AttachRequestToSpan

func AttachRequestToSpan(span trace.Span, req *http.Request)

AttachRequestToSpan attaches a given HTTP request to a span.

func AttachResponseToSpan

func AttachResponseToSpan(span trace.Span, res *http.Response)

AttachResponseToSpan attaches a given *http.Response to a span.

func AttachSessionContextDataToSpan

func AttachSessionContextDataToSpan(span trace.Span, sessionCtxData SessionContextDataForTracing)

AttachSessionContextDataToSpan provides a consistent way to attach a SessionContextData object to a span.

func AttachToSpan

func AttachToSpan[T any](span trace.Span, attachmentKey string, x T)

func AttachUserAgentDataToSpan

func AttachUserAgentDataToSpan(span trace.Span, req *http.Request)

AttachUserAgentDataToSpan attaches a request's user-agent details to a span.

func FormatSpan

func FormatSpan(operation string, req *http.Request) string

FormatSpan formats a span.

func GetCallerName

func GetCallerName() string

GetCallerName returns the name of the function that opened the current span, with the platform package prefix trimmed. The single-element stack array keeps runtime.Callers allocation-free, and runtime.FuncForPC avoids the allocating runtime.CallersFrames iterator. Results are memoized by program counter so the allocating runtime.Func.Name call happens once per call site.

func NewInstrumentedSQLTracer

func NewInstrumentedSQLTracer(tracerProvider Provider, name string) instrumentedsql.Tracer

NewInstrumentedSQLTracer wraps a Tracer for instrumentedsql.

func SetGlobalErrorHandler

func SetGlobalErrorHandler(logger logging.Logger) bool

SetGlobalErrorHandler installs a logger-backed handler as OpenTelemetry's process-global error handler, and reports whether it did.

This package used to do it in init(), which made importing anything under observability/tracing enough to reassign a process-global — hard-wired to the slog backend no matter which backend the application had configured, and clobbering any handler the application had installed itself. The choice to own that global belongs to whoever owns main, so it is a call now rather than a link-time side effect.

Passing a nil logger is a no-op returning false, rather than quietly installing a handler that discards everything OTel reports.

func StartCustomSpan

func StartCustomSpan(ctx context.Context, name string) (context.Context, trace.Span)

StartCustomSpan starts an anonymous custom span.

func StartSpan

func StartSpan(ctx context.Context) (context.Context, trace.Span)

StartSpan starts an anonymous span. Avoid using PackagePrefix and use an embedded tracer where possible.

Types

type ErrorHandler

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

ErrorHandler reports OpenTelemetry's own internal errors — a dropped batch, an exporter that cannot reach its collector — through a logging.Logger.

func NewErrorHandler

func NewErrorHandler(logger logging.Logger) *ErrorHandler

NewErrorHandler builds an ErrorHandler reporting through the given logger. An absent logger resolves to the noop, so the handler is safe to install regardless.

func (*ErrorHandler) Handle

func (h *ErrorHandler) Handle(err error)

Handle satisfies otel.ErrorHandler.

type Provider

type Provider interface {
	trace.TracerProvider
	ForceFlush(context.Context) error
	Shutdown(context.Context) error
}

Provider is trace.TracerProvider plus the two lifecycle methods a process needs at exit.

ForceFlush drains what is buffered; Shutdown drains and then releases — it stops the span processor's goroutine and closes the exporter's connection. Flushing alone leaves both running, which is why Shutdown is part of the interface rather than something callers type-assert for: an implementation that cannot be shut down is one this package should not accept.

func EnsureTracerProvider

func EnsureTracerProvider(tracerProvider Provider) Provider

type ServicePermissionChecker

type ServicePermissionChecker interface {
	IsServiceAdmin() bool
}

ServicePermissionChecker is a minimal interface for attaching permission state to spans. Export it so the app can adapt authorization.ServiceRolePermissionChecker.

type SessionContextDataForTracing

type SessionContextDataForTracing interface {
	GetUserID() string
	GetServicePermissions() ServicePermissionChecker
	GetActiveAccountID() string
}

SessionContextDataForTracing is a minimal interface for attaching session context to spans. Export it so the app can adapt sessions.ContextData.

type Span

type Span trace.Span

Span is a simple alias for the OpenTelemetry span interface.

type Tracer

type Tracer interface {
	StartSpan(ctx context.Context) (context.Context, Span)
	StartCustomSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, Span)
}

Tracer describes a tracer.

func NewNamedTracer

func NewNamedTracer(tracerProvider Provider, name string) Tracer

NewNamedTracer creates a named Tracer from the given Provider. If tracerProvider is nil, a noop Provider is used.

func NewTracerForTest

func NewTracerForTest(name string) Tracer

NewTracerForTest creates a noop Tracer for use in tests.