instrument_sampler behaviour (instrument v1.0.0)

OpenTelemetry Sampler behavior and registry.

Samplers determine whether a span should be sampled (recorded and exported) based on various criteria like trace ID, parent context, and span attributes.

Built-in Samplers

- instrument_sampler_always_on - Always sample - instrument_sampler_always_off - Never sample - instrument_sampler_probability - Probability-based sampling - instrument_sampler_parent_based - Defer to parent's sampling decision

Example Usage

  %% Set global sampler
  instrument_sampler:set_sampler(instrument_sampler_probability, #{ratio => 0.5}).
 
  %% Make a sampling decision
  Result = instrument_sampler:should_sample(TraceId, SpanName, SpanKind, Attributes, Links, ParentCtx).

Summary

Types

sampler_config/0

sampling_decision/0

sampling_result/0

Callbacks

get_description/1

should_sample/7

Functions

get_description()

Gets the description of the current sampler.

get_sampler()

Gets the current global sampler module.

set_sampler(SamplerModule)

Sets the global sampler module.

set_sampler(SamplerModule, Config)

Sets the global sampler module with configuration.

should_sample(TraceId, SpanName, SpanKind, Attributes, Links, ParentCtx)

Makes a sampling decision for a new span.

Types

sampler_config/0

-type sampler_config() :: map().

sampling_decision/0

-type sampling_decision() :: drop | record_only | record_and_sample.

sampling_result/0

-type sampling_result() ::
          #sampling_result{decision :: drop | record_only | record_and_sample,
                           attributes :: map(),
                           trace_state :: [{binary(), binary()}]}.

Callbacks

get_description/1

-callback get_description(Config :: sampler_config()) -> binary().

should_sample/7

-callback should_sample(Config :: sampler_config(),
                        TraceId :: binary(),
                        SpanName :: binary(),
                        SpanKind :: atom(),
                        Attributes :: map(),
                        Links :: list(),
                        ParentCtx ::
                            #span_ctx{trace_id :: <<_:128>> | undefined,
                                      span_id :: <<_:64>> | undefined,
                                      trace_flags :: 0 | 1,
                                      trace_state :: [{binary(), binary()}],
                                      is_remote :: boolean()} |
                            undefined) ->
                           #sampling_result{decision :: drop | record_only | record_and_sample,
                                            attributes :: map(),
                                            trace_state :: [{binary(), binary()}]}.

Functions

get_description()

-spec get_description() -> binary().

Gets the description of the current sampler.

get_sampler()

-spec get_sampler() -> module().

Gets the current global sampler module.

set_sampler(SamplerModule)

-spec set_sampler(module()) -> ok.

Sets the global sampler module.

set_sampler(SamplerModule, Config)

-spec set_sampler(module(), sampler_config()) -> ok.

Sets the global sampler module with configuration.

should_sample(TraceId, SpanName, SpanKind, Attributes, Links, ParentCtx)

-spec should_sample(TraceId :: binary(),
                    SpanName :: binary(),
                    SpanKind :: atom(),
                    Attributes :: map(),
                    Links :: list(),
                    ParentCtx ::
                        #span_ctx{trace_id :: <<_:128>> | undefined,
                                  span_id :: <<_:64>> | undefined,
                                  trace_flags :: 0 | 1,
                                  trace_state :: [{binary(), binary()}],
                                  is_remote :: boolean()} |
                        undefined) ->
                       sampling_result().

Makes a sampling decision for a new span.

Returns a sampling_result record containing: - decision: drop | record_only | record_and_sample - attributes: additional attributes to add to the span - trace_state: updated trace state