datadog 2.23.0 → 2.24.0

data/lib/datadog/tracing/trace_operation.rb

@@ -55,6 +55,12 @@ module Datadog
         :sampled,
         :service
 
+      # Creates a new TraceOperation.
+      #
+      # @param auto_finish [Boolean] when true, automatically finishes the trace when the local root span finishes.
+      #   When false, the trace remains unfinished until {#finish!} is called.
+      #   This is useful when this {TraceOperation} represents the continuation of a remote {TraceDigest},
+      #   in which case local root spans in this {TraceOperation} are children of the {TraceDigest}'s last active span.
       def initialize(
         logger: Datadog.logger,
         agent_sample_rate: nil,
@@ -80,7 +86,8 @@ module Datadog
         trace_state_unknown_fields: nil,
         remote_parent: false,
         tracer: nil, # DEV-3.0: deprecated, remove in 3.0
-        baggage: nil
+        baggage: nil,
+        auto_finish: true
       )
         @logger = logger
 
@@ -119,6 +126,7 @@ module Datadog
         @events = events || Events.new
         @finished = false
         @spans = []
+        @auto_finish = !!auto_finish
       end
 
       def full?
@@ -318,6 +326,29 @@ module Datadog
         build_trace(spans, !finished)
       end
 
+      # When automatic context management is disabled (@auto_finish is false),
+      # this method finishes the trace, marking it as completed.
+      #
+      # The trace will **not** automatically finish when its local root span
+      # when @auto_finish is false, thus calling this method is mandatory
+      # in such scenario.
+      #
+      # Unfinished spans are discarded.
+      #
+      # This method is idempotent and safe to call after the trace is finished.
+      # It is also a no-op when @auto_finish is true, to prevent misuse.
+      #
+      # @!visibility private
+      def finish!
+        return if @auto_finish || finished?
+
+        @finished = true
+        @active_span = nil
+        @active_span_count = 0
+
+        events.trace_finished.publish(self)
+      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.
@@ -460,7 +491,7 @@ module Datadog
 
         @active_span = span_op
 
-        set_root_span!(span_op) unless root_span
+        set_local_root_span!(span_op)
       end
 
       def deactivate_span!(span_op)
@@ -483,6 +514,12 @@ module Datadog
         logger.debug { "Error starting span on trace: #{e} Backtrace: #{e.backtrace.first(3)}" }
       end
 
+      # For traces with automatic context management (auto_finish),
+      # when the local root span finishes, the trace also finishes.
+      # The trace cannot receive new spans after finished.
+      #
+      # Without auto_finish, the trace can still receive spans
+      # until explicitly finished.
       def finish_span(span, span_op, parent)
         # Save finished span & root span
         @spans << span unless span.nil?
@@ -490,8 +527,9 @@ module Datadog
         # 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
+        # Finish if the local root span is finished and automatic
+        # context management is enabled.
+        @finished = true if span_op == root_span && @auto_finish
 
         # Update active span count
         @active_span_count -= 1
@@ -505,8 +543,8 @@ module Datadog
         logger.debug { "Error finishing span on trace: #{e} Backtrace: #{e.backtrace.first(3)}" }
       end
 
-      # Track the root span
-      def set_root_span!(span)
+      # Track the root {SpanOperation} object from the current execution context.
+      def set_local_root_span!(span)
         return if span.nil? || root_span
 
         @root_span = span

data/lib/datadog/tracing/tracer.rb

@@ -129,7 +129,6 @@ module Datadog
       # @yield Optional block where new newly created {Datadog::Tracing::SpanOperation} captures the execution.
       # @yieldparam [Datadog::Tracing::SpanOperation] span_op the newly created and active [Datadog::Tracing::SpanOperation]
       # @yieldparam [Datadog::Tracing::TraceOperation] trace_op the active [Datadog::Tracing::TraceOperation]
-      # rubocop:disable Metrics/MethodLength
       def trace(
         name,
         continue_from: nil,
@@ -241,10 +240,21 @@ module Datadog
         trace.to_correlation
       end
 
-      # Setup a new trace to continue from where another
+      # Setup a new trace execution context to continue from where another
       # trace left off.
+      # This is useful to continue distributed or async traces.
       #
-      # Used to continue distributed or async traces.
+      # The first span created in the restored context is a direct child of the
+      # active span from when the {Datadog::Tracing::TraceDigest} was created.
+      #
+      # When no block is given, the trace context is restored in the current thread.
+      # It remains active until the first span created in this restored context is finished.
+      # After that, if a new span is created, it start a new, unrelated trace.
+      #
+      # When a block is given, the trace context is restored inside the block execution.
+      # It remains active until the block ends, even when the first span created inside
+      # the block finishes. This means that multiple spans can be direct children of the
+      # active span from when the {Datadog::Tracing::TraceDigest} was created.
       #
       # @param [Datadog::Tracing::TraceDigest] digest continue from the {Datadog::Tracing::TraceDigest}.
       # @param [Thread] key Thread to retrieve trace from. Defaults to current thread. For internal use only.
@@ -260,13 +270,32 @@ module Datadog
         # Start a new trace from the digest
         context = call_context(key)
         original_trace = active_trace(key)
-        trace = start_trace(continue_from: digest)
+        # When we want the trace to be bound to a block, we cannot let
+        # it auto finish when the local root span finishes. This would
+        # create mutiple traces inside the block. Instead, we'll
+        # expliclity finish the trace after the block finishes.
+        auto_finish = !block
+
+        trace = start_trace(continue_from: digest, auto_finish: auto_finish)
 
         # If block hasn't been given; we need to manually deactivate
         # this trace. Subscribe to the trace finished event to do this.
         subscribe_trace_deactivation!(context, trace, original_trace) unless block
 
-        context.activate!(trace, &block)
+        if block
+          # When a block is given, the trace will be active until the block finishes.
+          context.activate!(trace) do
+            yield
+          ensure # We have to flush even when an error occurs
+            # On block completion, force the trace to finish and flush its finished spans.
+            # Unfinished spans are lost as the {TraceOperation} has ended.
+            trace.finish!
+            flush_trace(trace)
+          end
+        else
+          # Otherwise, the trace will be bound to the current thread after this point
+          context.activate!(trace)
+        end
       end
 
       # Sample a span, tagging the trace as appropriate.
@@ -329,7 +358,7 @@ module Datadog
         @provider.context(key)
       end
 
-      def build_trace(digest = nil)
+      def build_trace(digest, auto_finish)
         # Resolve hostname if configured
         hostname = Core::Environment::Socket.hostname if Datadog.configuration.tracing.report_hostname
         hostname = (hostname && !hostname.empty?) ? hostname : nil
@@ -353,7 +382,8 @@ module Datadog
             trace_state_unknown_fields: digest.trace_state_unknown_fields,
             remote_parent: digest.span_remote,
             tracer: self,
-            baggage: digest.baggage
+            baggage: digest.baggage,
+            auto_finish: auto_finish
           )
         else
           TraceOperation.new(
@@ -362,13 +392,12 @@ module Datadog
             profiling_enabled: profiling_enabled,
             apm_tracing_enabled: apm_tracing_enabled,
             remote_parent: false,
-            tracer: self
+            tracer: self,
+            auto_finish: auto_finish
           )
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
-      # rubocop:disable Metrics/MethodLength
       def bind_trace_events!(trace_op)
         events = trace_op.send(:events)
 
@@ -387,13 +416,12 @@ module Datadog
           flush_trace(event_trace_op)
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Creates a new TraceOperation, with events bounds to this Tracer instance.
       # @return [TraceOperation]
-      def start_trace(continue_from: nil)
+      def start_trace(continue_from: nil, auto_finish: true)
         # Build a new trace using digest if provided.
-        trace = build_trace(continue_from)
+        trace = build_trace(continue_from, auto_finish)
 
         # Bind trace events: sample trace, set default service, flush spans.
         bind_trace_events!(trace)
@@ -402,7 +430,6 @@ module Datadog
       end
 
       # rubocop:disable Lint/UnderscorePrefixedVariableName
-      # rubocop:disable Metrics/MethodLength
       def start_span(
         name,
         continue_from: nil,
@@ -454,9 +481,8 @@ module Datadog
           span
         end
       end
-      # rubocop:enable Lint/UnderscorePrefixedVariableName
-      # rubocop:enable Metrics/MethodLength
 
+      # rubocop:enable Lint/UnderscorePrefixedVariableName
       def resolve_tags(tags, service)
         merged_tags = if @tags.any? && tags
           # Combine default tags with provided tags,

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

@@ -2,12 +2,10 @@
 
 require 'json'
 
-require_relative '../traces'
-require_relative 'client'
 require_relative '../../../core/transport/http/response'
 require_relative '../../../core/transport/http/api/endpoint'
-require_relative '../../../core/transport/http/api/spec'
 require_relative '../../../core/transport/http/api/instance'
+require_relative '../traces'
 
 module Datadog
   module Tracing
@@ -27,58 +25,15 @@ module Datadog
             end
           end
 
-          # Extensions for HTTP client
-          module Client
-            def send_traces_payload(request)
-              send_request(request) do |api, env|
-                api.send_traces(env)
-              end
-            end
-          end
-
           module API
-            # HTTP API Spec
-            class Spec < Core::Transport::HTTP::API::Spec
-              attr_accessor :traces
-
-              def send_traces(env, &block)
-                raise Core::Transport::HTTP::API::Spec::EndpointNotDefinedError.new('traces', self) if traces.nil?
-
-                traces.call(env, &block)
-              end
-
-              def encoder
-                traces.encoder
-              end
-            end
-
-            # HTTP API Instance
-            class Instance < Core::Transport::HTTP::API::Instance
-              def send_traces(env)
-                unless spec.is_a?(Traces::API::Spec)
-                  raise Core::Transport::HTTP::API::Instance::EndpointNotSupportedError.new(
-                    'traces', self
-                  )
-                end
-
-                spec.send_traces(env) do |request_env|
-                  call(request_env)
-                end
-              end
-            end
-
             # Endpoint for submitting trace data
             class Endpoint < Datadog::Core::Transport::HTTP::API::Endpoint
               HEADER_CONTENT_TYPE = 'Content-Type'
               HEADER_TRACE_COUNT = 'X-Datadog-Trace-Count'
               SERVICE_RATE_KEY = 'rate_by_service'
 
-              attr_reader \
-                :encoder
-
               def initialize(path, encoder, options = {})
-                super(:post, path)
-                @encoder = encoder
+                super(:post, path, encoder: encoder)
                 @service_rates = options.fetch(:service_rates, false)
               end
 
@@ -111,9 +66,6 @@ module Datadog
               end
             end
           end
-
-          # Add traces behavior to transport components
-          HTTP::Client.include(Traces::Client)
         end
       end
     end

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

@@ -1,17 +1,28 @@
 # frozen_string_literal: true
 
+require_relative '../../core/encoding'
 require_relative '../../core/environment/container'
 require_relative '../../core/environment/ext'
 require_relative '../../core/transport/ext'
 require_relative '../../core/transport/http'
-require_relative 'http/api'
-require_relative '../../../datadog/version'
+require_relative 'http/traces'
 
 module Datadog
   module Tracing
     module Transport
       # Namespace for HTTP transport components
       module HTTP
+        V4 = Traces::API::Endpoint.new(
+          '/v0.4/traces',
+          Core::Encoding::MsgpackEncoder,
+          service_rates: true
+        )
+
+        V3 = Traces::API::Endpoint.new(
+          '/v0.3/traces',
+          Core::Encoding::MsgpackEncoder,
+        )
+
         module_function
 
         # Builds a new Transport::HTTP::Client with default settings
@@ -19,20 +30,15 @@ module Datadog
         def default(
           agent_settings:,
           logger: Datadog.logger,
-          api_version: nil,
           headers: nil
         )
           Core::Transport::HTTP.build(
-            api_instance_class: Traces::API::Instance,
             agent_settings: agent_settings,
             logger: logger,
-            api_version: api_version,
             headers: headers
           ) do |transport|
-            apis = API.defaults
-
-            transport.api API::V4, apis[API::V4], fallback: API::V3, default: true
-            transport.api API::V3, apis[API::V3]
+            transport.api 'v0.4', V4, fallback: 'v0.3', default: true
+            transport.api 'v0.3', V3
 
             # Call block to apply any customization, if provided
             yield(transport) if block_given?

data/lib/datadog/tracing/transport/io/client.rb

@@ -42,7 +42,7 @@ module Datadog
             response
           rescue => e
             message =
-              "Internal error during IO transport request. Cause: #{e.class.name} #{e.message} " \
+              "Internal error during IO transport request. Cause: #{e.class.name}: #{e.message} " \
                 "Location: #{Array(e.backtrace).first}"
 
             # Log error

data/lib/datadog/tracing/transport/traces.rb

@@ -3,7 +3,9 @@
 require_relative '../../core/chunker'
 require_relative '../../core/transport/parcel'
 require_relative '../../core/transport/request'
+require_relative '../../core/transport/transport'
 require_relative '../../core/utils/array'
+require_relative 'http/client'
 require_relative 'serializable_trace'
 require_relative 'trace_formatter'
 
@@ -121,16 +123,8 @@ module Datadog
         # This class initializes the HTTP client, breaks down large
         # batches of traces into smaller chunks and handles
         # API version downgrade handshake.
-        class Transport
-          attr_reader :client, :apis, :default_api, :current_api_id, :logger
-
-          def initialize(apis, default_api, logger: Datadog.logger)
-            @apis = apis
-            @default_api = default_api
-            @logger = logger
-
-            change_api!(default_api)
-          end
+        class Transport < Core::Transport::Transport
+          self.http_client_class = Tracing::Transport::HTTP::Client
 
           def send_traces(traces)
             encoder = current_api.encoder
@@ -143,7 +137,7 @@ module Datadog
             responses = chunker.encode_in_chunks(traces.lazy).map do |encoded_traces, trace_count|
               request = Request.new(EncodedParcel.new(encoded_traces, trace_count))
 
-              client.send_traces_payload(request).tap do |response|
+              client.send_request(:traces, request).tap do |response|
                 if downgrade?(response)
                   downgrade!
                   return send_traces(traces)
@@ -171,35 +165,11 @@ module Datadog
           end
 
           def stats
-            @client.stats
-          end
-
-          def current_api
-            apis[@current_api_id]
+            client.stats
           end
 
           private
 
-          def downgrade?(response)
-            return false unless apis.fallbacks.key?(@current_api_id)
-
-            response.not_found? || response.unsupported?
-          end
-
-          def downgrade!
-            downgrade_api_id = apis.fallbacks[@current_api_id]
-            raise NoDowngradeAvailableError, @current_api_id if downgrade_api_id.nil?
-
-            change_api!(downgrade_api_id)
-          end
-
-          def change_api!(api_id)
-            raise UnknownApiVersionError, api_id unless apis.key?(api_id)
-
-            @current_api_id = api_id
-            @client = HTTP::Client.new(current_api, logger: logger)
-          end
-
           # Queries the agent for native span events serialization support.
           # This changes how the serialization of span events performed.
           def native_events_supported?
@@ -219,36 +189,6 @@ module Datadog
               false
             end
           end
-
-          # Raised when configured with an unknown API version
-          class UnknownApiVersionError < StandardError
-            attr_reader :version
-
-            def initialize(version)
-              super
-
-              @version = version
-            end
-
-            def message
-              "No matching transport API for version #{version}!"
-            end
-          end
-
-          # Raised when configured with an unknown API version
-          class NoDowngradeAvailableError < StandardError
-            attr_reader :version
-
-            def initialize(version)
-              super
-
-              @version = version
-            end
-
-            def message
-              "No downgrade from transport API version #{version} is available!"
-            end
-          end
         end
       end
     end

data/lib/datadog/tracing/workers/trace_writer.rb

@@ -21,6 +21,8 @@ module Datadog
           :transport,
           :agent_settings
 
+        # DEV-3.0: change to keyword arguments
+        #
         # rubocop:disable Lint/MissingSuper
         def initialize(options = {})
           @logger = options[:logger] || Datadog.logger
@@ -143,6 +145,9 @@ module Datadog
 
         # Are there more traces to be processed next?
         def work_pending?
+          # This is the same implementation as in Queue, but it was
+          # overwritten by IntervalLoop on its way to this worker class.
+          # See the comments in those two methods for more info.
           !buffer.empty?
         end
 

data/lib/datadog/tracing/writer.rb

@@ -19,6 +19,7 @@ module Datadog
         :events,
         :agent_settings
 
+      # DEV-3.0: change to keyword arguments
       def initialize(options = {})
         @logger = options[:logger] || Datadog.logger
 

data/lib/datadog/version.rb

@@ -3,7 +3,7 @@
 module Datadog
   module VERSION
     MAJOR = 2
-    MINOR = 23
+    MINOR = 24
     PATCH = 0
     PRE = nil
     BUILD = nil
@@ -21,6 +21,6 @@ module Datadog
     # To allow testing with the next unreleased version of Ruby, the version check is performed
     # as `< #{MAXIMUM_RUBY_VERSION}`, meaning prereleases of MAXIMUM_RUBY_VERSION are allowed
     # but not stable MAXIMUM_RUBY_VERSION releases.
-    MAXIMUM_RUBY_VERSION = '4.0'
+    MAXIMUM_RUBY_VERSION = '4.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: datadog
 version: !ruby/object:Gem::Version
-  version: 2.23.0
+  version: 2.24.0
 platform: ruby
 authors:
 - Datadog, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-11 00:00:00.000000000 Z
+date: 2026-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -139,6 +139,7 @@ files:
 - ext/datadog_profiling_native_extension/collectors_stack.h
 - ext/datadog_profiling_native_extension/collectors_thread_context.c
 - ext/datadog_profiling_native_extension/collectors_thread_context.h
+- ext/datadog_profiling_native_extension/crashtracking_runtime_stacks.c
 - ext/datadog_profiling_native_extension/datadog_ruby_common.c
 - ext/datadog_profiling_native_extension/datadog_ruby_common.h
 - ext/datadog_profiling_native_extension/encoded_profile.c
@@ -374,7 +375,6 @@ files:
 - lib/datadog/core/remote/tie/tracing.rb
 - lib/datadog/core/remote/transport/config.rb
 - lib/datadog/core/remote/transport/http.rb
-- lib/datadog/core/remote/transport/http/api.rb
 - lib/datadog/core/remote/transport/http/config.rb
 - lib/datadog/core/remote/transport/http/negotiation.rb
 - lib/datadog/core/remote/transport/negotiation.rb
@@ -409,7 +409,6 @@ files:
 - lib/datadog/core/telemetry/metrics_manager.rb
 - lib/datadog/core/telemetry/request.rb
 - lib/datadog/core/telemetry/transport/http.rb
-- lib/datadog/core/telemetry/transport/http/api.rb
 - lib/datadog/core/telemetry/transport/http/telemetry.rb
 - lib/datadog/core/telemetry/transport/telemetry.rb
 - lib/datadog/core/telemetry/worker.rb
@@ -423,7 +422,6 @@ files:
 - lib/datadog/core/transport/http/api/fallbacks.rb
 - lib/datadog/core/transport/http/api/instance.rb
 - lib/datadog/core/transport/http/api/map.rb
-- lib/datadog/core/transport/http/api/spec.rb
 - lib/datadog/core/transport/http/builder.rb
 - lib/datadog/core/transport/http/client.rb
 - lib/datadog/core/transport/http/env.rb
@@ -431,6 +429,7 @@ files:
 - lib/datadog/core/transport/parcel.rb
 - lib/datadog/core/transport/request.rb
 - lib/datadog/core/transport/response.rb
+- lib/datadog/core/transport/transport.rb
 - lib/datadog/core/utils.rb
 - lib/datadog/core/utils/array.rb
 - lib/datadog/core/utils/at_fork_monkey_patch.rb
@@ -469,8 +468,6 @@ files:
 - lib/datadog/data_streams/pathway_context.rb
 - lib/datadog/data_streams/processor.rb
 - lib/datadog/data_streams/transport/http.rb
-- lib/datadog/data_streams/transport/http/api.rb
-- lib/datadog/data_streams/transport/http/client.rb
 - lib/datadog/data_streams/transport/http/stats.rb
 - lib/datadog/data_streams/transport/stats.rb
 - lib/datadog/di.rb
@@ -506,7 +503,6 @@ files:
 - lib/datadog/di/serializer.rb
 - lib/datadog/di/transport/diagnostics.rb
 - lib/datadog/di/transport/http.rb
-- lib/datadog/di/transport/http/api.rb
 - lib/datadog/di/transport/http/diagnostics.rb
 - lib/datadog/di/transport/http/input.rb
 - lib/datadog/di/transport/input.rb
@@ -543,7 +539,6 @@ files:
 - lib/datadog/open_feature/transport.rb
 - lib/datadog/opentelemetry.rb
 - lib/datadog/opentelemetry/api/baggage.rb
-- lib/datadog/opentelemetry/api/baggage.rbs
 - lib/datadog/opentelemetry/api/context.rb
 - lib/datadog/opentelemetry/api/trace/span.rb
 - lib/datadog/opentelemetry/configuration/settings.rb
@@ -1060,7 +1055,6 @@ files:
 - lib/datadog/tracing/trace_segment.rb
 - lib/datadog/tracing/tracer.rb
 - lib/datadog/tracing/transport/http.rb
-- lib/datadog/tracing/transport/http/api.rb
 - lib/datadog/tracing/transport/http/client.rb
 - lib/datadog/tracing/transport/http/statistics.rb
 - lib/datadog/tracing/transport/http/traces.rb
@@ -1083,8 +1077,8 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/DataDog/dd-trace-rb/blob/v2.23.0/CHANGELOG.md
-  source_code_uri: https://github.com/DataDog/dd-trace-rb/tree/v2.23.0
+  changelog_uri: https://github.com/DataDog/dd-trace-rb/blob/v2.24.0/CHANGELOG.md
+  source_code_uri: https://github.com/DataDog/dd-trace-rb/tree/v2.24.0
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -1096,7 +1090,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.5.0
   - - "<"
     - !ruby/object:Gem::Version
-      version: '4.0'
+      version: '4.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="