Add _dd.p.ksr propagated tag for Knuth sampling rate

lib/datadog/tracing/metadata/ext.rb

@@ -66,6 +66,10 @@ module Distributed
           TAG_DD_PARENT_ID = '_dd.parent_id'
           DD_PARENT_ID_DEFAULT = '0000000000000000'
 
+          # Knuth Sampling Rate: the sampling rate applied by agent-based or rule-based sampling.
+          # This is a propagated tag (prefixed with `_dd.p.`) that is included in `x-datadog-tags`.
+          TAG_KNUTH_SAMPLING_RATE = '_dd.p.ksr'
+
           # Trace tags with this prefix will propagate from a trace through distributed tracing.
           # Distributed headers tags with this prefix will be injected into the active trace.
           TAGS_PREFIX = '_dd.p.'

lib/datadog/tracing/transport/trace_formatter.rb

@@ -49,6 +49,7 @@ def format!
 
           tag_agent_sample_rate!
           tag_hostname!
+          tag_knuth_sampling_rate!
           tag_lang!
           tag_origin!
           tag_process_id!
@@ -110,6 +111,16 @@ def tag_hostname!
           )
         end
 
+        def tag_knuth_sampling_rate!
+          rate = trace.rule_sample_rate || trace.agent_sample_rate
+          return unless rate
+
+          root_span.set_tag(
+            Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE,
+            format('%.6g', rate)
+          )
+        end
+
         def tag_lang!
           return if trace.lang.nil?
 

sig/datadog/tracing/metadata/ext.rbs

@@ -28,6 +28,7 @@ module Datadog
         module Distributed
           TAG_TRACE_SOURCE: ::String
           TAG_DECISION_MAKER: ::String
+          TAG_KNUTH_SAMPLING_RATE: ::String
           TAG_ORIGIN: ::String
           TAG_SAMPLING_PRIORITY: ::String
           TAGS_PREFIX: ::String

spec/datadog/tracing/transport/trace_formatter_spec.rb

@@ -161,6 +161,7 @@
             Datadog::Tracing::Metadata::Ext::Sampling::TAG_SAMPLE_RATE => nil,
             Datadog::Tracing::Metadata::Ext::Distributed::TAG_SAMPLING_PRIORITY => nil,
             Datadog::Tracing::Metadata::Ext::TAG_PROFILING_ENABLED => nil,
+            Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE => nil,
           )
         end
       end
@@ -182,6 +183,18 @@
             Datadog::Tracing::Metadata::Ext::TAG_PROFILING_ENABLED => 1.0,
           )
         end
+
+        context 'knuth sampling rate on root span' do
+          let(:rule_sample_rate) { 0.75 }
+
+          it 'sets _dd.p.ksr as a string tag' do
+            format!
+            # rule_sample_rate takes priority over agent_sample_rate
+            expect(root_span.meta).to include(
+              Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE => '0.75'
+            )
+          end
+        end
       end
 
       shared_examples 'root span with generic tags' do
@@ -457,5 +470,98 @@
         end
       end
     end
+
+    context 'knuth sampling rate (_dd.p.ksr)' do
+      include_context 'available root span'
+
+      context 'when only agent_sample_rate is set' do
+        let(:trace_options) { {id: trace_id, agent_sample_rate: 0.5} }
+
+        it 'sets _dd.p.ksr from agent_sample_rate' do
+          format!
+          expect(root_span.meta).to include(
+            Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE => '0.5'
+          )
+        end
+      end
+
+      context 'when only rule_sample_rate is set' do
+        let(:trace_options) { {id: trace_id, rule_sample_rate: 0.75} }
+
+        it 'sets _dd.p.ksr from rule_sample_rate' do
+          format!
+          expect(root_span.meta).to include(
+            Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE => '0.75'
+          )
+        end
+      end
+
+      context 'when both agent_sample_rate and rule_sample_rate are set' do
+        let(:trace_options) { {id: trace_id, agent_sample_rate: 0.3, rule_sample_rate: 0.8} }
+
+        it 'sets _dd.p.ksr from rule_sample_rate (rule takes priority)' do
+          format!
+          expect(root_span.meta).to include(
+            Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE => '0.8'
+          )
+        end
+      end
+
+      context 'when neither agent_sample_rate nor rule_sample_rate is set' do
+        let(:trace_options) { {id: trace_id} }
+
+        it 'does not set _dd.p.ksr' do
+          format!
+          expect(root_span.meta).to_not include(
+            Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE
+          )
+        end
+      end
+
+      context 'value formatting with 6 significant digits' do
+        [
+          [1.0, '1'],
+          [0.5, '0.5'],
+          [0.1, '0.1'],
+          [0.7654321, '0.765432'],
+          [0.100000, '0.1'],
+          [0.000001, '1e-06'],
+          [0.123456789, '0.123457'],
+        ].each do |rate, expected|
+          context "when rate is #{rate}" do
+            let(:trace_options) { {id: trace_id, agent_sample_rate: rate} }
+
+            it "formats as #{expected.inspect}" do
+              format!
+              expect(root_span.meta[Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE]).to eq(expected)
+            end
+          end
+        end
+      end
+
+      context 'tag type' do
+        let(:trace_options) { {id: trace_id, agent_sample_rate: 0.5} }
+
+        it 'is stored as a string in meta (not metrics)' do
+          format!
+          expect(root_span.meta).to include(
+            Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE => '0.5'
+          )
+          expect(root_span.metrics).to_not include(
+            Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE
+          )
+        end
+      end
+
+      context 'propagation' do
+        let(:trace_options) { {id: trace_id, agent_sample_rate: 0.5} }
+
+        it 'has the _dd.p. prefix for distributed propagation' do
+          expect(Datadog::Tracing::Metadata::Ext::Distributed::TAG_KNUTH_SAMPLING_RATE).to start_with(
+            Datadog::Tracing::Metadata::Ext::Distributed::TAGS_PREFIX
+          )
+        end
+      end
+    end
   end
 end