cw-datadog 2.23.0.2

data/lib/datadog/tracing/span.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative '../core/utils/safe_dup'
+require_relative 'utils'
+
+require_relative 'metadata/ext'
+require_relative 'metadata'
+
+module Datadog
+  module Tracing
+    # Represents a logical unit of work in the system. Each trace consists of one or more spans.
+    # Each span consists of a start time and a duration. For example, a span can describe the time
+    # spent on a distributed call on a separate machine, or the time spent in a small component
+    # within a larger operation. Spans can be nested within each other, and in those instances
+    # will have a parent-child relationship.
+    # @public_api
+    class Span
+      include Metadata
+
+      attr_accessor \
+        :end_time,
+        :id,
+        :meta,
+        :metrics,
+        :name,
+        :parent_id,
+        :resource,
+        :service,
+        :links,
+        :events,
+        :type,
+        :start_time,
+        :status,
+        :trace_id
+
+      attr_reader \
+        :metastruct
+
+      attr_writer \
+        :duration
+
+      # Create a new span manually. Call the <tt>start()</tt> method to start the time
+      # measurement and then <tt>stop()</tt> once the timing operation is over.
+      #
+      # * +service+: the service name for this span
+      # * +resource+: the resource this span refers, or +name+ if it's missing.
+      #     +nil+ can be used as a placeholder, when the resource value is not yet known at +#initialize+ time.
+      # * +type+: the type of the span (such as +http+, +db+ and so on)
+      # * +parent_id+: the identifier of the parent span
+      # * +trace_id+: the identifier of the root span for this trace
+      # * +service_entry+: whether it is a service entry span.
+      # * +events+: the list of events that occurred while a span was active.
+      def initialize(
+        name,
+        duration: nil,
+        end_time: nil,
+        id: nil,
+        meta: nil,
+        metrics: nil,
+        metastruct: nil,
+        parent_id: 0,
+        resource: name,
+        service: nil,
+        start_time: nil,
+        status: 0,
+        type: nil,
+        trace_id: nil,
+        service_entry: nil,
+        links: nil,
+        events: nil
+      )
+        @name = Core::Utils::SafeDup.frozen_or_dup(name)
+        @service = Core::Utils::SafeDup.frozen_or_dup(service)
+        @resource = Core::Utils::SafeDup.frozen_or_dup(resource)
+        @type = Core::Utils::SafeDup.frozen_or_dup(type)
+
+        @id = id || Tracing::Utils.next_id
+        @parent_id = parent_id || 0
+        @trace_id = trace_id || Tracing::Utils.next_id
+
+        @meta = meta || {}
+        @metrics = metrics || {}
+        @metastruct = metastruct || {}
+        @status = status || 0
+
+        # start_time and end_time track wall clock. In Ruby, wall clock
+        # has less accuracy than monotonic clock, so if possible we look to only use wall clock
+        # to measure duration when a time is supplied by the user, or if monotonic clock
+        # is unsupported.
+        @start_time = start_time
+        @end_time = end_time
+
+        # duration_start and duration_end track monotonic clock, and may remain nil in cases where it
+        # is known that we have to use wall clock to measure duration.
+        @duration = duration
+
+        @service_entry = service_entry
+
+        @links = links || []
+
+        @events = events || []
+
+        # Mark with the service entry span metric, if applicable
+        set_metric(Metadata::Ext::TAG_TOP_LEVEL, 1.0) if service_entry
+      end
+
+      # Return whether the duration is started or not
+      def started?
+        !@start_time.nil?
+      end
+
+      # Return whether the duration is stopped or not.
+      def stopped?
+        !@end_time.nil?
+      end
+      alias_method :finished?, :stopped?
+
+      def duration
+        return @duration if @duration
+
+        start_time = @start_time
+        end_time = @end_time
+        end_time - start_time if start_time && end_time
+      end
+
+      def set_error(e)
+        @status = Metadata::Ext::Errors::STATUS
+        set_error_tags(e)
+      end
+
+      # Spans with the same ID are considered the same span
+      def ==(other)
+        other.instance_of?(Span) &&
+          @id == other.id
+      end
+
+      # Return a string representation of the span.
+      def to_s
+        "Span(name:#{@name},sid:#{@id},tid:#{@trace_id},pid:#{@parent_id})"
+      end
+
+      # Return the hash representation of the current span.
+      # TODO: Change this to reflect attributes when serialization
+      # isn't handled by this method.
+      def to_hash
+        @meta['events'] = @events.map(&:to_hash).to_json unless @events.empty?
+
+        h = {
+          error: @status,
+          meta: @meta,
+          metrics: @metrics,
+          meta_struct: @metastruct.to_h,
+          name: @name,
+          parent_id: @parent_id,
+          resource: @resource,
+          service: @service,
+          span_id: @id,
+          trace_id: @trace_id,
+          type: @type,
+          span_links: @links.map(&:to_hash)
+        }
+
+        if stopped?
+          h[:start] = start_time_nano
+          h[:duration] = duration_nano
+        end
+
+        h
+      end
+
+      # Return a human readable version of the span
+      def pretty_print(q)
+        start_time = (self.start_time.to_f * 1e9).to_i
+        end_time = (self.end_time.to_f * 1e9).to_i
+        q.group 0 do
+          q.breakable
+          q.text "Name: #{@name}\n"
+          q.text "Span ID: #{@id}\n"
+          q.text "Parent ID: #{@parent_id}\n"
+          q.text "Trace ID: #{@trace_id}\n"
+          q.text "Type: #{@type}\n"
+          q.text "Service: #{@service}\n"
+          q.text "Resource: #{@resource}\n"
+          q.text "Error: #{@status}\n"
+          q.text "Start: #{start_time}\n"
+          q.text "End: #{end_time}\n"
+          q.text "Duration: #{duration.to_f}\n"
+          q.group(2, 'Tags: [', "]\n") do
+            q.breakable
+            q.seplist @meta.each do |key, value|
+              q.text "#{key} => #{value}"
+            end
+          end
+          q.group(2, 'Metrics: [', "]\n") do
+            q.breakable
+            q.seplist @metrics.each do |key, value|
+              q.text "#{key} => #{value}"
+            end
+          end
+          q.group(2, 'Metastruct: [', ']') do
+            metastruct.pretty_print(q)
+          end
+        end
+      end
+
+      private
+
+      # Used for serialization
+      # @return [Integer] in nanoseconds since Epoch
+      def start_time_nano
+        return unless (start_time = @start_time)
+
+        start_time.to_i * 1000000000 + start_time.nsec
+      end
+
+      # Used for serialization
+      # @return [Integer] in nanoseconds since Epoch
+      def duration_nano
+        duration = self.duration
+        return unless duration
+
+        (duration * 1e9).to_i
+      end
+
+      # https://docs.datadoghq.com/tracing/visualization/#service-entry-span
+      # A span is a service entry span when it is the entrypoint method for a request to a service.
+      # You can visualize this within Datadog APM when the color of the immediate parent on a flame graph is a different
+      # color. Services are also listed on the right when viewing a flame graph.
+      #
+      # @return [Boolean] `true` if the span is a serivce entry span
+      def service_entry?
+        @service_entry == true
+      end
+    end
+  end
+end

data/lib/datadog/tracing/span_event.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Datadog
+  module Tracing
+    # Represents a timestamped annotation on a span. It is analogous to structured log message.
+    # @public_api
+    class SpanEvent
+      # @!attribute [r] name
+      #   @return [Integer]
+      attr_reader :name
+
+      # @!attribute [r] attributes
+      #   @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+      attr_reader :attributes
+
+      # @!attribute [r] time_unix_nano
+      #   @return [Integer]
+      attr_reader :time_unix_nano
+
+      # TODO: Accept {Time} as the time_unix_nano parameter, possibly in addition to the current nano integer.
+      def initialize(
+        name,
+        attributes: nil,
+        time_unix_nano: nil
+      )
+        @name = name
+
+        @attributes = attributes.dup || {}
+        validate_attributes!(@attributes)
+        @attributes.transform_keys!(&:to_s)
+
+        # OpenTelemetry SDK stores span event timestamps in nanoseconds (not seconds).
+        # We will do the same here to avoid unnecessary conversions and inconsistencies.
+        @time_unix_nano = time_unix_nano || (Core::Utils::Time.now.to_r * 1_000_000_000).to_i
+      end
+
+      # Converts the span event into a hash to be used by with the span tag serialization
+      # (`span.set_tag('events) = [event.to_hash]`). This serialization format has the drawback
+      # of being limiting span events to the size limit of a span tag.
+      # All Datadog agents support this format.
+      def to_hash
+        h = {'name' => @name, 'time_unix_nano' => @time_unix_nano}
+        h['attributes'] = @attributes unless @attributes.empty?
+        h
+      end
+
+      # Converts the span event into a hash to be used by the MessagePack serialization as a
+      # top-level span field (span.span_events = [event.to_native_format]).
+      # This serialization format removes the serialization limitations of the `span.set_tag('events)` approach,
+      # but is only supported by newer version of the Datadog agent.
+      def to_native_format
+        h = {'name' => @name, 'time_unix_nano' => @time_unix_nano}
+
+        attr = {}
+        @attributes.each do |key, value|
+          attr[key] = if value.is_a?(Array)
+            {type: ARRAY_TYPE, array_value: {values: value.map { |v| serialize_native_attribute(v) }}}
+          else
+            serialize_native_attribute(value)
+          end
+        end
+
+        h['attributes'] = attr unless @attributes.empty?
+
+        h
+      end
+
+      private
+
+      MIN_INT64_SIGNED = -2**63
+      MAX_INT64_SIGNED = 2 << 63 - 1
+
+      # Checks the attributes hash to ensure it only contains serializable values.
+      # Invalid values are removed from the hash.
+      def validate_attributes!(attributes)
+        attributes.select! do |key, value|
+          case value
+          when Array
+            next true if value.empty?
+
+            first = value.first
+            case first
+            when String, Integer, Float
+              first_type = first.class
+              if value.all? { |v| v.is_a?(first_type) }
+                value.all? { |v| validate_scalar_attribute!(key, v) }
+              else
+                Datadog.logger.warn("Attribute #{key} array must be homogenous: #{value}.")
+                false
+              end
+            when TrueClass, FalseClass
+              if value.all? { |v| v.is_a?(TrueClass) || v.is_a?(FalseClass) }
+                value.all? { |v| validate_scalar_attribute!(key, v) }
+              else
+                Datadog.logger.warn("Attribute #{key} array must be homogenous: #{value}.")
+                false
+              end
+            else
+              Datadog.logger.warn("Attribute #{key} must be a string, number, or boolean: #{value}.")
+              false
+            end
+          when String, Numeric, TrueClass, FalseClass
+            validate_scalar_attribute!(key, value)
+          else
+            Datadog.logger.warn("Attribute #{key} must be a string, number, boolean, or array: #{value}.")
+            false
+          end
+        end
+      end
+
+      def validate_scalar_attribute!(key, value)
+        case value
+        when String, TrueClass, FalseClass
+          true
+        when Integer
+          # Cannot be larger than signed 64-bit integer
+          if value < MIN_INT64_SIGNED || value > MAX_INT64_SIGNED
+            Datadog.logger.warn("Attribute #{key} must be within the range of a signed 64-bit integer: #{value}.")
+            false
+          else
+            true
+          end
+        when Float
+          # Has to be finite
+          return true if value.finite?
+
+          Datadog.logger.warn("Attribute #{key} must be a finite number: #{value}.")
+          false
+        else
+          Datadog.logger.warn("Attribute #{key} must be a string, number, or boolean: #{value}.")
+          false
+        end
+      end
+
+      STRING_TYPE = 0
+      BOOLEAN_TYPE = 1
+      INTEGER_TYPE = 2
+      DOUBLE_TYPE = 3
+      ARRAY_TYPE = 4
+
+      # Serializes individual scalar attributes into the native format.
+      def serialize_native_attribute(value)
+        case value
+        when String
+          {type: STRING_TYPE, string_value: value}
+        when TrueClass, FalseClass
+          {type: BOOLEAN_TYPE, bool_value: value}
+        when Integer
+          {type: INTEGER_TYPE, int_value: value}
+        when Float
+          {type: DOUBLE_TYPE, double_value: value}
+        else
+          # This is technically unreachable due to the validation in #initialize.
+          raise ArgumentError, "Attribute must be a string, number, or boolean: #{value}."
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/span_link.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    # SpanLink represents a causal link between two spans.
+    # @public_api
+    class SpanLink
+      # @!attribute [r] span_id
+      #   Datadog id for the currently active span.
+      #   @return [Integer]
+      attr_reader :span_id
+
+      # @!attribute [r] trace_id
+      #   Datadog id for the currently active trace.
+      #   @return [Integer]
+      attr_reader :trace_id
+
+      # @!attribute [r] attributes
+      #   Datadog-specific tags that support richer distributed tracing association.
+      #   @return [Hash<String,String>]
+      attr_reader :attributes
+
+      # @!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
+      attr_reader :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
+      attr_reader :trace_state
+
+      # @!attribute [r] dropped_attributes
+      #   The number of attributes that were discarded due to serialization limits.
+      #   @return [Integer]
+      attr_reader :dropped_attributes
+
+      def initialize(
+        digest,
+        attributes: nil
+      )
+        @span_id = digest.span_id
+        @trace_id = digest.trace_id
+        @trace_flags = if digest.trace_sampling_priority.nil?
+          nil
+        elsif digest.trace_sampling_priority > 0
+          1
+        else
+          0
+        end
+        @trace_state = digest.trace_state&.dup
+        @dropped_attributes = 0
+        @attributes = attributes&.dup || {}
+      end
+
+      def to_hash
+        h = {
+          span_id: @span_id || 0,
+          trace_id: Tracing::Utils::TraceId.to_low_order(@trace_id) || 0,
+        }
+        # Optimization: Hash non empty attributes
+        if @trace_id.to_i > Tracing::Utils::EXTERNAL_MAX_ID
+          h[:trace_id_high] =
+            Tracing::Utils::TraceId.to_high_order(@trace_id)
+        end
+        unless @attributes&.empty?
+          h[:attributes] = {}
+          @attributes.each do |k1, v1|
+            Tracing::Utils.serialize_attribute(k1, v1).each do |new_k1, value|
+              h[:attributes][new_k1] = value.to_s
+            end
+          end
+        end
+        h[:dropped_attributes_count] = @dropped_attributes if @dropped_attributes > 0
+        h[:tracestate] = @trace_state if @trace_state
+        # If traceflags set, the high bit (bit 31) should be set to 1 (uint32).
+        # This helps us distinguish between when the sample decision is zero or not set
+        h[:flags] = if @trace_flags.nil?
+          0
+        else
+          @trace_flags | (1 << 31)
+        end
+        h
+      end
+    end
+  end
+end