The four sampling priorities Datadog understands, by name.

A priority is a fact about the trace, not about any one span: it travels as the _sampling_priority_v1 metric on the first span of each chunk, and it decides what the backend does with a trace it receives: the keep values ask for it to be ingested, the reject values ask for it to be counted and discarded. The user_ pair says a person decided; the auto_ pair says a tracer did.

A trace this tracer opens is undecided until the decision first has to leave the process or ship — DDTrace.current_context/0, a DDTrace.Task spawn, DDTrace.inject/1, or the trace's export — and the tracer then decides it once, over the trace's root: the user_ pair when a sampling rule or the global rate matched, the auto_ pair when the agent's rate decided. DDTrace.keep_trace/0 and DDTrace.drop_trace/0 are how a person decides, moving the trace to user_keep/0 or user_reject/0, before or after the tracer's turn.

These are values you read, not values you set

There is nothing to hand a priority to: the two functions above are the whole of deciding one. Where these names earn their place is reading a decision back — the priority field of a DDTrace.SpanContext a process was handed, which is the one place a priority is visible to code:

ctx = DDTrace.current_context()

if ctx.priority == DDTrace.Priority.user_reject() do
  Logger.debug("this work is traced, but the trace will be discarded")
end

A handed context's priority can also be nil: one DDTrace.extract/1 read from headers that carried no priority is undecided until a span opened under it reaches one of the moments above. A snapshot taken with a span open always carries an integer.

The functions exist to spell the values without a typo — the raw integers are equally valid everywhere, and since these are functions rather than macros, a guard or a match head needs the raw integer.

Examples

iex> DDTrace.Priority.auto_keep()
1