Documentation
¶
Overview ¶
Package tracing helps with the propagation of the tracing span through context in the system. It does this for operations contained to single node, as well as across nodes, by injecting special headers.
The package wraps the OpenTelemetry Go SDK and ships spans via the OTLP/HTTP exporter, so any OTLP-compatible backend (Jaeger v2, Tempo, Honeycomb, …) works.
To use the tracing package a Tracer instance must be created:
tracer, tracerCloser, err := tracing.NewTracer(&tracing.Options{
Enabled: true,
Endpoint: "127.0.0.1:4318",
ServiceName: "bee",
})
if err != nil {
// handle error
}
defer tracerCloser.Close()
// ...
The tracer instance contains functions for starting new span contexts, injecting them in other data, and extracting the active span from the context:
span, _, ctx := tracer.StartSpanFromContext(ctx, "operation-name", nil)
Once the operation is finished, the open span should be ended:
span.End()
The tracing package also provides a function for creating a logger which will inject a "traceID" field entry to the log line, which helps in finding out which log lines belong to a specific trace.
To create a logger with trace just wrap an existing logger:
logger := tracing.NewLoggerWithTraceID(ctx, s.logger)
// ...
logger.Info("some message")
Which will result in following log line (if the context contains tracing information):
time="2015-09-07T08:48:33Z" level=info msg="some message" traceID=ed65818cc1d30c
Package tracing wraps the OpenTelemetry SDK and exposes a small set of helpers for starting spans, propagating span context across libp2p streams and HTTP requests, and annotating loggers with trace ids.
Index ¶
- Variables
- func FromContext(ctx context.Context) trace.SpanContext
- func NewLoggerWithTraceID(ctx context.Context, l log.Logger) log.Logger
- func RecordError(span trace.Span, err error, attrs ...attribute.KeyValue)
- func WithContext(ctx context.Context, sc trace.SpanContext) context.Context
- type Options
- type Tracer
- func (t *Tracer) AddContextHTTPHeader(ctx context.Context, headers http.Header) error
- func (t *Tracer) AddContextHeader(ctx context.Context, headers p2p.Headers) error
- func (t *Tracer) FollowSpanFromContext(ctx context.Context, operationName string, l log.Logger, ...) (trace.Span, log.Logger, context.Context)
- func (t *Tracer) FromHTTPHeaders(headers http.Header) (trace.SpanContext, error)
- func (t *Tracer) FromHeaders(headers p2p.Headers) (trace.SpanContext, error)
- func (t *Tracer) StartSpanFromContext(ctx context.Context, operationName string, l log.Logger, ...) (trace.Span, log.Logger, context.Context)
- func (t *Tracer) WithContextFromHTTPHeaders(ctx context.Context, headers http.Header) (context.Context, error)
- func (t *Tracer) WithContextFromHeaders(ctx context.Context, headers p2p.Headers) (context.Context, error)
Constants ¶
This section is empty.
Variables ¶
var ErrContextNotFound = errors.New("tracing context not found")
ErrContextNotFound is returned when tracing context is not present in p2p Headers, HTTP headers, or the go context.
Functions ¶
func FromContext ¶
func FromContext(ctx context.Context) trace.SpanContext
FromContext returns the span context currently associated with ctx. The returned SpanContext's IsValid() reports false when none is present.
func NewLoggerWithTraceID ¶
NewLoggerWithTraceID returns a logger annotated with the trace id from ctx, or the original logger if no valid span context is present.
func RecordError ¶
RecordError attaches an error event to the span, marks the span status as Error, and records the supplied attributes alongside the error event. It is the OTel equivalent of the OpenTracing ext.LogError pattern bee used previously.
func WithContext ¶
WithContext stores a span context in ctx using the standard OTel context key, so any OTel-aware code (propagators, exporters) can find it.
Types ¶
type Options ¶
type Options struct {
// Enabled toggles span recording. When false the tracer is a no-op.
Enabled bool
// Endpoint is the OTLP collector endpoint, e.g. "127.0.0.1:4318" for http
// or "127.0.0.1:4317" for grpc. Required when Enabled is true.
Endpoint string
// ServiceName is reported as the OTel service.name resource attribute.
ServiceName string
// ServiceVersion is reported as the OTel service.version resource
// attribute. When empty the attribute is omitted.
ServiceVersion string
// Environment is reported as the OTel deployment.environment resource
// attribute (e.g. "mainnet", "testnet"). When empty the attribute is omitted.
Environment string
// InstanceID is reported as the OTel service.instance.id resource attribute
// (the node's overlay address). When empty the attribute is omitted.
InstanceID string
// Insecure disables TLS for the OTLP exporter (useful for a local collector).
Insecure bool
// CAFile is an optional path to a PEM-encoded CA bundle used to verify
// the OTLP collector certificate. Ignored when Insecure is true. When
// empty and Insecure is false, the system root CAs are used.
CAFile string
// SamplingRatio is the head-based sampling ratio for the parent-based
// sampler in the range [0, 1]. 0 disables sampling for non-parented spans;
// 1 samples everything. Values outside [0, 1] are clamped to the nearest bound.
SamplingRatio float64
// Protocol selects the OTLP exporter transport: "http" or "grpc". Empty
// defaults to "http".
Protocol string
// Logger, when set, receives a confirmation line once tracing is wired up
// and OTLP exporter errors (e.g. an unreachable collector) via the OTel
// global error handler. Optional.
Logger log.Logger
}
Options are the constructor parameters for Tracer.
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer wraps an OTel Tracer and provides p2p/HTTP carriers plus helpers aligned with bee's tracing API.
func NewTracer ¶
NewTracer creates a new Tracer and returns a closer that flushes pending spans and shuts down the OTel pipeline.
func NewTracerFromProvider ¶
func NewTracerFromProvider(tp trace.TracerProvider) *Tracer
NewTracerFromProvider wraps an existing OTel TracerProvider in a Tracer. It is primarily useful for tests that need a recording tracer (e.g. one backed by an in-memory span recorder) rather than the OTLP exporter pipeline NewTracer builds.
func (*Tracer) AddContextHTTPHeader ¶
AddContextHTTPHeader injects the active span context into HTTP headers. Safe to call on a nil receiver.
func (*Tracer) AddContextHeader ¶
AddContextHeader serialises the active span context into the bee p2p header. It is safe to call on a nil receiver.
func (*Tracer) FollowSpanFromContext ¶
func (t *Tracer) FollowSpanFromContext(ctx context.Context, operationName string, l log.Logger, opts ...trace.SpanStartOption) (trace.Span, log.Logger, context.Context)
FollowSpanFromContext starts a new span with a Link to the span context in ctx. Links are the OTel equivalent of OpenTracing's FollowsFrom relation: the new span is causally related but not a direct child.
func (*Tracer) FromHTTPHeaders ¶
FromHTTPHeaders extracts a span context from a W3C traceparent header. Safe to call on a nil receiver.
func (*Tracer) FromHeaders ¶
FromHeaders extracts the span context from the bee p2p header. ErrContextNotFound is returned when the header is absent or when its payload is undecodable — the latter lets mixed-version peers degrade to per-hop trace continuity loss rather than failing the stream. Safe to call on a nil receiver.
func (*Tracer) StartSpanFromContext ¶
func (t *Tracer) StartSpanFromContext(ctx context.Context, operationName string, l log.Logger, opts ...trace.SpanStartOption) (trace.Span, log.Logger, context.Context)
StartSpanFromContext starts a new span as a child of any span context already present in ctx. If logger is non-nil, a derived logger annotated with the trace id is returned alongside the new context.
Source Files