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)
})
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.
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 ¶
- Variables
- func Call[T any](ctx context.Context, tracer trace.Tracer, name string, f SpanFunc1[T], ...) (T, error)
- func Call2[T, U any](ctx context.Context, tracer trace.Tracer, name string, f SpanFunc2[T, U], ...) (T, U, error)
- func Run(ctx context.Context, tracer trace.Tracer, name string, f SpanFunc, ...) error
- type PanicError
- type Scope
- type ScopeOption
- type SpanFunc
- type SpanFunc1
- type SpanFunc2
- type SpanOption
Constants ¶
This section is empty.
Variables ¶
var ErrNilFunc = span.ErrNilFunc
Functions ¶
Types ¶
type PanicError ¶
type PanicError = span.PanicError
type ScopeOption ¶
func WithMeterProvider ¶
func WithMeterProvider(provider metric.MeterProvider) ScopeOption
func WithTracerProvider ¶
func WithTracerProvider(provider trace.TracerProvider) ScopeOption
type SpanOption ¶
func WithErrorFilter ¶
func WithRecoverPanics ¶
func WithRecoverPanics() SpanOption
func WithSpanOptions ¶
func WithSpanOptions(opts ...trace.SpanStartOption) SpanOption
func WithoutErrorStatus ¶
func WithoutErrorStatus() SpanOption
func WithoutRecordError ¶
func WithoutRecordError() SpanOption
Source Files
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. |