trace

package
v0.32.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 8, 2026 License: Apache-2.0 Imports: 46 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	// If set, adds the "caller" attribute to each trace with the source location
	// where the trace was started.
	TrackSpanCallers = (1 << iota)

	// If set, keeps track of all span references and will attempt to wait for
	// all traces to complete when shutting down a trace context.
	// Use with caution, this will cause increasing memory usage over time.
	TrackSpanReferences = (1 << iota)

	// If set, keeps track of all observed spans, including span context and
	// all attributes.
	// Use with caution, this will cause significantly increasing memory usage
	// over time.
	TrackAllSpans = (1 << iota) | TrackSpanCallers

	// If set, will log all trace IDs and their span counts on close.
	//
	// Enables [TrackAllSpans]
	LogTraceIDs = (1 << iota) | TrackAllSpans

	// If set, will log all spans observed by the exporter on close. These spans
	// may belong to incomplete traces.
	//
	// Enables [TrackAllSpans]
	LogAllSpans = (1 << iota) | TrackAllSpans

	// If set, will log all exported spans when a warning is issued on close
	// (requires warning flags to also be set)
	//
	// Enables [TrackAllSpans]
	LogAllSpansOnWarn = (1 << iota) | TrackAllSpans

	// If set, will log all trace ID mappings when a warning is issued on close.
	// (requires warning flags to also be set)
	LogTraceIDsOnWarn = (1 << iota)

	// If set, will print a warning to stderr on close if there are any incomplete
	// traces (traces with no observed root spans)
	WarnOnIncompleteTraces = (1 << iota)

	// If set, will print a warning to stderr on close if there are any incomplete
	// spans (spans started, but not ended)
	WarnOnIncompleteSpans = (1 << iota)

	// If set, will print a warning to stderr on close if there are any spans
	// which reference unknown parent spans.
	//
	// Enables [TrackSpanReferences]
	WarnOnUnresolvedReferences = (1 << iota) | TrackSpanReferences

	// If set, configures Envoy to flush every span individually, disabling its
	// internal buffer.
	EnvoyFlushEverySpan = (1 << iota)
)
View Source 
const PomeriumCoreTracer = "pomerium.io/core"

PomeriumCoreTracer should be used for all tracers created in pomerium core.

Variables

View Source 
var (
	ErrNoClient      = errors.New("no client")
	ErrClientStopped = errors.New("client is stopped")
)
View Source 
var (
	ErrIncompleteSpans    = errors.New("exporter shut down with incomplete spans")
	ErrMissingParentSpans = errors.New("exporter shut down with missing parent spans")
)
View Source 
var ShutdownGracePeriod = 2 * time.Second

ShutdownGracePeriod sets the maximum duration to wait for in-flight spans to be completed during shutdown. Only has an effect when the WarnOnIncompleteSpans debug flag is enabled.

Functions

func BatchSpanProcessorMaxExportBatchSize 

func BatchSpanProcessorMaxExportBatchSize() int

func BatchSpanProcessorScheduleDelay 

func BatchSpanProcessorScheduleDelay() int

func BestEffortProtocolFromOTLPEndpoint 

func BestEffortProtocolFromOTLPEndpoint(endpoint string, specificEnv bool) string

func Continue 

func Continue(ctx context.Context, name string, o ...trace.SpanStartOption) (context.Context, trace.Span)

Continue starts a new span using the tracer provider of the span in the given context.

In most cases, it is better to start spans directly from a specific tracer, obtained via dependency injection or some other mechanism. This function is useful in shared code where the tracer used to start the span is not necessarily the same every time, but can change based on the call site.

func ExporterServerFromContext 

func ExporterServerFromContext(ctx context.Context) coltracepb.TraceServiceServer

func ForceFlush 

func ForceFlush(ctx context.Context) error

ForceFlush immediately exports all spans that have not yet been exported for all tracer providers created using the given context.

func IsOtelSDKDisabled 

func IsOtelSDKDisabled() bool

func NewClientStatsHandler 

func NewClientStatsHandler(base stats.Handler, opts ...ClientStatsHandlerOption) stats.Handler

func NewContext 

func NewContext(parent context.Context, remoteClient otlptrace.Client) context.Context

NewContext creates a new top-level background context with tracing machinery and configuration that will be used when creating new tracer providers.

Any context created with NewContext should eventually be shut down by calling ShutdownContext to ensure all traces are exported.

The parent context should be context.Background(), or a background context containing a logger. If any context in the parent's hierarchy was created by NewContext, this will panic.

func NewHTTPMiddleware 

func NewHTTPMiddleware(opts ...otelhttp.Option) mux.MiddlewareFunc

func NewTraceClientFromConfig 

func NewTraceClientFromConfig(opts otelconfig.Config) (otlptrace.Client, error)

func NewTracerProvider 

func NewTracerProvider(ctx context.Context, serviceName string, opts ...sdktrace.TracerProviderOption) trace.TracerProvider

NewTracerProvider creates a new trace.TracerProvider with the given service name and options.

A context returned by NewContext must exist somewhere in the hierarchy of ctx, otherwise a no-op TracerProvider is returned. The configuration embedded within that context will be used to configure its resource attributes and exporter automatically.

func RemoteClientFromContext 

func RemoteClientFromContext(ctx context.Context) otlptrace.Client

func ShutdownContext 

func ShutdownContext(ctx context.Context) error

ShutdownContext will gracefully shut down all tracing resources created with a context returned by NewContext, including all tracer providers and the underlying exporter and remote client.

This should only be called once before exiting, but subsequent calls are a no-op.

The provided context does not necessarily need to be the exact context returned by NewContext; it can be anywhere in its context hierarchy and this function will have the same effect.

func ToSpanID 

func ToSpanID(bytes []byte) (oteltrace.SpanID, bool)

func ToTraceID 

func ToTraceID(bytes []byte) (unique.Handle[oteltrace.TraceID], bool)

func UseGlobalPanicTracer 

func UseGlobalPanicTracer()

UseGlobalPanicTracer sets the global tracer provider to one whose tracers panic when starting spans. This can be used to locate errant usages of the global tracer, and is enabled automatically in some tests. It is otherwise not used by default, since pomerium is used as a library in some places that might use the global tracer provider.

func WaitForSpans 

func WaitForSpans(ctx context.Context, maxDuration time.Duration) error

WaitForSpans will block up to the given max duration and wait for all in-flight spans from tracers created with the given context to end. This function can be called more than once, and is safe to call from multiple goroutines in parallel.

This requires the TrackSpanReferences debug flag to have been set with Options.NewContext. Otherwise, this function is a no-op and will return immediately.

If this function blocks for more than 10 seconds, it will print a warning to stderr containing a list of span IDs it is waiting for, and the IDs of their parents (if known). Additionally, if the TrackAllSpans debug flag is set, details about parent spans will be displayed, including call site and trace ID.

Types

type ClientStatsHandlerOption 

type ClientStatsHandlerOption func(*ClientStatsHandlerOptions)

func WithStatsInterceptor 

func WithStatsInterceptor(statsInterceptor func(ctx context.Context, rs stats.RPCStats) stats.RPCStats) ClientStatsHandlerOption

WithStatsInterceptor calls the given function to modify the rpc stats before passing it to the stats handler during HandleRPC events.

The interceptor MUST NOT modify the RPCStats it is given. It should instead return a copy of the underlying object with the same type, with any modifications made to the copy.

type ClientStatsHandlerOptions 

type ClientStatsHandlerOptions struct {
	// contains filtered or unexported fields
}

type DebugEvent 

type DebugEvent struct {
	Timestamp time.Time                             `json:"timestamp"`
	Request   *coltracepb.ExportTraceServiceRequest `json:"request"`
}

func (DebugEvent) MarshalJSON 

func (e DebugEvent) MarshalJSON() ([]byte, error)

func (*DebugEvent) UnmarshalJSON 

func (e *DebugEvent) UnmarshalJSON(b []byte) error

type DebugFlags 

type DebugFlags uint32

func DebugFlagsFromContext 

func DebugFlagsFromContext(ctx context.Context) DebugFlags

func (DebugFlags) Check 

func (df DebugFlags) Check(flags DebugFlags) bool

type ExporterServer 

type ExporterServer struct {
	coltracepb.UnimplementedTraceServiceServer
	// contains filtered or unexported fields
}

func NewServer 

func NewServer(ctx context.Context) *ExporterServer

func (*ExporterServer) Export 

func (srv *ExporterServer) Export(ctx context.Context, req *coltracepb.ExportTraceServiceRequest) (*coltracepb.ExportTraceServiceResponse, error)

Export implements ptraceotlp.GRPCServer.

func (*ExporterServer) NewClient 

func (srv *ExporterServer) NewClient() otlptrace.Client

func (*ExporterServer) Shutdown 

func (srv *ExporterServer) Shutdown(ctx context.Context) error

func (*ExporterServer) Start 

func (srv *ExporterServer) Start(ctx context.Context)

type NoopClient 

type NoopClient struct{}

func (NoopClient) Start 

func (n NoopClient) Start(context.Context) error

Start implements otlptrace.Client.

func (NoopClient) Stop 

func (n NoopClient) Stop(context.Context) error

Stop implements otlptrace.Client.

func (NoopClient) UploadTraces 

func (n NoopClient) UploadTraces(context.Context, []*v1.ResourceSpans) error

UploadTraces implements otlptrace.Client.

type Options 

type Options struct {
	DebugFlags DebugFlags
}

func (Options) NewContext 

func (op Options) NewContext(parent context.Context, remoteClient otlptrace.Client) context.Context

type PomeriumURLQueryCarrier 

type PomeriumURLQueryCarrier url.Values

func (PomeriumURLQueryCarrier) Get 

func (q PomeriumURLQueryCarrier) Get(key string) string

Get implements propagation.TextMapCarrier.

func (PomeriumURLQueryCarrier) Keys 

func (q PomeriumURLQueryCarrier) Keys() []string

Keys implements propagation.TextMapCarrier.

func (PomeriumURLQueryCarrier) Set 

func (q PomeriumURLQueryCarrier) Set(key string, value string)

Set implements propagation.TextMapCarrier.

type SyncClient 

type SyncClient interface {
	otlptrace.Client

	// Update safely replaces the current trace client with the one provided.
	// The new client must be unstarted. The old client (if any) will be stopped.
	//
	// This function is NOT reentrant; callers must use appropriate locking.
	Update(ctx context.Context, newClient otlptrace.Client) error
}

SyncClient wraps an underlying otlptrace.Client which can be swapped out for a different client (e.g. in response to a config update) safely and in a way that does not lose spans.

func NewSyncClient 

func NewSyncClient(client otlptrace.Client) SyncClient

NewSyncClient creates a new SyncClient with an initial underlying client.

The client can be nil; if so, calling any method on the SyncClient will return ErrNoClient.

type ValidNoopSpan 

type ValidNoopSpan struct {
	noop.Span
}

ValidNoopSpan is the same as noop.Span, except with a "valid" span context (has a non-zero trace and span ID).

Adding this into a context as follows: 

ctx = oteltrace.ContextWithSpan(ctx, trace.ValidNoopSpan{})

will prevent some usages of the global tracer provider by libraries such as otelhttp, which only uses the global provider if the context's span is "invalid".

func (ValidNoopSpan) SpanContext 

func (n ValidNoopSpan) SpanContext() oteltrace.SpanContext

SpanContext implements trace.Span.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.