ddtrace 0.54.0 → 1.0.0

data/lib/datadog/tracing/trace_operation.rb

@@ -0,0 +1,432 @@
+# typed: false
+
+require 'datadog/core'
+require 'datadog/core/environment/identity'
+require 'datadog/core/utils'
+
+require 'datadog/tracing/sampling/ext'
+require 'datadog/tracing/event'
+require 'datadog/tracing/span_operation'
+require 'datadog/tracing/trace_segment'
+require 'datadog/tracing/trace_digest'
+require 'datadog/tracing/metadata/tagging'
+
+module Datadog
+  module Tracing
+    # Represents the act of tracing a series of operations,
+    # by generating and collecting span measurements.
+    # When completed, it yields a trace.
+    #
+    # Supports synchronous code flow *only*. Usage across
+    # multiple threads will result in incorrect relationships.
+    # 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
+
+      DEFAULT_MAX_LENGTH = 100_000
+
+      attr_accessor \
+        :agent_sample_rate,
+        :hostname,
+        :origin,
+        :rate_limiter_rate,
+        :rule_sample_rate,
+        :sample_rate,
+        :sampling_priority
+
+      attr_reader \
+        :active_span_count,
+        :active_span,
+        :id,
+        :max_length,
+        :parent_span_id
+
+      attr_writer \
+        :name,
+        :resource,
+        :sampled,
+        :service
+
+      def initialize(
+        agent_sample_rate: nil,
+        events: nil,
+        hostname: nil,
+        id: nil,
+        max_length: DEFAULT_MAX_LENGTH,
+        name: nil,
+        origin: nil,
+        parent_span_id: nil,
+        rate_limiter_rate: nil,
+        resource: nil,
+        rule_sample_rate: nil,
+        sample_rate: nil,
+        sampled: nil,
+        sampling_priority: nil,
+        service: nil,
+        tags: nil,
+        metrics: nil
+      )
+        # Attributes
+        @events = events || Events.new
+        @id = id || Core::Utils.next_id
+        @max_length = max_length || DEFAULT_MAX_LENGTH
+        @parent_span_id = parent_span_id
+        @sampled = sampled.nil? ? false : sampled
+
+        # Tags
+        @agent_sample_rate = agent_sample_rate
+        @hostname = hostname
+        @name = name
+        @origin = origin
+        @rate_limiter_rate = rate_limiter_rate
+        @resource = resource
+        @rule_sample_rate = rule_sample_rate
+        @sample_rate = sample_rate
+        @sampling_priority = sampling_priority
+        @service = service
+
+        # Generic tags
+        set_tags(tags) if tags
+        set_tags(metrics) if metrics
+
+        # State
+        @root_span = nil
+        @active_span = nil
+        @active_span_count = 0
+        @events = events || Events.new
+        @finished = false
+        @spans = []
+      end
+
+      def full?
+        @max_length > 0 && @active_span_count >= @max_length
+      end
+
+      def finished_span_count
+        @spans.length
+      end
+
+      def finished?
+        @finished == true
+      end
+
+      def sampled?
+        @sampled == true || (!@sampling_priority.nil? && @sampling_priority > 0)
+      end
+
+      def keep!
+        self.sampled = true
+        self.sampling_priority = Sampling::Ext::Priority::USER_KEEP
+      end
+
+      def reject!
+        self.sampled = false
+        self.sampling_priority = Sampling::Ext::Priority::USER_REJECT
+      end
+
+      def name
+        @name || (root_span && root_span.name)
+      end
+
+      def resource
+        @resource || (root_span && root_span.resource)
+      end
+
+      def service
+        @service || (root_span && root_span.service)
+      end
+
+      def measure(
+        op_name,
+        events: nil,
+        on_error: nil,
+        resource: nil,
+        service: nil,
+        start_time: nil,
+        tags: nil,
+        type: nil,
+        &block
+      )
+        # Don't allow more span measurements if the
+        # trace is already completed. Prevents multiple
+        # root spans with parent_span_id = 0.
+        return yield(SpanOperation.new(op_name), TraceOperation.new) if finished? || full?
+
+        # Create new span
+        span_op = build_span(
+          op_name,
+          events: events,
+          on_error: on_error,
+          resource: resource,
+          service: service,
+          start_time: start_time,
+          tags: tags,
+          type: type
+        )
+
+        # Start span measurement
+        span_op.measure { |s| yield(s, self) }
+      end
+
+      def build_span(
+        op_name,
+        events: nil,
+        on_error: nil,
+        resource: nil,
+        service: nil,
+        start_time: nil,
+        tags: nil,
+        type: nil
+      )
+        begin
+          # Resolve span options:
+          # Parent, service name, etc.
+          # Add default options
+          trace_id = @id
+          parent = @active_span
+
+          # Use active span's span ID if available. Otherwise, the parent span ID.
+          # Necessary when this trace continues from another, e.g. distributed trace.
+          parent_id = parent ? parent.id : @parent_span_id || 0
+
+          # Build events
+          events ||= SpanOperation::Events.new
+
+          # Before start: activate the span, publish events.
+          events.before_start.subscribe do |span_op|
+            start_span(span_op)
+          end
+
+          # After finish: deactivate the span, record, publish events.
+          events.after_finish.subscribe do |span, span_op|
+            finish_span(span, span_op, parent)
+          end
+
+          # Build a new span operation
+          SpanOperation.new(
+            op_name,
+            events: events,
+            on_error: on_error,
+            parent_id: parent_id,
+            resource: resource || op_name,
+            service: service,
+            start_time: start_time,
+            tags: tags,
+            trace_id: trace_id,
+            type: type
+          )
+        rescue StandardError => e
+          Datadog.logger.debug { "Failed to build new span: #{e}" }
+
+          # Return dummy span
+          SpanOperation.new(op_name)
+        end
+      end
+
+      def flush!
+        finished = finished?
+
+        # Copy out completed spans
+        spans = @spans.dup
+        @spans = []
+
+        # Use them to build a trace
+        build_trace(spans, !finished)
+      end
+
+      # Returns a set of trace headers used for continuing traces.
+      # Used for propagation across execution contexts.
+      # Data should reflect the active state of the trace.
+      def to_digest
+        # Resolve current span ID
+        span_id = @active_span && @active_span.id
+        span_id ||= @parent_span_id unless finished?
+
+        TraceDigest.new(
+          span_id: span_id,
+          span_name: (@active_span && @active_span.name),
+          span_resource: (@active_span && @active_span.resource),
+          span_service: (@active_span && @active_span.service),
+          span_type: (@active_span && @active_span.type),
+          trace_hostname: @hostname,
+          trace_id: @id,
+          trace_name: name,
+          trace_origin: @origin,
+          trace_process_id: Core::Environment::Identity.pid,
+          trace_resource: resource,
+          trace_runtime_id: Core::Environment::Identity.id,
+          trace_sampling_priority: @sampling_priority,
+          trace_service: service,
+        ).freeze
+      end
+
+      # Returns a copy of this trace suitable for forks (w/o spans.)
+      # Used for continuation of traces across forks.
+      def fork_clone
+        self.class.new(
+          agent_sample_rate: @agent_sample_rate,
+          events: (@events && @events.dup),
+          hostname: (@hostname && @hostname.dup),
+          id: @id,
+          max_length: @max_length,
+          name: (name && name.dup),
+          origin: (@origin && @origin.dup),
+          parent_span_id: (@active_span && @active_span.id) || @parent_span_id,
+          rate_limiter_rate: @rate_limiter_rate,
+          resource: (resource && resource.dup),
+          rule_sample_rate: @rule_sample_rate,
+          sample_rate: @sample_rate,
+          sampled: @sampled,
+          sampling_priority: @sampling_priority,
+          service: (service && service.dup),
+          tags: meta.dup,
+          metrics: metrics.dup
+        )
+      end
+
+      # Callback behavior
+      class Events
+        include Tracing::Events
+
+        attr_reader \
+          :span_before_start,
+          :span_finished,
+          :trace_finished
+
+        def initialize
+          @span_before_start = SpanBeforeStart.new
+          @span_finished = SpanFinished.new
+          @trace_finished = TraceFinished.new
+        end
+
+        # Triggered before a span starts.
+        class SpanBeforeStart < Tracing::Event
+          def initialize
+            super(:span_before_start)
+          end
+        end
+
+        # Triggered when a span finishes, regardless of error.
+        class SpanFinished < Tracing::Event
+          def initialize
+            super(:span_finished)
+          end
+        end
+
+        # Triggered when the trace finishes, regardless of error.
+        class TraceFinished < Tracing::Event
+          def initialize
+            super(:trace_finished)
+            @deactivate_trace_subscribed = false
+          end
+
+          def deactivate_trace_subscribed?
+            @deactivate_trace_subscribed
+          end
+
+          def subscribe_deactivate_trace(&block)
+            @deactivate_trace_subscribed = true
+            subscribe(&block)
+          end
+        end
+      end
+
+      private
+
+      attr_reader \
+        :events,
+        :root_span
+
+      def activate_span!(span_op)
+        parent = @active_span
+
+        span_op.send(:parent=, parent) unless parent.nil?
+
+        @active_span = span_op
+
+        set_root_span!(span_op) unless root_span
+      end
+
+      def deactivate_span!(span_op)
+        # Set parent to closest unfinished ancestor span.
+        # Prevents wrong span from being set as the active span
+        # when spans finish out of order.
+        span_op = span_op.send(:parent) while !span_op.nil? && span_op.finished?
+        @active_span = span_op
+      end
+
+      def start_span(span_op)
+        begin
+          activate_span!(span_op)
+
+          # Update active span count
+          @active_span_count += 1
+
+          # Publish :span_before_start event
+          events.span_before_start.publish(span_op, self)
+        rescue StandardError => e
+          Datadog.logger.debug { "Error starting span on trace: #{e} Backtrace: #{e.backtrace.first(3)}" }
+        end
+      end
+
+      def finish_span(span, span_op, parent)
+        begin
+          # Save finished span & root span
+          @spans << span unless span.nil?
+
+          # Deactivate the span, re-activate parent.
+          deactivate_span!(span_op)
+
+          # Set finished, to signal root span has completed.
+          @finished = true if span_op == root_span
+
+          # Update active span count
+          @active_span_count -= 1
+
+          # Publish :span_finished event
+          events.span_finished.publish(span, self)
+
+          # Publish :trace_finished event
+          events.trace_finished.publish(self) if finished?
+        rescue StandardError => e
+          Datadog.logger.debug { "Error finishing span on trace: #{e} Backtrace: #{e.backtrace.first(3)}" }
+        end
+      end
+
+      # Track the root span
+      def set_root_span!(span)
+        return if span.nil? || root_span
+
+        @root_span = span
+      end
+
+      def build_trace(spans, partial = false)
+        TraceSegment.new(
+          spans,
+          agent_sample_rate: @agent_sample_rate,
+          hostname: @hostname,
+          id: @id,
+          lang: Core::Environment::Identity.lang,
+          origin: @origin,
+          process_id: Core::Environment::Identity.pid,
+          rate_limiter_rate: @rate_limiter_rate,
+          rule_sample_rate: @rule_sample_rate,
+          runtime_id: Core::Environment::Identity.id,
+          sample_rate: @sample_rate,
+          sampling_priority: @sampling_priority,
+          name: name,
+          resource: resource,
+          service: service,
+          tags: meta,
+          metrics: metrics,
+          root_span_id: !partial ? root_span && root_span.id : nil
+        )
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/datadog/tracing/trace_segment.rb

@@ -0,0 +1,207 @@
+# typed: true
+
+require 'datadog/core/runtime/ext'
+require 'datadog/core/utils/safe_dup'
+
+require 'datadog/tracing/sampling/ext'
+require 'datadog/tracing/metadata/ext'
+require 'datadog/tracing/metadata/tagging'
+
+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
+      TAG_SERVICE = 'service'.freeze
+
+      attr_reader \
+        :id,
+        :spans,
+        :agent_sample_rate,
+        :hostname,
+        :lang,
+        :name,
+        :origin,
+        :process_id,
+        :rate_limiter_rate,
+        :resource,
+        :rule_sample_rate,
+        :runtime_id,
+        :sample_rate,
+        :sampling_priority,
+        :service
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      def initialize(
+        spans,
+        agent_sample_rate: nil,
+        hostname: nil,
+        id: nil,
+        lang: nil,
+        name: nil,
+        origin: nil,
+        process_id: nil,
+        rate_limiter_rate: nil,
+        resource: nil,
+        root_span_id: nil,
+        rule_sample_rate: nil,
+        runtime_id: nil,
+        sample_rate: nil,
+        sampling_priority: nil,
+        service: nil,
+        tags: nil,
+        metrics: nil
+      )
+        @id = id
+        @root_span_id = root_span_id
+        @spans = spans || []
+
+        # Does not make an effort to move metrics out of tags
+        # The caller is expected to have done that
+        @meta = (tags && tags.dup) || {}
+        @metrics = (metrics && metrics.dup) || {}
+
+        # Set well-known tags, defaulting to getting the values from tags
+        @agent_sample_rate = agent_sample_rate || agent_sample_rate_tag
+        @hostname = hostname || hostname_tag
+        @lang = lang || lang_tag
+        @name = Core::Utils::SafeDup.frozen_or_dup(name || name_tag)
+        @origin = Core::Utils::SafeDup.frozen_or_dup(origin || origin_tag)
+        @process_id = process_id || process_id_tag
+        @rate_limiter_rate = rate_limiter_rate || rate_limiter_rate_tag
+        @resource = Core::Utils::SafeDup.frozen_or_dup(resource || resource_tag)
+        @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_priority = sampling_priority || sampling_priority_tag
+        @service = Core::Utils::SafeDup.frozen_or_dup(service || service_tag)
+      end
+      # rubocop:enable Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      def any?
+        @spans.any?
+      end
+
+      def count
+        @spans.count
+      end
+
+      def empty?
+        @spans.empty?
+      end
+
+      def length
+        @spans.length
+      end
+
+      def size
+        @spans.size
+      end
+
+      # If an active trace is present, forces it to be retained by the Datadog backend.
+      #
+      # Any sampling logic will not be able to change this decision.
+      #
+      # @return [void]
+      def keep!
+        self.sampling_priority = Sampling::Ext::Priority::USER_KEEP
+      end
+
+      # If an active trace is present, forces it to be dropped and not stored by the Datadog backend.
+      #
+      # Any sampling logic will not be able to change this decision.
+      #
+      # @return [void]
+      def reject!
+        self.sampling_priority = Sampling::Ext::Priority::USER_REJECT
+      end
+
+      def sampled?
+        sampling_priority == Sampling::Ext::Priority::AUTO_KEEP \
+          || sampling_priority == Sampling::Ext::Priority::USER_KEEP
+      end
+
+      protected
+
+      attr_reader \
+        :root_span_id,
+        :meta,
+        :metrics
+
+      private
+
+      attr_writer \
+        :agent_sample_rate,
+        :hostname,
+        :lang,
+        :name,
+        :origin,
+        :process_id,
+        :rate_limiter_rate,
+        :resource,
+        :rule_sample_rate,
+        :runtime_id,
+        :sample_rate,
+        :sampling_priority,
+        :service
+
+      def agent_sample_rate_tag
+        metrics[Metadata::Ext::Sampling::TAG_AGENT_RATE]
+      end
+
+      def hostname_tag
+        meta[Metadata::Ext::NET::TAG_HOSTNAME]
+      end
+
+      def lang_tag
+        meta[Core::Runtime::Ext::TAG_LANG]
+      end
+
+      def name_tag
+        meta[TAG_NAME]
+      end
+
+      def origin_tag
+        meta[Metadata::Ext::Distributed::TAG_ORIGIN]
+      end
+
+      def process_id_tag
+        meta[Core::Runtime::Ext::TAG_PID]
+      end
+
+      def rate_limiter_rate_tag
+        metrics[Metadata::Ext::Sampling::TAG_RATE_LIMITER_RATE]
+      end
+
+      def resource_tag
+        meta[TAG_RESOURCE]
+      end
+
+      def rule_sample_rate_tag
+        metrics[Metadata::Ext::Sampling::TAG_RULE_SAMPLE_RATE]
+      end
+
+      def runtime_id_tag
+        meta[Core::Runtime::Ext::TAG_ID]
+      end
+
+      def sample_rate_tag
+        metrics[Metadata::Ext::Sampling::TAG_SAMPLE_RATE]
+      end
+
+      def sampling_priority_tag
+        meta[Metadata::Ext::Distributed::TAG_SAMPLING_PRIORITY]
+      end
+
+      def service_tag
+        meta[TAG_SERVICE]
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end