document sampling_mechanism.h

Author: dgoffredo

src/datadog/sampling_mechanism.h

@@ -1,5 +1,38 @@
 #pragma once
 
+// This component provides an `enum class`, `SamplingMechanism`, describing a
+// reason for a sampling decision.  A sampler (or a user, with a manual
+// override) decides whether to keep or to drop a trace, but it might do so for
+// various reasons.
+//
+// Some of those reasons are indicated by existing `SamplingPriority` values,
+// but `SamplingPriority` is inadequate for future expansion, for two reasons:
+//
+// - `SamplingPriority` conflates the keep/drop decision with the reason (e.g.
+//   `UserKeep` vs. `SamplerKeep`).  Some engineers dislike this.
+// - Some tracer implementations do not decode `SamplingPriority` integer values
+//   outside of those enumerated in this library.  This makes adding new values
+//   infeasible, as older versions of tracers propagating the `SamplingPriority`
+//   along the trace will omit new integer values.
+//
+// `SamplingMechanism` is a redefinition of the "why" of a sampling decision,
+// while the "what" is still the binary keep/drop.
+//
+// Since `SamplingPriority` is already in use and has implications for sampling
+// behavior (both in its propagation along and trace and its interpretation by
+// the trace agent), the combination `{SamplingPriority, SamplingMechanism}` is
+// used to completely describe a sampling decision.  The `SamplingPriority`
+// conveys the keep/drop decision, as well as the existing (and now redundant)
+// user vs. sampler distinction, while the `SamplingMechanism` conveys
+// precisely where the sampling decision came from, e.g. a user-specified
+// sampling rule, a user-specified override, an agent-specified priority
+// sampling rate, etc.
+//
+// To allow forward compatibility with future `SamplingMechanism` values,
+// sampling mechanism is treated as just an integer when being deserialized or
+// serialized.  `SamplingMechanism` enumerates integer values relevant to logic
+// within the tracer.
+
 namespace datadog {
 namespace tracing {