Line data    Source code

       1              : // Copyright The OpenTelemetry Authors
       2              : // SPDX-License-Identifier: Apache-2.0
       3              : 
       4              : import 'package:dartastic_opentelemetry_api/dartastic_opentelemetry_api.dart';
       5              : 
       6              : /// Sources of sampling decisions.
       7              : ///
       8              : /// Identifies where a sampling decision originated from.
       9              : enum SamplingDecisionSource {
      10              :   /// The sampling decision was based on the parent span's sampling decision.
      11              :   parentBased,
      12              : 
      13              :   /// The sampling decision was based on the tracer's configuration.
      14              :   tracerConfig,
      15              : }
      16              : 
      17              : /// The possible decisions a sampler can make.
      18              : ///
      19              : /// This enum represents the possible decisions a sampler can make
      20              : /// when determining whether to sample a span.
      21              : enum SamplingDecision {
      22              :   /// The span should be recorded and sampled.
      23              :   ///
      24              :   /// This means the span will be processed by span processors and exporters,
      25              :   /// and the sampling bit in the trace flags will be set.
      26              :   recordAndSample,
      27              : 
      28              :   /// The span should be recorded but not sampled.
      29              :   ///
      30              :   /// This means the span will be processed by span processors and exporters,
      31              :   /// but the sampling bit in the trace flags will not be set.
      32              :   recordOnly,
      33              : 
      34              :   /// The span should be dropped.
      35              :   ///
      36              :   /// This means the span will not be processed by span processors or exporters.
      37              :   drop,
      38              : }
      39              : 
      40              : /// Result of a sampling decision.
      41              : ///
      42              : /// This class encapsulates the decision made by a sampler, along with
      43              : /// any additional information about the decision.
      44              : class SamplingResult {
      45              :   /// The sampling decision.
      46              :   final SamplingDecision decision;
      47              : 
      48              :   /// The source of the sampling decision.
      49              :   final SamplingDecisionSource source;
      50              : 
      51              :   /// Additional attributes to add to the span.
      52              :   ///
      53              :   /// Some samplers may add attributes to a span to provide additional
      54              :   /// information about the sampling decision.
      55              :   final Attributes? attributes;
      56              : 
      57              :   /// The TraceState to associate with the Span through the new
      58              :   /// SpanContext (Trace SDK spec, ShouldSample).
      59              :   ///
      60              :   /// Samplers SHOULD normally return the passed-in parent TraceState
      61              :   /// (reachable via `parentContext.spanContext?.traceState`) if they do
      62              :   /// not intend to change it — all built-in samplers do. Returning an
      63              :   /// empty TraceState clears the span's TraceState. Returning null means
      64              :   /// the sampler has no opinion and the SDK keeps the TraceState
      65              :   /// inherited from the parent, so samplers written before this field
      66              :   /// existed keep their inheritance behavior.
      67              :   final TraceState? traceState;
      68              : 
      69              :   /// Creates a new sampling result.
      70              :   ///
      71              :   /// @param decision The sampling decision
      72              :   /// @param source The source of the sampling decision
      73              :   /// @param attributes Optional attributes to add to the span
      74              :   /// @param traceState Optional TraceState for the new SpanContext
      75           66 :   const SamplingResult({
      76              :     required this.decision,
      77              :     required this.source,
      78              :     this.attributes,
      79              :     this.traceState,
      80              :   });
      81              : }
      82              : 
      83              : /// Interface for sampling decision logic.
      84              : ///
      85              : /// Samplers are responsible for deciding whether a span should be sampled
      86              : /// (i.e., recorded and exported) or not. This decision is typically made
      87              : /// when a span is started, based on various factors such as the parent
      88              : /// context, trace ID, and span attributes.
      89              : ///
      90              : /// More information:
      91              : /// https://opentelemetry.io/docs/specs/otel/trace/sdk/#sampler
      92              : abstract class Sampler {
      93              :   /// Gets a description of this sampler.
      94              :   ///
      95              :   /// This description is included in the recorded data to identify
      96              :   /// the sampler that made the sampling decision.
      97              :   ///
      98              :   /// @return A human-readable description of the sampler
      99              :   String get description;
     100              : 
     101              :   /// Makes a sampling decision based on the provided parameters.
     102              :   ///
     103              :   /// This method is called when a span is started to determine whether
     104              :   /// it should be sampled.
     105              :   ///
     106              :   /// @param parentContext The parent context containing the parent span
     107              :   /// @param traceId The trace ID of the span
     108              :   /// @param name The name of the span
     109              :   /// @param spanKind The kind of the span
     110              :   /// @param attributes The attributes of the span
     111              :   /// @param links The links to other spans
     112              :   /// @return A sampling result containing the decision and other information
     113              :   SamplingResult shouldSample({
     114              :     required Context parentContext,
     115              :     required String traceId,
     116              :     required String name,
     117              :     required SpanKind spanKind,
     118              :     required Attributes? attributes,
     119              :     required List<SpanLink>? links,
     120              :   });
     121              : }