trace

Documentation

Index

• func Manifold(config ManifoldConfig) dependency.Manifold
• func NewClient(ctx context.Context, namespace coretrace.TaggedTracerNamespace, ...) (Client, ClientTracerProvider, ClientTracer, error)
• func NewNoopWorker() *noopWorker
• func NewWorker(cfg WorkerConfig) (*tracerWorker, error)
• type Client
• type ClientSpan
• type ClientTracer
• type ClientTracerProvider
• type ManifoldConfig
  • func (cfg ManifoldConfig) Validate() error
• type NewClientFunc
• type TracerGetter
• type TracerWorkerFunc
• type TrackedTracer
  • func NewTracerWorker(ctx context.Context, namespace coretrace.TaggedTracerNamespace, ...) (TrackedTracer, error)
• type WorkerConfig
  • func (c *WorkerConfig) Validate() error

Functions

func Manifold

func Manifold(config ManifoldConfig) dependency.Manifold

Manifold returns a dependency manifold that runs the trace worker.

func NewClient

func NewClient(
	ctx context.Context,
	namespace coretrace.TaggedTracerNamespace,
	endpoint string, insecureSkipVerify bool,
	sampleRatio float64, tailSamplingThreshold time.Duration,
	logger logger.Logger,
) (Client, ClientTracerProvider, ClientTracer, error)

NewClient returns a new tracing client.

func NewNoopWorker

func NewNoopWorker() *noopWorker

NewNoopWorker worker creates a worker that doesn't perform any new work on the context. Though it will manage the lifecycle of the worker.

func NewWorker

func NewWorker(cfg WorkerConfig) (*tracerWorker, error)

NewWorker creates a new tracer worker.

Types

type Client

type Client interface {
	// Start should establish connection(s) to endpoint(s). It is
	// called just once by the exporter, so the implementation
	// does not need to worry about idempotence and locking.
	Start(ctx context.Context) error

	// Stop should close the connections. The function is called
	// only once by the exporter, so the implementation does not
	// need to worry about idempotence, but it may be called
	// concurrently with UploadTraces, so proper
	// locking is required. The function serves as a
	// synchronization point - after the function returns, the
	// process of closing connections is assumed to be finished.
	Stop(ctx context.Context) error
}

Client manages connections to the collector, handles the transformation of data into wire format, and the transmission of that data to the collector.

type ClientSpan

type ClientSpan interface {
	// End completes the Span. The Span is considered complete and ready to be
	// delivered through the rest of the telemetry pipeline after this method
	// is called. Therefore, updates to the Span are not allowed after this
	// method has been called.
	End(options ...trace.SpanEndOption)

	// AddEvent adds an event with the provided name and options.
	AddEvent(name string, options ...trace.EventOption)

	// IsRecording returns the recording state of the Span. It will return
	// true if the Span is active and events can be recorded.
	IsRecording() bool

	// RecordError will record err as an exception span event for this span. An
	// additional call to SetStatus is required if the Status of the Span should
	// be set to Error, as this method does not change the Span status. If this
	// span is not being recorded or err is nil then this method does nothing.
	RecordError(err error, options ...trace.EventOption)

	// SpanContext returns the SpanContext of the Span. The returned SpanContext
	// is usable even after the End method has been called for the Span.
	SpanContext() trace.SpanContext

	// SetStatus sets the status of the Span in the form of a code and a
	// description, provided the status hasn't already been set to a higher
	// value before (OK > Error > Unset). The description is only included in a
	// status when the code is for an error.
	SetStatus(code codes.Code, description string)

	// SetName sets the Span name.
	SetName(name string)

	// SetAttributes sets kv as attributes of the Span. If a key from kv
	// already exists for an attribute of the Span it will be overwritten with
	// the value contained in kv.
	SetAttributes(kv ...attribute.KeyValue)

	// TracerProvider returns a TracerProvider that can be used to generate
	// additional Spans on the same telemetry pipeline as the current Span.
	TracerProvider() trace.TracerProvider
}

ClientSpan is directly equivalent to the opentelemetry Span interface, minus the embedded interface.

type ClientTracer

type ClientTracer interface {
	// Start creates a span and a context.Context containing the newly-created span.
	//
	// If the context.Context provided in `ctx` contains a Span then the newly-created
	// Span will be a child of that span, otherwise it will be a root span. This behavior
	// can be overridden by providing `WithNewRoot()` as a SpanOption, causing the
	// newly-created Span to be a root span even if `ctx` contains a Span.
	//
	// When creating a Span it is recommended to provide all known span attributes using
	// the `WithAttributes()` SpanOption as samplers will only have access to the
	// attributes provided when a Span is created.
	//
	// Any Span that is created MUST also be ended. This is the responsibility of the user.
	// Implementations of this API may leak memory or other resources if Spans are not ended.
	Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, ClientSpan)
}

Tracer is the creator of Spans.

type ClientTracerProvider

type ClientTracerProvider interface {
	ForceFlush(ctx context.Context) error
	Shutdown(ctx context.Context) error
}

ClientTracerProvider is the interface for a tracer provider.

type ManifoldConfig

type ManifoldConfig struct {
	AgentName       string
	Clock           clock.Clock
	Logger          logger.Logger
	NewTracerWorker TracerWorkerFunc
	Kind            coretrace.Kind
}

ManifoldConfig defines the configuration for the trace manifold.

func (ManifoldConfig) Validate

func (cfg ManifoldConfig) Validate() error

Validate validates the manifold configuration.

type NewClientFunc

type NewClientFunc func(context.Context, coretrace.TaggedTracerNamespace, string, bool, float64, time.Duration, logger.Logger) (Client, ClientTracerProvider, ClientTracer, error)

NewClientFunc is the function signature for creating a new client.

type TracerGetter

type TracerGetter interface {
	// GetTracer returns a tracer for the given namespace.
	GetTracer(context.Context, coretrace.TracerNamespace) (coretrace.Tracer, error)
}

TracerGetter is the interface that is used to get a tracer.

type TracerWorkerFunc

type TracerWorkerFunc func(
	ctx context.Context,
	namespace coretrace.TaggedTracerNamespace,
	endpoint string,
	insecureSkipVerify bool,
	showStackTraces bool,
	sampleRatio float64,
	tailSamplingThreshold time.Duration,
	logger logger.Logger,
	newClient NewClientFunc,
) (TrackedTracer, error)

TracerWorkerFunc is the function signature for creating a new tracer worker.

type TrackedTracer

type TrackedTracer interface {
	worker.Worker
	coretrace.Tracer
}

TrackedTracer is a Tracer that is also a worker, to ensure the lifecycle of the tracer is managed.

func NewTracerWorker

func NewTracerWorker(
	ctx context.Context,
	namespace coretrace.TaggedTracerNamespace,
	endpoint string,
	insecureSkipVerify bool,
	stackTracesEnabled bool,
	sampleRatio float64,
	tailSamplingThreshold time.Duration,
	logger logger.Logger,
	newClient NewClientFunc,
) (TrackedTracer, error)

NewTracerWorker returns a new tracer worker.

type WorkerConfig

type WorkerConfig struct {
	Clock           clock.Clock
	Logger          logger.Logger
	NewTracerWorker TracerWorkerFunc

	Tag  names.Tag
	Kind coretrace.Kind

	Endpoint              string
	InsecureSkipVerify    bool
	StackTracesEnabled    bool
	SampleRatio           float64
	TailSamplingThreshold time.Duration
}

WorkerConfig encapsulates the configuration options for the tracer worker.

func (*WorkerConfig) Validate

func (c *WorkerConfig) Validate() error

Validate ensures that the config values are valid.