Documentation
¶
Overview ¶
Package tracing provides a thin wrapper around OpenTelemetry's tracing sdk.
The tracer instance is meant to be initialized as a singleton and injected into the context during the initialization of the application. Only the otlp exporter via grpc is currently supported but extending this support should be fairly simple.
Every function that wants to create a span should use the tracing.FromContext helper to obtain an instrumented context as well as its close function.
example usage ¶
// initialize tracer instance
tracer, err := tracing.NewTracer("service", "environment", "version")
if err != nil {
return fmt.Errorf("failed to initialize tracing: %w", err)
}
// inject tracer into context
ctx := tracing.NewContext(context.Background(), tracer)
// anywhere else in the code that should be instrumented
var err error
ctx, finish := tracing.FromContext(ctx, trace.SpanKindInternal, "domain.OperatioName")
defer finish(&err)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromContext ¶
func FromContext( ctx context.Context, kind trace.SpanKind, operation string, attributes ...attribute.KeyValue, ) (context.Context, func(*error, ...attribute.KeyValue))
FromContext starts a new span and returns a new context instrumented with said span, as well as the function to close the span. The caller *must* call the close function. If no tracer instance is present in the context, this function is no-op.
Types ¶
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer is a wrapper around the OpenTelemetry TracerProvider.
func NewTracer ¶
func NewTracer(service, env, version string, opts ...TracerOption) (*Tracer, func(context.Context) error, error)
NewTracer creates a new tracer with the given service name, environment and version. Additional options can be provided to customize the tracer behavior.
Returns the tracer instance, a shutdown function, and any error that occurred during initialization. The shutdown function should be called when the application is shutting down to ensure all spans are flushed.
func (*Tracer) StartSpan ¶
func (t *Tracer) StartSpan( ctx context.Context, kind trace.SpanKind, operation string, attributes ...attribute.KeyValue, ) (context.Context, func(*error, ...attribute.KeyValue))
StartSpan starts a new span with the given operation name and attributes.
The returned context contains the new span and should be passed to downstream functions. The returned function must be called when the operation is complete, typically using defer. The returned function accepts a pointer to an error which will be recorded if non-nil, along with any additional attributes to add to the span before it ends.
Example usage:
ctx, finish := tracer.StartSpan(ctx, trace.SpanKindServer, "my-operation") defer finish(&err)
type TracerOption ¶
TracerOption allows customizing the tracer behaviour. Use option functions only as part of tracer initialization, do not call them outside of this process.
func WithOtlpExporter ¶
func WithOtlpExporter(ctx context.Context, hostname string, port int) TracerOption
WithOtlpExporter configures the traces to be exported via OTLP to the specified endpoint. This option should only be used to initialize the tracer and it's not safe for concurrent use.
func WithSampleRate ¶
func WithSampleRate(value float64) TracerOption
WithSampleRate configures the sampling rate for traces. This option should only be used to initialize the tracer and it's not safe for concurrent use.
func WithStdOutExporter ¶
func WithStdOutExporter() TracerOption
WithStdOutExporter configures the tracer to print traces to standard output. This output is very verbose and logs a bunch of json without further processing. This option should only be used to initialize the tracer and it's not safe for concurrent use.
Source Files