README
¶
tracing
import "github.com/brpaz/lib-go/tracing"
Package tracing provides OpenTelemetry distributed tracing helpers: a Provider that wires up an OTLP/gRPC TracerProvider, and span helpers (StartSpan, EndSpan).
For OpenTelemetry trace/span injection into logs, see github.com/brpaz/lib\-go/logging.OtelMiddleware.
Provider setup
provider, err := tracing.New(ctx,
tracing.WithServiceVersion("1.2.3"),
tracing.WithServiceRevision("abc1234"),
)
if err != nil {
return err
}
defer provider.Shutdown(ctx)
The provider is registered as the global OTel tracer provider on creation, so instrumentation libraries (otelhttp, GORM plugin, etc.) work without explicit wiring after New returns. Endpoint, protocol and service name are read from the standard OTel env vars (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_SERVICE_NAME).
Span helpers
func (s *Svc) Op(ctx context.Context) (_ Result, err error) {
ctx, span := tracing.StartSpan(ctx, tracerName, "Op")
defer func() { tracing.EndSpan(span, err) }()
...
}
For HTTP middleware and test helpers, see the tracing/middleware and tracing/tracingtest sub-packages.
Index
- func EndSpan(span trace.Span, err error)
- func StartSpan(ctx context.Context, tracerName, spanName string) (context.Context, trace.Span)
- type Option
- type Provider
func EndSpan
func EndSpan(span trace.Span, err error)
EndSpan records err on span (if non-nil) and ends it. Use with named returns and a defer closure:
func (s *Svc) Op(ctx context.Context) (_ Result, err error) {
ctx, span := tracing.StartSpan(ctx, tracerName, "Op")
defer func() { tracing.EndSpan(span, err) }()
func StartSpan
func StartSpan(ctx context.Context, tracerName, spanName string) (context.Context, trace.Span)
StartSpan starts a new span using the named tracer from the global provider. tracerName should be the fully-qualified package path of the calling package (e.g. "github.com/acme/app/internal/orders").
type Option
Option configures a Provider.
type Option func(*options)
func WithAttributes
func WithAttributes(attrs ...attribute.KeyValue) Option
WithAttributes adds extra resource attributes (e.g. deployment.environment), merged with the service.version and service.revision attributes.
func WithErrorHandler
func WithErrorHandler(fn func(err error)) Option
WithErrorHandler registers fn to receive errors reported by the OTel SDK (e.g. export failures). By default, these are written to stderr.
func WithSampler
func WithSampler(sampler sdktrace.Sampler) Option
WithSampler sets the trace sampler. By default, the SDK's default sampler ([sdktrace.ParentBased] wrapping [sdktrace.AlwaysSample]) is used, which samples every trace.
func WithServiceRevision
func WithServiceRevision(revision string) Option
WithServiceRevision sets the service.revision resource attribute (e.g. a git SHA).
func WithServiceVersion
func WithServiceVersion(version string) Option
WithServiceVersion sets the service.version resource attribute.
type Provider
Provider wraps an OTel TracerProvider and provides lifecycle management. It is registered as the global OTel tracer provider on creation.
type Provider struct {
// contains filtered or unexported fields
}
func New
func New(ctx context.Context, opts ...Option) (*Provider, error)
New initialises an OTel Provider and registers it as the global tracer provider. Endpoint and protocol are read from standard OTel env vars (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL). service.name is read from OTEL_SERVICE_NAME.
func (*Provider) Shutdown
func (p *Provider) Shutdown(ctx context.Context) error
Shutdown flushes buffered spans and releases provider resources. Defer immediately after a successful New call.
Generated by gomarkdoc
Documentation
¶
Overview ¶
Package tracing provides OpenTelemetry distributed tracing helpers: a Provider that wires up an OTLP/gRPC TracerProvider, and span helpers (StartSpan, EndSpan).
For OpenTelemetry trace/span injection into logs, see github.com/brpaz/lib-go/logging.OtelMiddleware.
Provider setup ¶
provider, err := tracing.New(ctx,
tracing.WithServiceVersion("1.2.3"),
tracing.WithServiceRevision("abc1234"),
)
if err != nil {
return err
}
defer provider.Shutdown(ctx)
The provider is registered as the global OTel tracer provider on creation, so instrumentation libraries (otelhttp, GORM plugin, etc.) work without explicit wiring after New returns. Endpoint, protocol and service name are read from the standard OTel env vars (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_SERVICE_NAME).
Span helpers ¶
func (s *Svc) Op(ctx context.Context) (_ Result, err error) {
ctx, span := tracing.StartSpan(ctx, tracerName, "Op")
defer func() { tracing.EndSpan(span, err) }()
...
}
For HTTP middleware and test helpers, see the tracing/middleware and tracing/tracingtest sub-packages.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EndSpan ¶
EndSpan records err on span (if non-nil) and ends it. Use with named returns and a defer closure:
func (s *Svc) Op(ctx context.Context) (_ Result, err error) {
ctx, span := tracing.StartSpan(ctx, tracerName, "Op")
defer func() { tracing.EndSpan(span, err) }()
Types ¶
type Option ¶
type Option func(*options)
Option configures a Provider.
func WithAttributes ¶
WithAttributes adds extra resource attributes (e.g. deployment.environment), merged with the service.version and service.revision attributes.
func WithErrorHandler ¶
WithErrorHandler registers fn to receive errors reported by the OTel SDK (e.g. export failures). By default, these are written to stderr.
func WithSampler ¶
WithSampler sets the trace sampler. By default, the SDK's default sampler (sdktrace.ParentBased wrapping sdktrace.AlwaysSample) is used, which samples every trace.
func WithServiceRevision ¶
WithServiceRevision sets the service.revision resource attribute (e.g. a git SHA).
func WithServiceVersion ¶
WithServiceVersion sets the service.version resource attribute.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider wraps an OTel TracerProvider and provides lifecycle management. It is registered as the global OTel tracer provider on creation.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package tracingtest provides OpenTelemetry test helpers.
|
Package tracingtest provides OpenTelemetry test helpers. |