instrument_span_processor_tail_sampler (instrument v1.0.0)
View SourceTail-based sampling span processor.
Makes sampling decisions after spans complete, enabling filtering based on: - Error status (always keep errors) - Duration (keep slow operations) - Final attribute values - Span events (exceptions, specific events)
Configuration
- always_keep: List of rules; spans matching any rule are kept - always_drop: List of rules; spans matching any rule are dropped - default_ratio: Probability (0.0-1.0) for remaining spans - exporter: Exporter module to forward kept spans - exporter_config: Configuration for the exporter
Rule Types
- {status, error | ok} - Match span status - {duration_ms, Op, Value} - Match duration (Op: '>', '<', '>=', '<=') - {attribute, Key, Value} - Exact attribute match - {attribute_exists, Key} - Attribute is present - {has_event, EventName} - Span has named event - has_exception - Span has exception event
Example
instrument_span_processor:register(instrument_span_processor_tail_sampler, #{
always_keep => [
{status, error},
{duration_ms, '>', 100},
{attribute, <<"priority">>, high}
],
always_drop => [
{attribute, <<"health_check">>, true}
],
default_ratio => 0.01,
exporter => instrument_exporter_console,
exporter_config => #{}
}).Summary
Functions
Forces a flush. Delegates to exporter if configured.
Forces a flush with state.
Initializes the tail sampler processor.
Evaluates a single rule against a span.
Called when a span ends. Applies sampling rules and forwards or drops.
Called when a span starts. Returns the span unchanged.
Determines if a span should be kept based on rules.
Shuts down the processor.
Shuts down the processor with state.
Types
-type comparison_op() :: '>' | '<' | '>=' | '<='.
-type rule() :: {status, error | ok} | {duration_ms, comparison_op(), pos_integer()} | {attribute, binary(), term()} | {attribute_exists, binary()} | {has_event, binary()} | has_exception.
Functions
-spec force_flush() -> ok.
Forces a flush. Delegates to exporter if configured.
-spec force_flush(#state{always_keep :: [rule()], always_drop :: [rule()], default_ratio :: float(), exporter :: module() | undefined, exporter_state :: term()}) -> ok.
Forces a flush with state.
-spec init(map()) -> {ok, #state{always_keep :: [rule()], always_drop :: [rule()], default_ratio :: float(), exporter :: module() | undefined, exporter_state :: term()}} | {error, term()}.
Initializes the tail sampler processor.
-spec matches_rule(#span{name :: binary(), ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, parent_ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()} | undefined, tracer :: #tracer{name :: binary(), version :: binary() | undefined, schema_url :: binary() | undefined, resource :: #resource{attributes :: map(), schema_url :: binary() | undefined} | undefined} | undefined, kind :: client | server | producer | consumer | internal, start_time :: integer(), end_time :: integer() | undefined, attributes :: map(), events :: [#span_event{name :: binary(), timestamp :: integer(), attributes :: map(), dropped_attributes_count :: non_neg_integer()}], links :: [#span_link{ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, attributes :: map(), dropped_attributes_count :: non_neg_integer()}], status :: unset | ok | {error, binary()}, is_recording :: boolean(), dropped_attributes_count :: non_neg_integer(), dropped_events_count :: non_neg_integer(), dropped_links_count :: non_neg_integer()}, rule()) -> boolean().
Evaluates a single rule against a span.
-spec on_end(#span{name :: binary(), ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, parent_ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()} | undefined, tracer :: #tracer{name :: binary(), version :: binary() | undefined, schema_url :: binary() | undefined, resource :: #resource{attributes :: map(), schema_url :: binary() | undefined} | undefined} | undefined, kind :: client | server | producer | consumer | internal, start_time :: integer(), end_time :: integer() | undefined, attributes :: map(), events :: [#span_event{name :: binary(), timestamp :: integer(), attributes :: map(), dropped_attributes_count :: non_neg_integer()}], links :: [#span_link{ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, attributes :: map(), dropped_attributes_count :: non_neg_integer()}], status :: unset | ok | {error, binary()}, is_recording :: boolean(), dropped_attributes_count :: non_neg_integer(), dropped_events_count :: non_neg_integer(), dropped_links_count :: non_neg_integer()}) -> ok.
Called when a span ends. Applies sampling rules and forwards or drops.
-spec on_start(#span{name :: binary(), ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, parent_ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()} | undefined, tracer :: #tracer{name :: binary(), version :: binary() | undefined, schema_url :: binary() | undefined, resource :: #resource{attributes :: map(), schema_url :: binary() | undefined} | undefined} | undefined, kind :: client | server | producer | consumer | internal, start_time :: integer(), end_time :: integer() | undefined, attributes :: map(), events :: [#span_event{name :: binary(), timestamp :: integer(), attributes :: map(), dropped_attributes_count :: non_neg_integer()}], links :: [#span_link{ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, attributes :: map(), dropped_attributes_count :: non_neg_integer()}], status :: unset | ok | {error, binary()}, is_recording :: boolean(), dropped_attributes_count :: non_neg_integer(), dropped_events_count :: non_neg_integer(), dropped_links_count :: non_neg_integer()}, #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()} | undefined) -> #span{name :: binary(), ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, parent_ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()} | undefined, tracer :: #tracer{name :: binary(), version :: binary() | undefined, schema_url :: binary() | undefined, resource :: #resource{attributes :: map(), schema_url :: binary() | undefined} | undefined} | undefined, kind :: client | server | producer | consumer | internal, start_time :: integer(), end_time :: integer() | undefined, attributes :: map(), events :: [#span_event{name :: binary(), timestamp :: integer(), attributes :: map(), dropped_attributes_count :: non_neg_integer()}], links :: [#span_link{ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, attributes :: map(), dropped_attributes_count :: non_neg_integer()}], status :: unset | ok | {error, binary()}, is_recording :: boolean(), dropped_attributes_count :: non_neg_integer(), dropped_events_count :: non_neg_integer(), dropped_links_count :: non_neg_integer()}.
Called when a span starts. Returns the span unchanged.
-spec should_keep(#span{name :: binary(), ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, parent_ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()} | undefined, tracer :: #tracer{name :: binary(), version :: binary() | undefined, schema_url :: binary() | undefined, resource :: #resource{attributes :: map(), schema_url :: binary() | undefined} | undefined} | undefined, kind :: client | server | producer | consumer | internal, start_time :: integer(), end_time :: integer() | undefined, attributes :: map(), events :: [#span_event{name :: binary(), timestamp :: integer(), attributes :: map(), dropped_attributes_count :: non_neg_integer()}], links :: [#span_link{ctx :: #span_ctx{trace_id :: <<_:128>> | undefined, span_id :: <<_:64>> | undefined, trace_flags :: 0 | 1, trace_state :: [{binary(), binary()}], is_remote :: boolean()}, attributes :: map(), dropped_attributes_count :: non_neg_integer()}], status :: unset | ok | {error, binary()}, is_recording :: boolean(), dropped_attributes_count :: non_neg_integer(), dropped_events_count :: non_neg_integer(), dropped_links_count :: non_neg_integer()}, #state{always_keep :: [rule()], always_drop :: [rule()], default_ratio :: float(), exporter :: module() | undefined, exporter_state :: term()}) -> boolean().
Determines if a span should be kept based on rules.
-spec shutdown() -> ok.
Shuts down the processor.
-spec shutdown(#state{always_keep :: [rule()], always_drop :: [rule()], default_ratio :: float(), exporter :: module() | undefined, exporter_state :: term()}) -> ok.
Shuts down the processor with state.