Documentation ¶
Overview ¶
Package tracing supplies access to tracer providers.
It uses the otel(https://opentelemetry.io/docs/instrumentation/go/getting-started/) tracing library, connecting to an OpenTelemetry collector.
The package relies on, and is meant to be used in conjunction with the observability package
Index ¶
- Constants
- func ContextFromB3SingleHeader(ctx context.Context, b3Header string) context.Context
- func ContextFromTraceparentHeader(ctx context.Context, traceparentHeader string) context.Context
- func ContextFromW3CTraceparentHeader(ctx context.Context, traceparentHeader string) context.Context
- func Error(span trace.Span, err error)
- func GetB3SingleHeader(ctx context.Context) (b3header string)
- func GetIDs(ctx context.Context) (traceID, spanID string)
- func GetSpanID(ctx context.Context) (spanID string)
- func GetTraceID(ctx context.Context) (traceID string)
- func GetTraceparentHeader(ctx context.Context) (traceparentHeader string)
- func GetW3CTraceparentHeader(ctx context.Context) (traceparentHeader string)
- func NewTracerProvider(opts ...Option) (tp *sdktrace.TracerProvider, err error)
- func RegisterFlags(flags *flag.FlagSet)
- func Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- type Option
- type ShutdownFunc
Constants ¶
const ( TracingKey = "tracing" TracingEnabledArg string = TracingKey + ".enabled" TracingEnabledDefault bool = false TracingEnabledHelp string = "enable tracing" TracingCollectorKey string = TracingKey + ".collector" TracingCollectorTypeArg string = TracingCollectorKey + ".type" TracingCollectorTypeDefault string = "" TracingCollectorTypeHelp string = "tracing collector type" TracingCollectorEndpointArg string = TracingCollectorKey + ".endpoint" TracingCollectorEndpointDefault string = "" TracingCollectorEndpointHelp string = "endpoint collecting traces" )
Tracing flag names and their help text. The '.' is the hierarchy delimiter
Variables ¶
This section is empty.
Functions ¶
func ContextFromB3SingleHeader ¶
ContextFromB3SingleHeader will inject a tracing context that will use traceparent as the root span. The traceparent will have to comply with the [B3 single header](https://github.com/openzipkin/b3-propagation#single-header) specification
func ContextFromTraceparentHeader ¶
ContextFromTraceparentHeader accepts both W3C compliant and B3 single header compliant strings to synthesize a tracing context from an existing context
The function is meant to be called at program/processing start:
rootCtx := ContextFromTraceparentHeader(context.Background(), traceparent) // do some work A(rootCtx)
func ContextFromW3CTraceparentHeader ¶
ContextFromW3CTraceparentHeader will inject a tracing context that will use traceparent as the root span. It is meant to be used for cross-cutting injection (such as from pub/sub systems, CLI tools, etc.)
func GetB3SingleHeader ¶
GetB3SingleHeader will return the [B3 single header format](https://github.com/openzipkin/b3-propagation#single-header) compliant b3 header as a string
func GetTraceID ¶
GetTraceID extracts the traceID from the context if it is set
func GetTraceparentHeader ¶
GetTraceparentHeader will return either a W3C compliant or B3 compliant header string, depending on which propagator was used to create the tracing context
func GetW3CTraceparentHeader ¶
GetW3CTraceparentHeader will return the [W3C Trace Context](https://www.w3.org/TR/trace-context/) compliant traceparent header as a string
func NewTracerProvider ¶
func NewTracerProvider(opts ...Option) (tp *sdktrace.TracerProvider, err error)
NewTracerProvider creates a new tracer provider using the provided service name. The options can and should be used to supply a span exporter. There is no default set on purpose, since the choice of exporter highly depends on the environment the application is deployed in
func RegisterFlags ¶
RegisterFlags registers CLI arguments into flags. It accepts the Flagger interface, allowing for the use of pflag or other flag libraries such as cobra. Registration of the flags is done exactly once
func Start ¶
func Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
Start gets the tracer provider and starts a span with the provided name and options. Additional observability attributes from the context are added to the span with trace.WithAttributes
Types ¶
type Option ¶
type Option func(*tracingConfig) error
Option allows to configure the tracing setup
func WithGRPCExporter ¶
WithGRPCExporter sets up an exporter using a gRPC connection to the trace collector
func WithSpanExporter ¶
func WithSpanExporter(exporter sdktrace.SpanExporter) Option
WithSpanExporter sets the exporter
func WithStdoutTraceExporter ¶
WithStdoutTraceExporter sets the exporter to write to stdout. It's not recommended to use this exporter in production and only for testing and validation
A writer can be optionally provided. The default case is stdout
type ShutdownFunc ¶
ShutdownFunc is a function that can be used to shutdown the tracing collector
func Init ¶
func Init(opts ...Option) (ShutdownFunc, error)
Init initializes the tracer provider. The function is meant to be called once upon program setup. The reason for providing the serviceName explicitly is so that this package does not depend on the observability package to be intitialized
Best practice is to use the serviceName from the package, having previously called `observability.Init`.
func InitFromFlags ¶
func InitFromFlags(ctx context.Context) (ShutdownFunc, error)
InitFromFlags initializes tracing from the set of registered flags. Replaces the Init method