xtrace

package module
v1.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 6 Imported by: 0

README

xtrace

Small OpenTelemetry tracing helpers for Go services.

xtrace keeps the core package thin: span helpers and instrumentation scopes depend only on the OpenTelemetry API. Exporter setup and logging integrations live in separate contrib modules.

OpenTelemetry API/SDK minimum: v1.45.0. Logging integrations require the Logs API/SDK v0.21.0 or newer; the SDK uses semantic conventions v1.43.0.

Install

go get github.com/gopherex/xtrace@latest

Optional integrations:

go get github.com/gopherex/xtrace/contrib/libs/xlog@latest
go get github.com/gopherex/xtrace/contrib/sdk@latest

Span Helpers

scope := xtrace.New("billing.worker")

err := scope.Run(ctx, "charge", func(ctx context.Context, span trace.Span) error {
	return charge(ctx)
}, xtrace.WithAttrs(attribute.String("tenant", tenantID)))

Returned errors are recorded on the span and set span status to Error by default. Use WithErrorFilter, WithoutRecordError, or WithoutErrorStatus to tune that behavior.

For return values:

user, err := xtrace.Call(ctx, tracer, "user.load",
	func(ctx context.Context, span trace.Span) (User, error) {
		return users.Load(ctx, id)
	})

Instrumented clients: spans only under an operation

client, err := valkeyotel.NewClient(opts, valkeyotel.WithTracerProvider(scope.ChildOnly(otel.GetTracerProvider())))

scope.ChildOnly(provider) starts a span only when the context already carries one (local or remote). A client's background work (polling, pings, sweeps) creates no root traces; its commands still appear as children of the operations that issue them. Metrics are not affected.

xlog

contrib/libs/xlog wraps the existing github.com/gopherex/xlog/contrib/libs/otel adapter:

logger := xlog.NewJSON(xlogtrace.Options()...)
logger.Ctx().Info(ctx, "request handled")

It adds trace/span IDs to context-aware logs and records error logs onto the active span.

SDK Bootstrap

shutdown, err := sdk.Setup(ctx,
	sdk.WithService("api"),
	sdk.WithVersion(version),
	sdk.WithInstanceID(instanceID),
)
if err != nil {
	return err
}
defer shutdown(context.Background())

The SDK package exists for the code part of OpenTelemetry setup: creating and installing global providers, wiring shutdown, and stamping build-time service metadata into the resource. Exporter endpoint, protocol, headers, and timeouts still use the standard OTEL_* environment variables.

A signal is exported only when an OTLP endpoint is configured for it: OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT (TRACES, METRICS, LOGS) or the shared OTEL_EXPORTER_OTLP_ENDPOINT. With no endpoint, Setup disables that signal exactly as WithoutTraces, WithoutMetrics, or WithoutLogs would and logs one line (via slog) naming the disabled signals; it no longer falls back to the OpenTelemetry default of localhost:4317/4318. To export to a local collector, set the endpoint explicitly, e.g. OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318. An explicit Without* option always wins over a configured endpoint. StartHostRuntime is a no-op when metrics are disabled.

Build-time metadata passed through WithService, WithVersion, and WithInstanceID overrides matching values from OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES.

Documentation

Overview

Package xtrace provides small OpenTelemetry tracing helpers.

Layout:

pkg/span   - Run/Call helpers for trace spans
pkg/scope  - component instrumentation scopes
contrib/libs/xlog      - xlog integration
contrib/sdk   - optional OpenTelemetry SDK bootstrap

The root package re-exports the most common identifiers for ergonomic use.

Index

Constants

This section is empty.

Variables

View Source
var ErrNilFunc = span.ErrNilFunc

Functions

func Call

func Call[T any](ctx context.Context, tracer trace.Tracer, name string, f SpanFunc1[T], opts ...SpanOption) (T, error)

func Call2

func Call2[T, U any](ctx context.Context, tracer trace.Tracer, name string, f SpanFunc2[T, U], opts ...SpanOption) (T, U, error)

func Run

func Run(ctx context.Context, tracer trace.Tracer, name string, f SpanFunc, opts ...SpanOption) error

Types

type PanicError

type PanicError = span.PanicError

type Scope

type Scope = scope.Scope

func New

func New(name string, opts ...ScopeOption) *Scope

type ScopeOption

type ScopeOption = scope.Option

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) ScopeOption

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) ScopeOption

type SpanFunc

type SpanFunc = span.Func

type SpanFunc1

type SpanFunc1[T any] = span.Func1[T]

type SpanFunc2

type SpanFunc2[T, U any] = span.Func2[T, U]

type SpanOption

type SpanOption = span.Option

func WithAttrs

func WithAttrs(attrs ...attribute.KeyValue) SpanOption

func WithErrorFilter

func WithErrorFilter(filter func(error) bool) SpanOption

func WithRecoverPanics

func WithRecoverPanics() SpanOption

func WithSpanOptions

func WithSpanOptions(opts ...trace.SpanStartOption) SpanOption

func WithoutErrorStatus

func WithoutErrorStatus() SpanOption

func WithoutRecordError

func WithoutRecordError() SpanOption

Directories

Path Synopsis
contrib
libs/xlog module
sdk module
pkg
scope
Package scope groups OpenTelemetry instruments under one instrumentation scope name.
Package scope groups OpenTelemetry instruments under one instrumentation scope name.
span
Package span provides small helpers for running functions inside OpenTelemetry spans.
Package span provides small helpers for running functions inside OpenTelemetry spans.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL