ddtrace 1.4.2 → 1.19.0

data/lib/datadog/tracing/trace_digest.rb

@@ -1,4 +1,4 @@
-# typed: true
+# frozen_string_literal: true
 
 module Datadog
   module Tracing
@@ -6,12 +6,84 @@ module Datadog
     # Used to propagate context and continue traces across execution boundaries.
     # @public_api
     class TraceDigest
+      # @!attribute [r] span_id
+      #   Datadog id for the currently active span.
+      #   @return [Integer]
+      # @!attribute [r] span_name
+      #   The operation name of the currently active span.
+      #   @return [String]
+      # @!attribute [r] span_resource
+      #   The resource name of the currently active span.
+      #   @return [String]
+      # @!attribute [r] span_service
+      #   The service of the currently active span.
+      #   @return [String]
+      # @!attribute [r] span_type
+      #   The type of the currently active span.
+      #   @return [String]
+      # @!attribute [r] trace_distributed_tags
+      #   Datadog-specific tags that support richer distributed tracing association.
+      #   @return [Hash<String,String>]
+      # @!attribute [r] trace_hostname
+      #   The hostname of the currently active trace. Use to attribute traces to hosts.
+      #   @return [String]
+      # @!attribute [r] trace_id
+      #   Datadog id for the currently active trace.
+      #   @return [Integer]
+      # @!attribute [r] trace_name
+      #   Operation name for the currently active trace.
+      #   @return [Integer]
+      # @!attribute [r] trace_origin
+      #   Datadog-specific attribution of this trace's creation.
+      #   @return [String]
+      # @!attribute [r] trace_process_id
+      #   The OS-specific process id.
+      #   @return [Integer]
+      # @!attribute [r] trace_resource
+      #   The resource name of the currently active trace.
+      #   @return [String]
+      # @!attribute [r] trace_runtime_id
+      #   Unique id to this Ruby process. Used to differentiate traces coming from
+      #   child processes forked from same parent process.
+      #   @return [String]
+      # @!attribute [r] trace_sampling_priority
+      #   Datadog-specific sampling decision for the currently active trace.
+      #   @return [Integer]
+      # @!attribute [r] trace_service
+      #   The service of the currently active trace.
+      #   @return [String]
+      # @!attribute [r] trace_distributed_id
+      #   The trace id extracted from a distributed context, if different from `trace_id`.
+      #
+      #   The current use case is when the distributed context has a trace id integer larger than 64-bit:
+      #   This attribute will preserve the original id, while `trace_id` will only contain the lower 64 bits.
+      #   @return [Integer]
+      #   @see https://www.w3.org/TR/trace-context/#trace-id
+      # @!attribute [r] trace_flags
+      #   The W3C "trace-flags" extracted from a distributed context. This field is an 8-bit unsigned integer.
+      #   @return [Integer]
+      #   @see https://www.w3.org/TR/trace-context/#trace-flags
+      # @!attribute [r] trace_state
+      #   The W3C "tracestate" extracted from a distributed context.
+      #   This field is a string representing vendor-specific distribution data.
+      #   The `dd=` entry is removed from `trace_state` as its value is dynamically calculated
+      #   on every propagation injection.
+      #   @return [String]
+      #   @see https://www.w3.org/TR/trace-context/#tracestate-header
+      # @!attribute [r] trace_state_unknown_fields
+      #   From W3C "tracestate"'s `dd=` entry, when keys are not recognized they are stored here long with their values.
+      #   This allows later propagation to include those unknown fields, as they can represent future versions of the spec
+      #   sending data through this service. This value ends in a trailing `;` to facilitate serialization.
+      #   @return [String]
+      # TODO: The documentation for the last attribute above won't be rendered.
+      # TODO: This might be a YARD bug as adding an attribute, making it now second-last attribute, renders correctly.
       attr_reader \
         :span_id,
         :span_name,
         :span_resource,
         :span_service,
         :span_type,
+        :trace_distributed_tags,
         :trace_hostname,
         :trace_id,
         :trace_name,
@@ -20,7 +92,11 @@ module Datadog
         :trace_resource,
         :trace_runtime_id,
         :trace_sampling_priority,
-        :trace_service
+        :trace_service,
+        :trace_distributed_id,
+        :trace_flags,
+        :trace_state,
+        :trace_state_unknown_fields
 
       def initialize(
         span_id: nil,
@@ -28,6 +104,7 @@ module Datadog
         span_resource: nil,
         span_service: nil,
         span_type: nil,
+        trace_distributed_tags: nil,
         trace_hostname: nil,
         trace_id: nil,
         trace_name: nil,
@@ -36,13 +113,18 @@ module Datadog
         trace_resource: nil,
         trace_runtime_id: nil,
         trace_sampling_priority: nil,
-        trace_service: nil
+        trace_service: nil,
+        trace_distributed_id: nil,
+        trace_flags: nil,
+        trace_state: nil,
+        trace_state_unknown_fields: nil
       )
         @span_id = span_id
         @span_name = span_name && span_name.dup.freeze
         @span_resource = span_resource && span_resource.dup.freeze
         @span_service = span_service && span_service.dup.freeze
         @span_type = span_type && span_type.dup.freeze
+        @trace_distributed_tags = trace_distributed_tags && trace_distributed_tags.dup.freeze
         @trace_hostname = trace_hostname && trace_hostname.dup.freeze
         @trace_id = trace_id
         @trace_name = trace_name && trace_name.dup.freeze
@@ -52,9 +134,44 @@ module Datadog
         @trace_runtime_id = trace_runtime_id && trace_runtime_id.dup.freeze
         @trace_sampling_priority = trace_sampling_priority
         @trace_service = trace_service && trace_service.dup.freeze
+        @trace_distributed_id = trace_distributed_id
+        @trace_flags = trace_flags
+        @trace_state = trace_state && trace_state.dup.freeze
+        @trace_state_unknown_fields = trace_state_unknown_fields && trace_state_unknown_fields.dup.freeze
 
         freeze
       end
+
+      # Creates a copy of this object, modifying the provided fields.
+      # @param field_value_pairs [Hash<String>] the fields to be overwritten
+      # @return [TraceDigest] returns a copy of this object with the `field_value_pairs` modified
+      def merge(field_value_pairs)
+        # DEV: Because we want to sometimes freeze the values provided to `TraceDigest`, it's best
+        # DEV: to let `#initialize` decide how to handle each field, instead of duplicating that logic here.
+        TraceDigest.new(
+          **{
+            span_id: span_id,
+            span_name: span_name,
+            span_resource: span_resource,
+            span_service: span_service,
+            span_type: span_type,
+            trace_distributed_tags: trace_distributed_tags,
+            trace_hostname: trace_hostname,
+            trace_id: trace_id,
+            trace_name: trace_name,
+            trace_origin: trace_origin,
+            trace_process_id: trace_process_id,
+            trace_resource: trace_resource,
+            trace_runtime_id: trace_runtime_id,
+            trace_sampling_priority: trace_sampling_priority,
+            trace_service: trace_service,
+            trace_distributed_id: trace_distributed_id,
+            trace_flags: trace_flags,
+            trace_state: trace_state,
+            trace_state_unknown_fields: trace_state_unknown_fields,
+          }.merge!(field_value_pairs)
+        )
+      end
     end
   end
 end

data/lib/datadog/tracing/trace_operation.rb

@@ -1,15 +1,13 @@
-# typed: false
-
-require_relative '../core'
 require_relative '../core/environment/identity'
 require_relative '../core/utils'
 
-require_relative 'sampling/ext'
 require_relative 'event'
+require_relative 'metadata/tagging'
+require_relative 'sampling/ext'
 require_relative 'span_operation'
-require_relative 'trace_segment'
 require_relative 'trace_digest'
-require_relative 'metadata/tagging'
+require_relative 'trace_segment'
+require_relative 'utils'
 
 module Datadog
   module Tracing
@@ -22,7 +20,6 @@ module Datadog
     # For async support, a {Datadog::Tracing::TraceOperation} should be employed
     # per execution context (e.g. Thread, etc.)
     #
-    # rubocop:disable Metrics/ClassLength
     # @public_api
     class TraceOperation
       include Metadata::Tagging
@@ -43,7 +40,9 @@ module Datadog
         :active_span,
         :id,
         :max_length,
-        :parent_span_id
+        :parent_span_id,
+        :trace_state,
+        :trace_state_unknown_fields
 
       attr_writer \
         :name,
@@ -67,11 +66,14 @@ module Datadog
         sampled: nil,
         sampling_priority: nil,
         service: nil,
+        profiling_enabled: nil,
         tags: nil,
-        metrics: nil
+        metrics: nil,
+        trace_state: nil,
+        trace_state_unknown_fields: nil
       )
         # Attributes
-        @id = id || Core::Utils.next_id
+        @id = id || Tracing::Utils::TraceId.next_id
         @max_length = max_length || DEFAULT_MAX_LENGTH
         @parent_span_id = parent_span_id
         @sampled = sampled.nil? ? true : sampled
@@ -87,6 +89,9 @@ module Datadog
         @sample_rate = sample_rate
         @sampling_priority = sampling_priority
         @service = service
+        @profiling_enabled = profiling_enabled
+        @trace_state = trace_state
+        @trace_state_unknown_fields = trace_state_unknown_fields
 
         # Generic tags
         set_tags(tags) if tags
@@ -113,18 +118,34 @@ module Datadog
         @finished == true
       end
 
+      # Will this trace be flushed by the tracer transport?
+      # This includes cases where the span is kept solely due to priority sampling.
+      #
+      # This is not the ultimate Datadog App sampling decision. Downstream systems
+      # can decide to reject this trace, especially for cases where priority
+      # sampling is set to AUTO_KEEP.
+      #
+      # @return [Boolean]
       def sampled?
-        @sampled == true || (!@sampling_priority.nil? && @sampling_priority > 0)
+        @sampled == true || priority_sampled?
+      end
+
+      # Has the priority sampling chosen to keep this span?
+      # @return [Boolean]
+      def priority_sampled?
+        !@sampling_priority.nil? && @sampling_priority > 0
       end
 
       def keep!
         self.sampled = true
         self.sampling_priority = Sampling::Ext::Priority::USER_KEEP
+        set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, Tracing::Sampling::Ext::Decision::MANUAL)
       end
 
       def reject!
         self.sampled = false
         self.sampling_priority = Sampling::Ext::Priority::USER_REJECT
+        set_tag(Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER, Tracing::Sampling::Ext::Decision::MANUAL)
       end
 
       def name
@@ -233,6 +254,11 @@ module Datadog
         end
       end
 
+      # Returns a {TraceSegment} with all finished spans that can be flushed
+      # at invocation time. All other **finished** spans are discarded.
+      #
+      # @yield [spans] spans that will be returned as part of the trace segment returned
+      # @return [TraceSegment]
       def flush!
         finished = finished?
 
@@ -240,6 +266,8 @@ module Datadog
         spans = @spans.dup
         @spans = []
 
+        spans = yield(spans) if block_given?
+
         # Use them to build a trace
         build_trace(spans, !finished)
       end
@@ -258,6 +286,7 @@ module Datadog
           span_resource: (@active_span && @active_span.resource),
           span_service: (@active_span && @active_span.service),
           span_type: (@active_span && @active_span.type),
+          trace_distributed_tags: distributed_tags,
           trace_hostname: @hostname,
           trace_id: @id,
           trace_name: name,
@@ -267,6 +296,8 @@ module Datadog
           trace_runtime_id: Core::Environment::Identity.id,
           trace_sampling_priority: @sampling_priority,
           trace_service: service,
+          trace_state: @trace_state,
+          trace_state_unknown_fields: @trace_state_unknown_fields,
         ).freeze
       end
 
@@ -289,6 +320,8 @@ module Datadog
           sampled: @sampled,
           sampling_priority: @sampling_priority,
           service: (service && service.dup),
+          trace_state: (@trace_state && @trace_state.dup),
+          trace_state_unknown_fields: (@trace_state_unknown_fields && @trace_state_unknown_fields.dup),
           tags: meta.dup,
           metrics: metrics.dup
         )
@@ -429,10 +462,25 @@ module Datadog
           service: service,
           tags: meta,
           metrics: metrics,
-          root_span_id: !partial ? root_span && root_span.id : nil
+          root_span_id: !partial ? root_span && root_span.id : nil,
+          profiling_enabled: @profiling_enabled,
         )
       end
+
+      # Returns tracer tags that will be propagated if this span's context
+      # is exported through {.to_digest}.
+      # @return [Hash] key value pairs of distributed tags
+      def distributed_tags
+        meta.select { |name, _| name.start_with?(Metadata::Ext::Distributed::TAGS_PREFIX) }
+      end
+
+      def reset
+        @root_span = nil
+        @active_span = nil
+        @active_span_count = 0
+        @finished = false
+        @spans = []
+      end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/datadog/tracing/trace_segment.rb

@@ -1,17 +1,15 @@
-# typed: true
-
 require_relative '../core/runtime/ext'
 require_relative '../core/utils/safe_dup'
 
 require_relative 'sampling/ext'
 require_relative 'metadata/ext'
 require_relative 'metadata/tagging'
+require_relative 'utils'
 
 module Datadog
   module Tracing
     # Serializable construct representing a trace
     # @public_api
-    # rubocop:disable Metrics/ClassLength
     class TraceSegment
       TAG_NAME = 'name'.freeze
       TAG_RESOURCE = 'resource'.freeze
@@ -31,11 +29,14 @@ module Datadog
         :rule_sample_rate,
         :runtime_id,
         :sample_rate,
+        :sampling_decision_maker,
         :sampling_priority,
-        :service
+        :service,
+        :profiling_enabled
 
       # rubocop:disable Metrics/CyclomaticComplexity
       # rubocop:disable Metrics/PerceivedComplexity
+      # @param spans [Array<Datadog::Span>]
       def initialize(
         spans,
         agent_sample_rate: nil,
@@ -54,7 +55,8 @@ module Datadog
         sampling_priority: nil,
         service: nil,
         tags: nil,
-        metrics: nil
+        metrics: nil,
+        profiling_enabled: nil
       )
         @id = id
         @root_span_id = root_span_id
@@ -77,8 +79,10 @@ module Datadog
         @rule_sample_rate = rule_sample_rate_tag || rule_sample_rate
         @runtime_id = runtime_id || runtime_id_tag
         @sample_rate = sample_rate || sample_rate_tag
+        @sampling_decision_maker = sampling_decision_maker_tag
         @sampling_priority = sampling_priority || sampling_priority_tag
         @service = Core::Utils::SafeDup.frozen_or_dup(service || service_tag)
+        @profiling_enabled = profiling_enabled
       end
       # rubocop:enable Metrics/PerceivedComplexity
       # rubocop:enable Metrics/CyclomaticComplexity
@@ -126,6 +130,12 @@ module Datadog
           || sampling_priority == Sampling::Ext::Priority::USER_KEEP
       end
 
+      def high_order_tid
+        high_order = Tracing::Utils::TraceId.to_high_order(@id)
+
+        high_order.to_s(16) if high_order != 0
+      end
+
       protected
 
       attr_reader \
@@ -171,7 +181,7 @@ module Datadog
       end
 
       def process_id_tag
-        meta[Core::Runtime::Ext::TAG_PID]
+        meta[Core::Runtime::Ext::TAG_PROCESS_ID]
       end
 
       def rate_limiter_rate_tag
@@ -194,6 +204,10 @@ module Datadog
         metrics[Metadata::Ext::Sampling::TAG_SAMPLE_RATE]
       end
 
+      def sampling_decision_maker_tag
+        meta[Metadata::Ext::Distributed::TAG_DECISION_MAKER]
+      end
+
       def sampling_priority_tag
         meta[Metadata::Ext::Distributed::TAG_SAMPLING_PRIORITY]
       end
@@ -202,6 +216,5 @@ module Datadog
         meta[TAG_SERVICE]
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/datadog/tracing/tracer.rb

@@ -1,6 +1,3 @@
-# typed: true
-
-require_relative '../core'
 require_relative '../core/environment/ext'
 require_relative '../core/environment/socket'
 
@@ -11,6 +8,7 @@ require_relative 'context_provider'
 require_relative 'sampling/all_sampler'
 require_relative 'sampling/rule_sampler'
 require_relative 'sampling/priority_sampler'
+require_relative 'sampling/span/sampler'
 require_relative 'span_operation'
 require_relative 'trace_digest'
 require_relative 'trace_operation'
@@ -22,12 +20,12 @@ module Datadog
     # example, a trace can be used to track the entire time spent processing a complicated web request.
     # Even though the request may require multiple resources and machines to handle the request, all
     # of these function calls and sub-requests would be encapsulated within a single trace.
-    # rubocop:disable Metrics/ClassLength
     class Tracer
       attr_reader \
         :trace_flush,
         :provider,
         :sampler,
+        :span_sampler,
         :tags
 
       attr_accessor \
@@ -56,6 +54,7 @@ module Datadog
           base_sampler: Sampling::AllSampler.new,
           post_sampler: Sampling::RuleSampler.new
         ),
+        span_sampler: Sampling::Span::Sampler.new,
         tags: {},
         writer: Writer.new
       )
@@ -64,6 +63,7 @@ module Datadog
         @enabled = enabled
         @provider = context_provider
         @sampler = sampler
+        @span_sampler = span_sampler
         @tags = tags
         @writer = writer
       end
@@ -320,14 +320,20 @@ module Datadog
         if digest
           TraceOperation.new(
             hostname: hostname,
+            profiling_enabled: profiling_enabled,
             id: digest.trace_id,
             origin: digest.trace_origin,
             parent_span_id: digest.span_id,
-            sampling_priority: digest.trace_sampling_priority
+            sampling_priority: digest.trace_sampling_priority,
+            # Distributed tags are just regular trace tags with special meaning to Datadog
+            tags: digest.trace_distributed_tags,
+            trace_state: digest.trace_state,
+            trace_state_unknown_fields: digest.trace_state_unknown_fields,
           )
         else
           TraceOperation.new(
-            hostname: hostname
+            hostname: hostname,
+            profiling_enabled: profiling_enabled,
           )
         end
       end
@@ -341,11 +347,14 @@ module Datadog
           sample_trace(event_trace_op) if event_span_op && event_span_op.parent_id == 0
         end
 
-        events.span_finished.subscribe do |_event_span, event_trace_op|
+        events.span_finished.subscribe do |event_span, event_trace_op|
+          sample_span(event_trace_op, event_span)
           flush_trace(event_trace_op)
         end
       end
 
+      # Creates a new TraceOperation, with events bounds to this Tracer instance.
+      # @return [TraceOperation]
       def start_trace(continue_from: nil)
         # Build a new trace using digest if provided.
         trace = build_trace(continue_from)
@@ -461,20 +470,43 @@ module Datadog
         begin
           @sampler.sample!(trace_op)
         rescue StandardError => e
-          Datadog.logger.debug { "Failed to sample trace: #{e}" }
+          SAMPLE_TRACE_LOG_ONLY_ONCE.run do
+            Datadog.logger.warn { "Failed to sample trace: #{e.class.name} #{e} at #{Array(e.backtrace).first}" }
+          end
         end
       end
 
+      SAMPLE_TRACE_LOG_ONLY_ONCE = Core::Utils::OnlyOnce.new
+      private_constant :SAMPLE_TRACE_LOG_ONLY_ONCE
+
+      def sample_span(trace_op, span)
+        begin
+          @span_sampler.sample!(trace_op, span)
+        rescue StandardError => e
+          SAMPLE_SPAN_LOG_ONLY_ONCE.run do
+            Datadog.logger.warn { "Failed to sample span: #{e.class.name} #{e} at #{Array(e.backtrace).first}" }
+          end
+        end
+      end
+
+      SAMPLE_SPAN_LOG_ONLY_ONCE = Core::Utils::OnlyOnce.new
+      private_constant :SAMPLE_SPAN_LOG_ONLY_ONCE
+
       # Flush finished spans from the trace buffer, send them to writer.
       def flush_trace(trace_op)
         begin
           trace = @trace_flush.consume!(trace_op)
           write(trace) if trace && !trace.empty?
         rescue StandardError => e
-          Datadog.logger.debug { "Failed to flush trace: #{e}" }
+          FLUSH_TRACE_LOG_ONLY_ONCE.run do
+            Datadog.logger.warn { "Failed to flush trace: #{e.class.name} #{e} at #{Array(e.backtrace).first}" }
+          end
         end
       end
 
+      FLUSH_TRACE_LOG_ONLY_ONCE = Core::Utils::OnlyOnce.new
+      private_constant :FLUSH_TRACE_LOG_ONLY_ONCE
+
       # Send the trace to the writer to enqueue the spans list in the agent
       # sending queue.
       def write(trace)
@@ -499,7 +531,11 @@ module Datadog
           span
         end
       end
+
+      def profiling_enabled
+        @profiling_enabled ||=
+          !!(defined?(Datadog::Profiling) && Datadog::Profiling.respond_to?(:enabled?) && Datadog::Profiling.enabled?)
+      end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/datadog/tracing/transport/http/api/instance.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Transport
+      module HTTP
+        module API
+          # An API configured with adapter and routes
+          class Instance
+            attr_reader \
+              :adapter,
+              :headers,
+              :spec
+
+            def initialize(spec, adapter, options = {})
+              @spec = spec
+              @adapter = adapter
+              @headers = options.fetch(:headers, {})
+            end
+
+            def encoder
+              spec.encoder
+            end
+
+            def call(env)
+              # Add headers to request env, unless empty.
+              env.headers.merge!(headers) unless headers.empty?
+
+              # Send request env to the adapter.
+              adapter.call(env)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/transport/http/api/spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Transport
+      module HTTP
+        module API
+          # Specification for an HTTP API
+          # Defines behaviors without specific configuration details.
+          class Spec
+            def initialize
+              yield(self) if block_given?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/transport/http/api.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../../../core/encoding'
+
+require_relative '../../../core/transport/http/api/map'
+require_relative 'api/spec'
+
+require_relative 'traces'
+
+module Datadog
+  module Tracing
+    module Transport
+      module HTTP
+        # Namespace for API components
+        module API
+          # Default API versions
+          V4 = 'v0.4'
+          V3 = 'v0.3'
+
+          module_function
+
+          def defaults
+            Datadog::Core::Transport::HTTP::API::Map[
+              V4 => Spec.new do |s|
+                s.traces = Traces::API::Endpoint.new(
+                  '/v0.4/traces',
+                  Core::Encoding::MsgpackEncoder,
+                  service_rates: true
+                )
+              end,
+              V3 => Spec.new do |s|
+                s.traces = Traces::API::Endpoint.new(
+                  '/v0.3/traces',
+                  Core::Encoding::MsgpackEncoder
+                )
+              end,
+            ].with_fallbacks(V4 => V3)
+          end
+        end
+      end
+    end
+  end
+end