Merge pull request #729 from whatyouhide/al/document-samplers

Document sampler modules

Author: tsloughter

apps/opentelemetry/src/otel_sampler.erl

@@ -12,9 +12,23 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
-%% A sampler is a function run on each started span that returns whether to
-%% record and propagate, only record or not record the span.
+%% @doc Behaviour for defining samplers.
+%%
+%% A sampler should provide a function run on each started span that returns whether to
+%% record and propagate, only record, or not record the span.
+%%
+%% For more information on the concept of <i>Sampling</i>, see
+%% <a href="https://opentelemetry.io/docs/concepts/sampling/">Sampling in the OpenTelemetry
+%% documentation</a> or the
+%% <a href="https://opentelemetry.io/docs/specs/otel/trace/sdk/#sampling">Sampling spec</a>.
+%% For examples of configuring samplers or implementing your own sampler,
+%% see <a href="https://opentelemetry.io/docs/languages/erlang/sampling/">the OpenTelemetry
+%% Erlang documentation</a>.
+%%
+%% <h3>Configuration</h3>
+%%
+%% To configure sampling for the `opentelemetry' application, see
+%% <a href="https://hexdocs.pm/opentelemetry/readme.html#samplers">the documentation</a>.
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_sampler).
@@ -30,8 +44,11 @@
               t/0]).
 
 -callback setup(sampler_opts()) -> sampler_config().
+%% Called when a sampler is created to set up the sampler.
+%% Should return the sampler configuration that is then passed to other callbacks.
 
 -callback description(sampler_config()) -> description().
+%% Should return the description of the sampler.
 
 -callback should_sample(
     otel_ctx:t(),
@@ -42,12 +59,19 @@
     opentelemetry:attributes_map(),
     sampler_config()
 ) -> sampling_result().
+%% Main callback that determines whether a span should be sampled.\
 
 -include("otel_sampler.hrl").
 
 -type description() :: unicode:unicode_binary().
+%% The description of the sampler.
+
 -type sampler_config() :: term().
+%% Any term used to configured a given sampler.
+
 -type sampler_opts() :: term().
+%% Any options passed to a sampler.
+
 -type builtin_sampler() ::
     always_on
     | always_off
@@ -59,16 +83,26 @@
         local_parent_not_sampled => sampler_spec(),
         root => sampler_spec()
     }}.
+%% A built-in sampler.
+
 -type sampler_spec() :: builtin_sampler() | {module(), sampler_opts()}.
+%% Specification to create a sampler.
+
 -type sampling_decision() :: ?DROP | ?RECORD_ONLY | ?RECORD_AND_SAMPLE.
+%% The decision that a sampler can make on a given span.
+
 -type sampling_result() :: {
                             sampling_decision(),
                             opentelemetry:attributes_map(),
                             opentelemetry:tracestate() | otel_tracestate:members()
                            }.
+%% The result of a sampling decision.
+
 -opaque t() :: {module(), description(), sampler_opts()}.
+%% A sampler.
 
--spec new(sampler_spec()) -> t().
+%% @doc Returns a sampler based on the given specification.
+-spec new(SamplerSpec :: sampler_spec()) -> t().
 new(always_on) ->
     new({otel_sampler_always_on, #{}});
 new(always_off) ->
@@ -81,6 +115,7 @@ new({Sampler, Opts}) ->
     Config = Sampler:setup(Opts),
     {Sampler, Sampler:description(Config), Config}.
 
+%% @private
 -spec should_sample(
     t(),
     otel_ctx:t(),
@@ -100,5 +135,6 @@ should_sample({Sampler, _, Config}, Ctx, TraceId, Links, SpanName, Kind, Attribu
             Result
     end.
 
+%% @doc Returns the description of the given sampler.
 -spec description(t()) -> description().
-description({_, Description, _}) -> Description.
+description(_Sampler = {_, Description, _}) -> Description.

apps/opentelemetry/src/otel_sampler_always_off.erl

@@ -12,8 +12,11 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
-%% This sampler always decides to neither record nor sample each span.
+%% @doc An {@link otel_sampler} that drops all spans.
+%%
+%% This is one of the
+%% <a href="https://opentelemetry.io/docs/specs/otel/trace/sdk/#built-in-samplers">built-in
+%% samplers</a> provided by the OpenTelemetry SDK.
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_sampler_always_off).
@@ -25,10 +28,13 @@
 -include_lib("opentelemetry_api/include/opentelemetry.hrl").
 -include("otel_sampler.hrl").
 
+%% @private
 setup(_Opts) -> [].
 
+%% @private
 description(_) -> <<"AlwaysOffSampler">>.
 
+%% @private
 should_sample(Ctx, _TraceId, _Links, _SpanName, _SpanKind, _Attributes, _Opts) ->
     SpanCtx = otel_tracer:current_span_ctx(Ctx),
     {?DROP, [], otel_span:tracestate(SpanCtx)}.

apps/opentelemetry/src/otel_sampler_always_on.erl

@@ -12,8 +12,11 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
-%% This sampler always decides to record and sample each span.
+%% @doc An {@link otel_sampler} that records and samples all spans.
+%%
+%% This is one of the
+%% <a href="https://opentelemetry.io/docs/specs/otel/trace/sdk/#built-in-samplers">built-in
+%% samplers</a> provided by the OpenTelemetry SDK.
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_sampler_always_on).
@@ -25,10 +28,13 @@
 -include_lib("opentelemetry_api/include/opentelemetry.hrl").
 -include("otel_sampler.hrl").
 
+%% @private
 setup(_Opts) -> [].
 
+%% @private
 description(_) -> <<"AlwaysOnSampler">>.
 
+%% @private
 should_sample(Ctx, _TraceId, _Links, _SpanName, _SpanKind, _Attributes, _Opts) ->
     SpanCtx = otel_tracer:current_span_ctx(Ctx),
     {?RECORD_AND_SAMPLE, [], otel_span:tracestate(SpanCtx)}.

apps/opentelemetry/src/otel_sampler_parent_based.erl

@@ -12,15 +12,23 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
-%% This sampler makes the decision based on the parent, with the following possibilities:
-%% 1) a remote parent that is sampled (by default always_on);
-%% 2) a remote parent that is not sampled (by default always_off);
-%% 3) a local parent that is sampled (by default always_on);
-%% 4) a local parent that is not sampled (by default always_off);
-%% 5) no parent (by default always_on).
+%% @doc An {@link otel_sampler} that makes the decision based on the parent.
+%%
+%% This sampler decides with the following possibilities:
+%% <ol>
+%%   <li>a remote parent that is sampled (by default `always_on');</li>
+%%   <li>a remote parent that is not sampled (by default `always_off');</li>
+%%   <li>a local parent that is sampled (by default `always_on');</li>
+%%   <li>a local parent that is not sampled (by default `always_off');</li>
+%%   <li>no parent (by default `always_on').</li>
+%% </ol>
 %%
 %% For each of these cases a different sampler can be configured.
+%% For options, see {@link opts()}.
+%%
+%% This is one of the
+%% <a href="https://opentelemetry.io/docs/specs/otel/trace/sdk/#built-in-samplers">built-in
+%% samplers</a> provided by the OpenTelemetry SDK.
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_sampler_parent_based).
@@ -41,7 +49,9 @@
     local_parent_not_sampled => otel_sampler:sampler_spec(),
     root => otel_sampler:sampler_spec()
 }.
+%% Options to configure this sampler.
 
+%% @private
 setup(Opts = #{root := RootSpec}) ->
     RemoteParentSampledSampler = sampler_for_spec(remote_parent_sampled, Opts, always_on),
     RemoteParentNotSampledSampler = sampler_for_spec(remote_parent_not_sampled, Opts, always_off),
@@ -63,6 +73,7 @@ sampler_for_spec(Key, Opts, DefaultModule) ->
     Spec = maps:get(Key, Opts, DefaultModule),
     otel_sampler:new(Spec).
 
+%% @private
 description(#{
     root := RootSampler,
     remote_parent_sampled := RemoteParentSampler,
@@ -76,6 +87,7 @@ description(#{
         (otel_sampler:description(LocalParentSampler))/binary, ",localParentNotSampled:",
         (otel_sampler:description(LocalParentNotSampler))/binary, "}">>.
 
+%% @private
 should_sample(Ctx, TraceId, Links, SpanName, SpanKind, Attributes, Config) ->
     ParentSpanCtx = otel_tracer:current_span_ctx(Ctx),
     SamplerKey = parent_based_sampler(ParentSpanCtx),

apps/opentelemetry/src/otel_sampler_trace_id_ratio_based.erl

@@ -12,10 +12,15 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @doc An {@link otel_sampler} that samples a configured percentage of spans.
+%%
 %% This sampler samples a configured percentage of spans, where the sampling
-%% decision is deterministic with respect to the span trace id, i.e., it always
-%% makes the same decision for the same trace id.
+%% decision is <i>deterministic</i> with respect to the span trace ID. That means
+%% the sampler always makes the same decision for the same trace ID.
+%%
+%% This is one of the
+%% <a href="https://opentelemetry.io/docs/specs/otel/trace/sdk/#built-in-samplers">built-in
+%% samplers</a> provided by the OpenTelemetry SDK.
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_sampler_trace_id_ratio_based).
@@ -30,11 +35,15 @@
 -include("otel_sampler.hrl").
 
 -type probability() :: float().
+%% A probability on whether to sample a span, between `0.0' and `1.0'.
+
 -type config() :: #{probability := probability(), id_upper_bound := integer()}.
+%% The configuration for this sampler.
 
 %% 2^63 - 1
 -define(MAX_VALUE, 9223372036854775807).
 
+%% @private
 -spec setup(probability()) -> config().
 setup(Probability) ->
     IdUpperBound =
@@ -48,9 +57,11 @@ setup(Probability) ->
         end,
     #{probability => Probability, id_upper_bound => IdUpperBound}.
 
+%% @private
 description(#{probability := Probability}) ->
     unicode:characters_to_binary(io_lib:format("TraceIdRatioBased{~.6f}", [Probability])).
 
+%% @private
 should_sample(Ctx, TraceId, _Links, _SpanName, _SpanKind, _Attributes, #{
     id_upper_bound := IdUpperBound
 }) ->

apps/opentelemetry_api_experimental/.gitignore

@@ -17,3 +17,5 @@ _build
 *.iml
 rebar3.crashdump
 *~
+
+/deps