jaegerremote

README

Jaeger Remote Sampler

This package implements Jaeger remote sampler. Remote sampler allows defining sampling configuration for services at the backend, at the granularity of service + endpoint. When using the Jaeger backend, the sampling configuration can come from two sources:

1. A static configuration file, with the ability to hot-reload it on changes.
2. Adaptive sampling where Jaeger backend automatically calculates desired sampling probabilities based on the target volume of trace data per service.

Usage

Configuration in the code:

	jaegerRemoteSampler := jaegerremote.New(
		"your-service-name",
		jaegerremote.WithSamplingServerURL("http://{sampling_service_host_name}:5778/sampling"),
		jaegerremote.WithSamplingRefreshInterval(10*time.Second),
		jaegerremote.WithInitialSampler(trace.TraceIDRatioBased(0.5)),
	)

	tp := trace.NewTracerProvider(
		trace.WithSampler(jaegerRemoteSampler),
		...
	)
	otel.SetTracerProvider(tp)

Sampling server:

• Historically, the Jaeger Agent provided the sampling server at http://{agent_host}:5778/sampling.
• When not running the Jaeger Agent, the sampling server is also provided by the Jaeger Collector, but at a slightly different endpoint: http://collector_host:14268/api/sampling.
• The OpenTelemetry Collector can provide the sampling endpoint http://{otel_collector_host}:5778/sampling by configuring an extension.

Notes:

• At this time, the Jaeger Remote Sampler can only be configured in the code, configuration via OTEL_TRACES_SAMPLER=jaeger_sampler environment variable is not supported.
• Service name must be passed to the constructor. It will be used by the sampler to poll the backend for the sampling strategy for this service.
• Both Jaeger Agent and OpenTelemetry Collector implement the Jaeger sampling service endpoint.

Example

example/ shows how to host remote sampling strategies using the OpenTelemetry Collector. The Collector uses the Jaeger receiver to host the strategy file. Note you do not need to run Jaeger to make use of the Jaeger remote sampling protocol. However, you do need Jaeger backend if you want to utilize its adaptive sampling engine that auto-calculates remote sampling strategies.

Run the OpenTelemetry Collector using docker-compose:

$ docker-compose up -d

You can fetch the strategy file using curl:

$ curl 'localhost:5778/sampling?service=foo'
$ curl 'localhost:5778/sampling?service=myService'

Run the Go program. This program will start with an initial sampling percentage of 50% and tries to fetch the sampling strategies from the OpenTelemetry Collector. It will print the entire Jaeger remote sampler structure every 10 seconds, this allows you to observe the internal sampler.

$ go run .

Update generated Jaeger code

Code is generated using the .proto files from jaeger-idl. In case sampling.proto is modified these have to be regenerated.

$ make proto-gen

Documentation

Overview

Package jaegerremote implements the Jaeger Remote protocol.

Index

• func SemVersion() string
• func Version() string
• type Option
  • func WithInitialSampler(sampler trace.Sampler) Option
  • func WithLogger(logger logr.Logger) Option
  • func WithMaxOperations(maxOperations int) Option
  • func WithOperationNameLateBinding(enable bool) Option
  • func WithSamplingRefreshInterval(samplingRefreshInterval time.Duration) Option
  • func WithSamplingServerURL(samplingServerURL string) Option
  • func WithSamplingStrategyFetcher(fetcher SamplingStrategyFetcher) Option
• type Sampler
  • func New(serviceName string, opts ...Option) *Sampler
  • func (s *Sampler) Close()
  • func (s *Sampler) Description() string
  • func (s *Sampler) ShouldSample(p trace.SamplingParameters) trace.SamplingResult
  • func (s *Sampler) UpdateSampler()
• type SamplingStrategyFetcher

Functions

func SemVersion

func SemVersion() string

SemVersion is the semantic version to be supplied to tracer/meter creation.

Deprecated: Use Version instead.

func Version

func Version() string

Version is the current release version of the Jaeger remote sampler.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option applies configuration settings to a Sampler.

func WithInitialSampler

func WithInitialSampler(sampler trace.Sampler) Option

WithInitialSampler creates a Option that sets the initial sampler to use before a remote sampler is created and used.

func WithLogger

func WithLogger(logger logr.Logger) Option

WithLogger configures the sampler to log operation and debug information with logger.

func WithMaxOperations

func WithMaxOperations(maxOperations int) Option

WithMaxOperations creates a Option that sets the maximum number of operations the sampler will keep track of.

func WithOperationNameLateBinding

func WithOperationNameLateBinding(enable bool) Option

WithOperationNameLateBinding creates a Option that sets the respective field in the perOperationSamplerParams.

func WithSamplingRefreshInterval

func WithSamplingRefreshInterval(samplingRefreshInterval time.Duration) Option

WithSamplingRefreshInterval creates a Option that sets how often the sampler will poll local agent for the appropriate sampling strategy.

func WithSamplingServerURL

func WithSamplingServerURL(samplingServerURL string) Option

WithSamplingServerURL creates a Option that sets the sampling server url of the local agent that contains the sampling strategies.

func WithSamplingStrategyFetcher

func WithSamplingStrategyFetcher(fetcher SamplingStrategyFetcher) Option

WithSamplingStrategyFetcher creates an Option that initializes the sampling strategy fetcher. Custom fetcher can be used for setting custom headers, timeouts, etc., or getting sampling strategies from a different source, like files.

type Sampler

type Sampler struct {
	sync.RWMutex // used to serialize access to samplerConfig.sampler
	// contains filtered or unexported fields
}

Sampler is a delegating sampler that polls a remote server for the appropriate sampling strategy, constructs a corresponding sampler and delegates to it for sampling decisions.

func New

func New(
	serviceName string,
	opts ...Option,
) *Sampler

New creates a sampler that periodically pulls the sampling strategy from an HTTP sampling server (e.g. jaeger-agent).

func (*Sampler) Close

func (s *Sampler) Close()

Close does a clean shutdown of the sampler, stopping any background go-routines it may have started.

func (*Sampler) Description

func (s *Sampler) Description() string

Description returns a human-readable name for the Sampler.

func (*Sampler) ShouldSample

func (s *Sampler) ShouldSample(p trace.SamplingParameters) trace.SamplingResult

ShouldSample returns a sampling choice based on the passed sampling parameters.

func (*Sampler) UpdateSampler

func (s *Sampler) UpdateSampler()

UpdateSampler forces the sampler to fetch sampling strategy from backend server. This function is called automatically on a timer, but can also be safely called manually, e.g. from tests.

type SamplingStrategyFetcher

type SamplingStrategyFetcher interface {
	Fetch(service string) ([]byte, error)
}

SamplingStrategyFetcher is used to fetch sampling strategy updates from remote server.