ddtrace 1.5.2 → 1.6.1

data/lib/datadog/tracing/contrib/sinatra/tracer.rb

@@ -17,69 +17,12 @@ module Datadog
         # Datadog::Tracing::Contrib::Sinatra::Tracer is a Sinatra extension which traces
         # requests.
         module Tracer
-          def route(verb, action, *)
-            # Keep track of the route name when the app is instantiated for an
-            # incoming request.
-            condition do
-              # If the option to prepend script names is enabled, then
-              # prepend the script name from the request onto the action.
-              #
-              # DEV: env['sinatra.route'] already exists with very similar information,
-              # DEV: but doesn't account for our `resource_script_names` logic.
-              #
-              @datadog_route = if Datadog.configuration.tracing[:sinatra][:resource_script_names]
-                                 "#{request.script_name}#{action}"
-                               else
-                                 action
-                               end
-            end
-
-            super
-          end
-
           def self.registered(app)
             app.use TracerMiddleware, app_instance: app
-
-            app.after do
-              next unless Tracing.enabled?
-
-              span = Sinatra::Env.datadog_span(env, app)
-
-              # TODO: `route` should *only* be populated if @datadog_route is defined.
-              # TODO: If @datadog_route is not defined, then this Sinatra app is not responsible
-              # TODO: for handling this request.
-              # TODO:
-              # TODO: This change would be BREAKING for any Sinatra app (classic or modular),
-              # TODO: as it affects the `resource` value for requests not handled by the Sinatra app.
-              # TODO: Currently we use "#{method} #{path}" in such aces, but `path` is the raw,
-              # TODO: high-cardinality HTTP path, and can contain PII.
-              # TODO:
-              # TODO: The value we should use as the `resource` when the Sinatra app is not
-              # TODO: responsible for the request is a tricky subject.
-              # TODO: The best option is a value that clearly communicates that this app did not
-              # TODO: handle this request. It's important to keep in mind that an unhandled request
-              # TODO: by this Sinatra app might still be handled by another Rack middleware (which can
-              # TODO: be a Sinatra app itself) or it might just 404 if not handled at all.
-              # TODO:
-              # TODO: A possible value for `resource` could set a high level description, e.g.
-              # TODO: `request.request_method`, given we don't have the response object available yet.
-              route = if defined?(@datadog_route)
-                        @datadog_route
-                      else
-                        # Fallback in case no routes have matched
-                        request.path
-                      end
-
-              span.resource = "#{request.request_method} #{route}"
-              span.set_tag(Ext::TAG_ROUTE_PATH, route)
-            end
           end
 
           # Method overrides for Sinatra::Base
           module Base
-            MISSING_REQUEST_SPAN_ONLY_ONCE = Core::Utils::OnlyOnce.new
-            private_constant :MISSING_REQUEST_SPAN_ONLY_ONCE
-
             def render(engine, data, *)
               return super unless Tracing.enabled?
 
@@ -102,19 +45,21 @@ module Datadog
 
             # Invoked when a matching route is found.
             # This method yields directly to user code.
-            # rubocop:disable Metrics/MethodLength
             def route_eval
               configuration = Datadog.configuration.tracing[:sinatra]
               return super unless Tracing.enabled?
 
+              datadog_route = Sinatra::Env.route_path(env)
+
               Tracing.trace(
                 Ext::SPAN_ROUTE,
                 service: configuration[:service_name],
                 span_type: Tracing::Metadata::Ext::HTTP::TYPE_INBOUND,
-                resource: "#{request.request_method} #{@datadog_route}",
+                resource: "#{request.request_method} #{datadog_route}",
               ) do |span, trace|
                 span.set_tag(Ext::TAG_APP_NAME, settings.name || settings.superclass.name)
-                span.set_tag(Ext::TAG_ROUTE_PATH, @datadog_route)
+                span.set_tag(Ext::TAG_ROUTE_PATH, datadog_route)
+
                 if request.script_name && !request.script_name.empty?
                   span.set_tag(Ext::TAG_SCRIPT_NAME, request.script_name)
                 end
@@ -124,32 +69,15 @@ module Datadog
 
                 trace.resource = span.resource
 
-                sinatra_request_span =
-                  if self.class <= ::Sinatra::Application # Classic style (top-level) application
-                    Sinatra::Env.datadog_span(env, ::Sinatra::Application)
-                  else
-                    Sinatra::Env.datadog_span(env, self.class)
-                  end
-                if sinatra_request_span
-                  sinatra_request_span.resource = span.resource
-                else
-                  MISSING_REQUEST_SPAN_ONLY_ONCE.run do
-                    Datadog.logger.warn do
-                      'Sinatra integration is misconfigured, reported traces will be missing request metadata ' \
-                      'such as path and HTTP status code. ' \
-                      'Did you forget to add `register Datadog::Tracing::Contrib::Sinatra::Tracer` to your ' \
-                      '`Sinatra::Base` subclass? ' \
-                      'See <https://docs.datadoghq.com/tracing/setup_overview/setup/ruby/#sinatra> for more details.'
-                    end
-                  end
-                end
+                sinatra_request_span = Sinatra::Env.datadog_span(env)
+
+                sinatra_request_span.resource = span.resource
 
                 Contrib::Analytics.set_measured(span)
 
                 super
               end
             end
-            # rubocop:enable Metrics/MethodLength
           end
         end
       end

data/lib/datadog/tracing/contrib/sinatra/tracer_middleware.rb

@@ -25,10 +25,12 @@ module Datadog
           def call(env)
             # Set the trace context (e.g. distributed tracing)
             if configuration[:distributed_tracing] && Tracing.active_trace.nil?
-              original_trace = Propagation::HTTP.extract(env)
+              original_trace = Tracing::Propagation::HTTP.extract(env)
               Tracing.continue_trace!(original_trace)
             end
 
+            return @app.call(env) if Sinatra::Env.datadog_span(env)
+
             Tracing.trace(
               Ext::SPAN_REQUEST,
               service: configuration[:service_name],
@@ -39,7 +41,7 @@ module Datadog
                 # the nil signals that there's no good one yet and is also seen by profiler, when sampling the resource
                 span.resource = nil
 
-                Sinatra::Env.set_datadog_span(env, @app_instance, span)
+                Sinatra::Env.set_datadog_span(env, span)
 
                 response = @app.call(env)
               ensure
@@ -51,14 +53,18 @@ module Datadog
                 span.set_tag(Tracing::Metadata::Ext::TAG_OPERATION, Ext::TAG_OPERATION_REQUEST)
 
                 request = ::Sinatra::Request.new(env)
+
                 span.set_tag(Tracing::Metadata::Ext::HTTP::TAG_URL, request.path)
                 span.set_tag(Tracing::Metadata::Ext::HTTP::TAG_METHOD, request.request_method)
+
+                datadog_route = Sinatra::Env.route_path(env)
+
+                span.set_tag(Ext::TAG_ROUTE_PATH, datadog_route) if datadog_route
+
                 if request.script_name && !request.script_name.empty?
                   span.set_tag(Ext::TAG_SCRIPT_NAME, request.script_name)
                 end
 
-                span.set_tag(Ext::TAG_APP_NAME, @app_instance.settings.name)
-
                 # If this app handled the request, then Contrib::Sinatra::Tracer OR Contrib::Sinatra::Base set the
                 # resource; if no resource was set, let's use a fallback
                 span.resource = env['REQUEST_METHOD'] if span.resource.nil?
@@ -79,7 +85,10 @@ module Datadog
                   end
 
                   if (headers = response[1])
-                    Sinatra::Headers.response_header_tags(headers, configuration[:headers][:response]).each do |name, value|
+                    Sinatra::Headers.response_header_tags(
+                      headers,
+                      configuration[:headers][:response]
+                    ).each do |name, value|
                       span.set_tag(name, value) if span.get_tag(name).nil?
                     end
                   end
@@ -111,10 +120,6 @@ module Datadog
           def configuration
             Datadog.configuration.tracing[:sinatra]
           end
-
-          def header_to_rack_header(name)
-            "HTTP_#{name.to_s.upcase.gsub(/[-\s]/, '_')}"
-          end
         end
       end
     end

data/lib/datadog/tracing/contrib.rb

@@ -49,6 +49,7 @@ require_relative 'contrib/faraday/integration'
 require_relative 'contrib/grape/integration'
 require_relative 'contrib/graphql/integration'
 require_relative 'contrib/grpc/integration'
+require_relative 'contrib/hanami/integration'
 require_relative 'contrib/http/integration'
 require_relative 'contrib/httpclient/integration'
 require_relative 'contrib/httprb/integration'

data/lib/datadog/tracing/distributed/datadog_tags_codec.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Encodes and decodes distributed 'x-datadog-tags' tags for transport
+      # to and from external processes.
+      module DatadogTagsCodec
+        # Backport `Regexp::match?` because it is measurably the most performant
+        # way to check if a string matches a regular expression.
+        module RefineRegexp
+          unless Regexp.method_defined?(:match?)
+            refine ::Regexp do
+              def match?(*args)
+                !match(*args).nil?
+              end
+            end
+          end
+        end
+        using RefineRegexp
+
+        # ASCII characters 32-126, except `,`, `=`, and ` `. At least one character.
+        VALID_KEY_CHARS = /\A(?:(?![,= ])[\u0020-\u007E])+\Z/.freeze
+        # ASCII characters 32-126, except `,`. At least one character.
+        VALID_VALUE_CHARS = /\A(?:(?!,)[\u0020-\u007E])+\Z/.freeze
+
+        # Serializes a {Hash<String,String>} into a `x-datadog-tags`-compatible
+        # String.
+        #
+        # @param tags [Hash<String,String>] trace tag hash
+        # @return [String] serialized tags hash
+        # @raise [EncodingError] if tags cannot be serialized to the `x-datadog-tags` format
+        def self.encode(tags)
+          begin
+            tags.map do |raw_key, raw_value|
+              key = raw_key.to_s
+              value = raw_value.to_s
+
+              raise EncodingError, "Invalid key `#{key}` for value `#{value}`" unless VALID_KEY_CHARS.match?(key)
+              raise EncodingError, "Invalid value `#{value}` for key `#{key}`" unless VALID_VALUE_CHARS.match?(value)
+
+              "#{key}=#{value.strip}"
+            end.join(',')
+          rescue => e
+            raise EncodingError, "Error encoding tags `#{tags}`: `#{e}`"
+          end
+        end
+
+        # Deserializes a `x-datadog-tags`-formatted String into a {Hash<String,String>}.
+        #
+        # @param string [String] tags as serialized by {#encode}
+        # @return [Hash<String,String>] decoded input as a hash of strings
+        # @raise [DecodingError] if string does not conform to the `x-datadog-tags` format
+        def self.decode(string)
+          result = Hash[string.split(',').map do |raw_tag|
+            raw_tag.split('=', 2).tap do |raw_key, raw_value|
+              key = raw_key.to_s
+              value = raw_value.to_s
+
+              raise DecodingError, "Invalid key: #{key}" unless VALID_KEY_CHARS.match?(key)
+              raise DecodingError, "Invalid value: #{value}" unless VALID_VALUE_CHARS.match?(value)
+
+              value.strip!
+            end
+          end]
+
+          raise DecodingError, "Invalid empty tags: #{string}" if result.empty? && !string.empty?
+
+          result
+        end
+
+        # An error occurred during distributed tags encoding.
+        # See {#message} for more information.
+        class EncodingError < StandardError
+        end
+
+        # An error occurred during distributed tags decoding.
+        # See {#message} for more information.
+        class DecodingError < StandardError
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/headers/datadog.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
 # typed: true
 
 require_relative 'parser'
 require_relative 'ext'
+require_relative '../../metadata/ext'
 require_relative '../../trace_digest'
+require_relative '../datadog_tags_codec'
 
 module Datadog
   module Tracing
@@ -10,40 +13,129 @@ module Datadog
       module Headers
         # Datadog provides helpers to inject or extract headers for Datadog style headers
         module Datadog
-          include Ext
+          class << self
+            include Ext
 
-          def self.inject!(digest, env)
-            return if digest.nil?
+            def inject!(digest, env)
+              return if digest.nil?
 
-            env[HTTP_HEADER_TRACE_ID] = digest.trace_id.to_s
-            env[HTTP_HEADER_PARENT_ID] = digest.span_id.to_s
-            env[HTTP_HEADER_SAMPLING_PRIORITY] = digest.trace_sampling_priority.to_s if digest.trace_sampling_priority
-            env[HTTP_HEADER_ORIGIN] = digest.trace_origin.to_s unless digest.trace_origin.nil?
+              env[HTTP_HEADER_TRACE_ID] = digest.trace_id.to_s
+              env[HTTP_HEADER_PARENT_ID] = digest.span_id.to_s
+              env[HTTP_HEADER_SAMPLING_PRIORITY] = digest.trace_sampling_priority.to_s if digest.trace_sampling_priority
+              env[HTTP_HEADER_ORIGIN] = digest.trace_origin.to_s unless digest.trace_origin.nil?
 
-            env
-          end
+              inject_tags(digest, env)
+
+              env
+            end
+
+            def extract(env)
+              # Extract values from headers
+              headers = Parser.new(env)
+              trace_id = headers.id(HTTP_HEADER_TRACE_ID)
+              parent_id = headers.id(HTTP_HEADER_PARENT_ID)
+              origin = headers.header(HTTP_HEADER_ORIGIN)
+              sampling_priority = headers.number(HTTP_HEADER_SAMPLING_PRIORITY)
+
+              # Return early if this propagation is not valid
+              # DEV: To be valid we need to have a trace id and a parent id
+              #      or when it is a synthetics trace, just the trace id.
+              # DEV: `Parser#id` will not return 0
+              return unless (trace_id && parent_id) || (origin && trace_id)
+
+              trace_distributed_tags = extract_tags(headers)
+
+              # Return new trace headers
+              TraceDigest.new(
+                span_id: parent_id,
+                trace_id: trace_id,
+                trace_origin: origin,
+                trace_sampling_priority: sampling_priority,
+                trace_distributed_tags: trace_distributed_tags,
+              )
+            end
+
+            private
+
+            # Export trace distributed tags through the `x-datadog-tags` header.
+            #
+            # DEV: This method accesses global state (the active trace) to record its error state as a trace tag.
+            # DEV: This means errors cannot be reported if there's not active span.
+            # DEV: Ideally, we'd have a dedicated error reporting stream for all of ddtrace.
+            # DEV: The same comment applies to the {.extract_tags}.
+            def inject_tags(digest, env)
+              return if digest.trace_distributed_tags.nil? || digest.trace_distributed_tags.empty?
+
+              if ::Datadog.configuration.tracing.x_datadog_tags_max_length <= 0
+                active_trace = Tracing.active_trace
+                active_trace.set_tag('_dd.propagation_error', 'disabled') if active_trace
+                return
+              end
+
+              encoded_tags = DatadogTagsCodec.encode(digest.trace_distributed_tags)
+
+              if encoded_tags.size > ::Datadog.configuration.tracing.x_datadog_tags_max_length
+                active_trace = Tracing.active_trace
+                active_trace.set_tag('_dd.propagation_error', 'inject_max_size') if active_trace
+
+                ::Datadog.logger.warn(
+                  "Failed to inject x-datadog-tags: tags are too large (size:#{encoded_tags.size} " \
+                  "limit:#{::Datadog.configuration.tracing.x_datadog_tags_max_length}). This limit can be configured " \
+                  'through the DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH environment variable.'
+                )
+                return
+              end
+
+              env[HTTP_HEADER_TAGS] = encoded_tags
+            rescue => e
+              active_trace = Tracing.active_trace
+              active_trace.set_tag('_dd.propagation_error', 'encoding_error') if active_trace
+              ::Datadog.logger.warn(
+                "Failed to inject x-datadog-tags: #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+              )
+            end
+
+            # Import `x-datadog-tags` header tags as trace distributed tags.
+            # Only tags that have the `_dd.p.` prefix are processed.
+            def extract_tags(headers)
+              tags_header = headers.header(HTTP_HEADER_TAGS)
+              return unless tags_header
+
+              if ::Datadog.configuration.tracing.x_datadog_tags_max_length <= 0
+                active_trace = Tracing.active_trace
+                active_trace.set_tag('_dd.propagation_error', 'disabled') if active_trace
+                return
+              end
+
+              if tags_header.size > ::Datadog.configuration.tracing.x_datadog_tags_max_length
+                active_trace = Tracing.active_trace
+                active_trace.set_tag('_dd.propagation_error', 'extract_max_size') if active_trace
+
+                ::Datadog.logger.warn(
+                  "Failed to extract x-datadog-tags: tags are too large (size:#{tags_header.size} " \
+                  "limit:#{::Datadog.configuration.tracing.x_datadog_tags_max_length}). This limit can be configured " \
+                  'through the DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH environment variable.'
+                )
+                return
+              end
+
+              tags = DatadogTagsCodec.decode(tags_header)
+              # Only extract keys with the expected Datadog prefix
+              tags.select! do |key, _|
+                key.start_with?(Tracing::Metadata::Ext::Distributed::TAGS_PREFIX) && key != EXCLUDED_TAG
+              end
+              tags
+            rescue => e
+              active_trace = Tracing.active_trace
+              active_trace.set_tag('_dd.propagation_error', 'decoding_error') if active_trace
+              ::Datadog.logger.warn(
+                "Failed to extract x-datadog-tags: #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+              )
+            end
 
-          def self.extract(env)
-            # Extract values from headers
-            headers = Parser.new(env)
-            trace_id = headers.id(HTTP_HEADER_TRACE_ID)
-            parent_id = headers.id(HTTP_HEADER_PARENT_ID)
-            origin = headers.header(HTTP_HEADER_ORIGIN)
-            sampling_priority = headers.number(HTTP_HEADER_SAMPLING_PRIORITY)
-
-            # Return early if this propagation is not valid
-            # DEV: To be valid we need to have a trace id and a parent id
-            #      or when it is a synthetics trace, just the trace id.
-            # DEV: `Parser#id` will not return 0
-            return unless (trace_id && parent_id) || (origin && trace_id)
-
-            # Return new trace headers
-            TraceDigest.new(
-              span_id: parent_id,
-              trace_id: trace_id,
-              trace_origin: origin,
-              trace_sampling_priority: sampling_priority
-            )
+            # We want to exclude tags that we don't want to propagate downstream.
+            EXCLUDED_TAG = '_dd.p.upstream_services'
+            private_constant :EXCLUDED_TAG
           end
         end
       end

data/lib/datadog/tracing/distributed/headers/ext.rb

@@ -12,6 +12,8 @@ module Datadog
           HTTP_HEADER_PARENT_ID = 'x-datadog-parent-id'.freeze
           HTTP_HEADER_SAMPLING_PRIORITY = 'x-datadog-sampling-priority'.freeze
           HTTP_HEADER_ORIGIN = 'x-datadog-origin'.freeze
+          # Distributed trace-level tags
+          HTTP_HEADER_TAGS = 'x-datadog-tags'.freeze
 
           # B3 headers used for distributed tracing
           B3_HEADER_TRACE_ID = 'x-b3-traceid'.freeze

data/lib/datadog/tracing/flush.rb

@@ -48,7 +48,7 @@ module Datadog
         # Single Span Sampling has chosen to keep this span
         # regardless of the trace-level sampling decision
         def single_sampled?(span)
-          span.get_metric(Sampling::Span::Ext::TAG_MECHANISM) == Sampling::Span::Ext::MECHANISM_SPAN_SAMPLING_RATE
+          span.get_metric(Sampling::Span::Ext::TAG_MECHANISM) == Sampling::Ext::Mechanism::SPAN_SAMPLING_RATE
         end
       end
 

data/lib/datadog/tracing/metadata/ext.rb

@@ -45,8 +45,16 @@ module Datadog
         # @public_api
         # Tags related to distributed tracing
         module Distributed
+          # What mechanism was used to make this trace's sampling decision.
+          # @see Datadog::Tracing::Sampling::Ext::Mechanism
+          TAG_DECISION_MAKER = '_dd.p.dm'
+
           TAG_ORIGIN = '_dd.origin'
           TAG_SAMPLING_PRIORITY = '_sampling_priority_v1'
+
+          # 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.'
         end
 
         # @public_api

data/lib/datadog/tracing/propagation/http.rb

@@ -23,7 +23,15 @@ module Datadog
           Configuration::Ext::Distributed::PROPAGATION_STYLE_DATADOG => Distributed::Headers::Datadog
         }.freeze
 
-        # inject! popolates the env with span ID, trace ID and sampling priority
+        # inject! populates the env with span ID, trace ID and sampling priority
+        #
+        # DEV-2.0: inject! should work without arguments, injecting the active_trace's digest
+        # DEV-2.0: and returning a new Hash with the injected headers.
+        # DEV-2.0: inject! should also accept either a `trace` or a `digest`, as a `trace`
+        # DEV-2.0: argument is the common use case, but also allows us to set error tags in the `trace`
+        # DEV-2.0: if needed.
+        # DEV-2.0: Ideally, we'd have a separate stream to report tracer errors and never
+        # DEV-2.0: touch the active span.
         def self.inject!(digest, env)
           # Prevent propagation from being attempted if trace headers provided are nil.
           if digest.nil?

data/lib/datadog/tracing/sampling/ext.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # typed: strict
 
 module Datadog
@@ -21,6 +23,35 @@ module Datadog
           # through the {Datadog::Tracing::Sampling::RuleSampler}.
           USER_KEEP = 2
         end
+
+        # List of what mechanism was used to make the trace-level sampling decision.
+        module Mechanism
+          # Single Span Sampled.
+          SPAN_SAMPLING_RATE = 8
+        end
+
+        # List of how the decision was made for the trace-level sampling.
+        #
+        # These values used to populate the {Datadog::Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER} tag.
+        #
+        # The decision has two parts, separated by a `-`:
+        # `part1-sampling_mechanism`. `part1` is currently not populated, thus
+        # this tag is currently formatted as `"-sampling_mechanism"`.
+        module Decision
+          # Used before the tracer receives any rates from agent and there are no rules configured.
+          DEFAULT = '-0'
+          # The sampling rate received in the agent's http response.
+          AGENT_RATE = '-1'
+          # Sampling rule or sampling rate based on tracer config.
+          TRACE_SAMPLING_RULE = '-3'
+          # User directly sets sampling priority via {Tracing.reject!} or {Tracing.keep!},
+          # or by a custom sampler implementation.
+          MANUAL = '-4'
+          # Formerly AppSec.
+          ASM = '-5'
+          # Single Span Sampled.
+          SPAN_SAMPLING_RATE = '-8'
+        end
       end
     end
   end

data/lib/datadog/tracing/sampling/priority_sampler.rb

@@ -21,17 +21,26 @@ module Datadog
 
         def initialize(opts = {})
           @pre_sampler = opts[:base_sampler] || AllSampler.new
-          @priority_sampler = opts[:post_sampler] || RateByServiceSampler.new
+          @priority_sampler = opts[:post_sampler] || RateByServiceSampler.new(decision: Sampling::Ext::Decision::AGENT_RATE)
         end
 
         def sample?(trace)
           @pre_sampler.sample?(trace)
         end
 
+        # DEV-2.0:We should get rid of this complicated interaction between @pre_sampler and @priority_sampler.
+        # DEV-2.0:If the user wants to configure a custom sampler, we should only allow them to provide a complete
+        # DEV-2.0:sampling suite, not having this convoluted support for mixing arbitrary provided samplers in
+        # DEV-2.0:the PrioritySampler. Ideally, the PrioritySampler is only used by Datadog.
+        # DEV-2.0:There are too many edge cases and combinations to work around currently in this class.
         def sample!(trace)
+          # The priority that was set before the sampler ran.
+          # This comes from distributed tracing priority propagation.
+          distributed_sampling_priority = priority_assigned?(trace)
+
           # If pre-sampling is configured, do it first. (By default, this will sample at 100%.)
           # NOTE: Pre-sampling at rates < 100% may result in partial traces; not recommended.
-          trace.sampled = pre_sample?(trace) ? @pre_sampler.sample!(trace) : true
+          trace.sampled = pre_sample?(trace) ? preserving_priority_sampling(trace) { @pre_sampler.sample!(trace) } : true
 
           if trace.sampled?
             # If priority sampling has already been applied upstream, use that value.
@@ -53,11 +62,27 @@ module Datadog
           end
 
           trace.sampled?
+        ensure
+          if trace.sampling_priority && trace.sampling_priority > 0
+            # Don't modify decision if priority was set upstream.
+            if !distributed_sampling_priority && !trace.has_tag?(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+              # If no sampling priority being assigned at this point, a custom
+              # sampler implementation is configured: this means the user has
+              # full control over the sampling decision.
+              trace.set_tag(
+                Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER,
+                Sampling::Ext::Decision::MANUAL
+              )
+            end
+          else
+            # The sampler decided to not keep this span, removing sampling decision.
+            trace.clear_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+          end
         end
 
         # (see Datadog::Tracing::Sampling::RateByServiceSampler#update)
-        def update(rate_by_service)
-          @priority_sampler.update(rate_by_service)
+        def update(rate_by_service, decision: nil)
+          @priority_sampler.update(rate_by_service, decision: decision)
         end
 
         private
@@ -83,6 +108,23 @@ module Datadog
           end
         end
 
+        # Ensures the trace's priority sampling decision is not changed by the @pre_sampler.
+        # The @pre_sampler should only change `trace.sampled`.
+        def preserving_priority_sampling(trace)
+          sampling_priority = trace.sampling_priority
+          sampling_decision = trace.get_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+
+          yield.tap do
+            trace.sampling_priority = sampling_priority
+
+            if sampling_decision
+              trace.set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, sampling_decision)
+            else
+              trace.clear_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER)
+            end
+          end
+        end
+
         # Ensures the trace is always propagated to the writer and that
         # the sample rate metric represents the true client-side sampling.
         def preserving_sampling(trace)