Line data    Source code

       1              : // Licensed under the Apache License, Version 2.0
       2              : // Copyright 2025, Michael Bushe, All rights reserved.
       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              :   /// Creates a new sampling result.
      58              :   ///
      59              :   /// @param decision The sampling decision
      60              :   /// @param source The source of the sampling decision
      61              :   /// @param attributes Optional attributes to add to the span
      62           81 :   const SamplingResult({
      63              :     required this.decision,
      64              :     required this.source,
      65              :     this.attributes,
      66              :   });
      67              : }
      68              : 
      69              : /// Interface for sampling decision logic.
      70              : ///
      71              : /// Samplers are responsible for deciding whether a span should be sampled
      72              : /// (i.e., recorded and exported) or not. This decision is typically made
      73              : /// when a span is started, based on various factors such as the parent
      74              : /// context, trace ID, and span attributes.
      75              : ///
      76              : /// More information:
      77              : /// https://opentelemetry.io/docs/specs/otel/trace/sdk/#sampler
      78              : abstract class Sampler {
      79              :   /// Gets a description of this sampler.
      80              :   ///
      81              :   /// This description is included in the recorded data to identify
      82              :   /// the sampler that made the sampling decision.
      83              :   ///
      84              :   /// @return A human-readable description of the sampler
      85              :   String get description;
      86              : 
      87              :   /// Makes a sampling decision based on the provided parameters.
      88              :   ///
      89              :   /// This method is called when a span is started to determine whether
      90              :   /// it should be sampled.
      91              :   ///
      92              :   /// @param parentContext The parent context containing the parent span
      93              :   /// @param traceId The trace ID of the span
      94              :   /// @param name The name of the span
      95              :   /// @param spanKind The kind of the span
      96              :   /// @param attributes The attributes of the span
      97              :   /// @param links The links to other spans
      98              :   /// @return A sampling result containing the decision and other information
      99              :   SamplingResult shouldSample({
     100              :     required Context parentContext,
     101              :     required String traceId,
     102              :     required String name,
     103              :     required SpanKind spanKind,
     104              :     required Attributes? attributes,
     105              :     required List<SpanLink>? links,
     106              :   });
     107              : }