datadog 2.46.0 → 2.48.0

data/lib/datadog/appsec/metrics/telemetry_exporter.rb

@@ -20,7 +20,7 @@ module Datadog
               block_failure: "false",
               rate_limited: (!context.trace.sampled?).to_s,
               input_truncated: metrics.inputs_truncated.positive?.to_s,
-            }
+            },
           )
         end
 
@@ -31,14 +31,14 @@ module Datadog
           if context.span&.get_tag(Tracing::Metadata::Ext::HTTP::TAG_ROUTE).nil?
             AppSec.telemetry.inc(
               AppSec::Ext::TELEMETRY_METRICS_NAMESPACE, "api_security.missing_route", 1,
-              tags: {framework: web_framework}
+              tags: {framework: web_framework},
             )
           end
 
           metric_name = context.state[:schema_extracted] ? "schema" : "no_schema"
           AppSec.telemetry.inc(
             AppSec::Ext::TELEMETRY_METRICS_NAMESPACE, "api_security.request.#{metric_name}", 1,
-            tags: {framework: web_framework}
+            tags: {framework: web_framework},
           )
         end
       end

data/lib/datadog/appsec/monitor/gateway/watcher.rb

@@ -44,7 +44,7 @@ module Datadog
 
                 if result.match? || result.attributes.any?
                   context.events.push(
-                    AppSec::SecurityEvent.new(result, trace: context.trace, span: context.span)
+                    AppSec::SecurityEvent.new(result, trace: context.trace, span: context.span),
                   )
                 end
 
@@ -71,7 +71,7 @@ module Datadog
 
                 if result.match? || result.attributes.any?
                   context.events.push(
-                    AppSec::SecurityEvent.new(result, trace: context.trace, span: context.span)
+                    AppSec::SecurityEvent.new(result, trace: context.trace, span: context.span),
                   )
                 end
 

data/lib/datadog/appsec/processor/rule_loader.rb

@@ -17,7 +17,7 @@ module Datadog
               Datadog.logger.warn(
                 "The :risky Application Security Management ruleset has been deprecated and no longer available." \
                 "The `:recommended` ruleset will be used instead." \
-                "Please remove the `appsec.ruleset = :risky` setting from your Datadog.configure block."
+                "Please remove the `appsec.ruleset = :risky` setting from your Datadog.configure block.",
               )
               JSON.parse(Datadog::AppSec::Assets.waf_rules(:recommended))
             when String

data/lib/datadog/appsec/response.rb

@@ -42,7 +42,7 @@ module Datadog
             body: [
               content(
                 security_response_id: interrupt_params["security_response_id"],
-                content_type: content_type
+                content_type: content_type,
               ),
             ],
           )

data/lib/datadog/appsec/security_engine/engine.rb

@@ -32,7 +32,7 @@ module Datadog
             obfuscator: {
               key_regex: appsec_settings.obfuscator_key_regex,
               value_regex: appsec_settings.obfuscator_value_regex,
-            }
+            },
           )
 
           diagnostics = load_default_config(telemetry: telemetry)
@@ -71,7 +71,8 @@ module Datadog
           if is_ruleset_update &&
               (diagnostics.key?("error") ||
               diagnostics.dig("rules", "error") ||
-              diagnostics.dig("processors", "errors"))
+              diagnostics.dig("processors", "error"))
+            @waf_builder.remove_config_at_path(path)
             diagnostics = load_default_config(telemetry: AppSec.telemetry)
             @reconfigured_ruleset_version = diagnostics["ruleset_version"]
             report_configuration_diagnostics(diagnostics, action: "update", telemetry: AppSec.telemetry)
@@ -131,7 +132,7 @@ module Datadog
               waf_version: Datadog::AppSec::WAF::VERSION::BASE_STRING,
               event_rules_version: ruleset_version.to_s,
               success: success.to_s,
-            }
+            },
           )
         end
 
@@ -141,7 +142,7 @@ module Datadog
           # deprecated - ip and user id denylists should be configured via RC
           config["rules_data"] ||= AppSec::Processor::RuleLoader.load_data(
             ip_denylist: @default_ip_denylist,
-            user_id_denylist: @default_user_id_denylist
+            user_id_denylist: @default_user_id_denylist,
           )
 
           # deprecated - ip passlist should be configured via RC
@@ -162,7 +163,7 @@ module Datadog
           if diagnostics["error"]
             telemetry.inc(
               Ext::TELEMETRY_METRICS_NAMESPACE, "waf.config_errors", 1,
-              tags: common_tags.merge(scope: "top-level")
+              tags: common_tags.merge(scope: "top-level"),
             )
 
             telemetry.error(diagnostics["error"])
@@ -177,7 +178,7 @@ module Datadog
 
               telemetry.inc(
                 Ext::TELEMETRY_METRICS_NAMESPACE, "waf.config_errors", 1,
-                tags: common_tags.merge(config_key: config_key, scope: "top-level")
+                tags: common_tags.merge(config_key: config_key, scope: "top-level"),
               )
             elsif config_diagnostics["errors"]
               config_diagnostics["errors"].each do |error, config_ids|
@@ -186,7 +187,7 @@ module Datadog
 
               telemetry.inc(
                 Ext::TELEMETRY_METRICS_NAMESPACE, "waf.config_errors", config_diagnostics["errors"].count,
-                tags: common_tags.merge(config_key: config_key, scope: "item")
+                tags: common_tags.merge(config_key: config_key, scope: "item"),
               )
             end
           end

data/lib/datadog/appsec/security_engine/runner.rb

@@ -54,7 +54,7 @@ module Datadog
             timeout: result.timeout?,
             duration_ns: result.duration,
             duration_ext_ns: (stop_ns - start_ns),
-            input_truncated: result.input_truncated?
+            input_truncated: result.input_truncated?,
           )
         ensure
           @mutex.unlock
@@ -89,7 +89,7 @@ module Datadog
             attributes: {},
             duration: 0,
             keep: false,
-            timeout: false
+            timeout: false,
           )
         end
 

data/lib/datadog/appsec/trace_keeper.rb

@@ -20,7 +20,7 @@ module Datadog
         if previous_dm.nil? || previous_dm == Tracing::Sampling::Ext::Decision::MANUAL
           trace.set_tag(
             Tracing::Metadata::Ext::Distributed::TAG_DECISION_MAKER,
-            Tracing::Sampling::Ext::Decision::ASM
+            Tracing::Sampling::Ext::Decision::ASM,
           )
         else
           trace.set_tag(

data/lib/datadog/appsec.rb

@@ -17,7 +17,7 @@ module Datadog
       def rasp_enabled?
         # TODO this should take rasp_enabled flag from the settings in
         # the appsec component rather than reading global configuration.
-        enabled? && Datadog.configuration.appsec.rasp_enabled
+        !!(enabled? && Datadog.configuration.appsec.rasp_enabled)
       end
 
       def active_context

data/lib/datadog/core/configuration/agent_settings_resolver.rb

@@ -60,16 +60,16 @@ module Datadog
           @configured_hostname = pick_from(
             DetectedConfiguration.new(
               friendly_name: "'c.agent.host'",
-              value: settings.agent.host
+              value: settings.agent.host,
             ),
             DetectedConfiguration.new(
               friendly_name: "#{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_URL} environment variable",
-              value: parsed_http_url&.hostname
+              value: parsed_http_url&.hostname,
             ),
             DetectedConfiguration.new(
               friendly_name: "#{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_HOST} environment variable",
-              value: DATADOG_ENV[Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_HOST]
-            )
+              value: DATADOG_ENV[Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_HOST],
+            ),
           )
         end
 
@@ -88,7 +88,7 @@ module Datadog
             try_parsing_as_integer(
               friendly_name: "#{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_PORT} environment variable",
               value: DATADOG_ENV[Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_PORT],
-            )
+            ),
           )
         end
 
@@ -103,7 +103,7 @@ module Datadog
             DetectedConfiguration.new(
               friendly_name: "#{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_URL} environment variable",
               value: parsed_url_ssl?,
-            )
+            ),
           )
         end
 
@@ -119,7 +119,7 @@ module Datadog
               friendly_name: "#{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_TIMEOUT_SECONDS} " \
                 "environment variable",
               value: DATADOG_ENV[Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_TIMEOUT_SECONDS],
-            )
+            ),
           )
         end
 
@@ -129,12 +129,12 @@ module Datadog
           @configured_uds_path = pick_from(
             DetectedConfiguration.new(
               friendly_name: "'c.agent.uds_path'",
-              value: settings.agent.uds_path
+              value: settings.agent.uds_path,
             ),
             DetectedConfiguration.new(
               friendly_name: "#{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_URL} environment variable",
-              value: parsed_url_uds_path
-            )
+              value: parsed_url_uds_path,
+            ),
           )
         end
 
@@ -239,7 +239,7 @@ module Datadog
                   friendly_name: "configuration of hostname/port for http/https use",
                   value: "hostname: '#{hostname}', port: '#{port}'",
                 ),
-              ]
+              ],
             )
           end
 
@@ -269,7 +269,7 @@ module Datadog
                 log_warning(
                   "Invalid URI scheme '#{parsed.scheme}' for #{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_URL} " \
                   "environment variable ('#{unparsed_url_from_env}'). " \
-                  "Ignoring the contents of #{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_URL}."
+                  "Ignoring the contents of #{Datadog::Core::Configuration::Ext::Agent::ENV_DEFAULT_URL}.",
                 )
                 # rubocop:enable Layout/LineLength
 
@@ -297,7 +297,8 @@ module Datadog
             "Configuration mismatch: values differ between " \
             "#{detected_configurations_in_priority_order
               .map { |config| "#{config.friendly_name} (#{config.value.inspect})" }.join(" and ")}" \
-            ". Using #{detected_configurations_in_priority_order.first.value.inspect} and ignoring other configuration."
+            ". Using #{detected_configurations_in_priority_order.first.value.inspect} and ignoring " \
+            "other configuration.",
           )
         end
 

data/lib/datadog/core/configuration/agentless_settings_resolver.rb

@@ -48,7 +48,7 @@ module Datadog
             host_prefix: host_prefix,
             url_override: url_override,
             url_override_source: url_override_source,
-            logger: logger
+            logger: logger,
           ).send(:call)
         end
 
@@ -162,7 +162,7 @@ module Datadog
               else
                 log_warning(
                   "Invalid URI scheme '#{parsed.scheme}' for #{url_override_source}. " \
-                  "Ignoring the contents of #{url_override_source}."
+                  "Ignoring the contents of #{url_override_source}.",
                 )
                 nil
               end

data/lib/datadog/core/configuration/components.rb

@@ -55,7 +55,7 @@ module Datadog
           # extension, remote config off, non-MRI). Under the always-build model
           # it is non-nil even when the DI setting defaults to off, so a built
           # SymbolDatabase component is inert until an upload is actually
-          # permitted: the component's own gate (see Component#upload_allowed?)
+          # permitted: the component's own gate, SymbolDatabase::Component#upload_allowed?,
           # only extracts and uploads when DI is truly active or the customer
           # opted in explicitly. This mirrors DI advertising/building a component
           # by default while installing no probes until it is enabled.
@@ -129,7 +129,7 @@ module Datadog
               logger: logger,
               settings: settings,
               agent_settings: agent_settings,
-              agent_info: agent_info
+              agent_info: agent_info,
             )
           rescue => e
             logger.warn("Failed to initialize Data Streams Monitoring: #{e.class}: #{e.message}")
@@ -288,12 +288,20 @@ module Datadog
             end
           end
 
+          if dynamic_instrumentation && old_state
+            dynamic_instrumentation.record_rc_enablement_signal_paths(old_state.rc_enablement_signal_paths)
+          end
+
           if remote && old_state&.remote_started?
             # The library was reconfigured and previously it already started
             # the remote component (i.e., it received at least one request
             # through the installed Rack middleware which started the remote).
             # If the new configuration also has remote enabled, start the
             # new remote right away.
+            #
+            # The DI signal-path restore above must precede this: the
+            # replacement client's first sync can dispatch the APM_TRACING
+            # merge, whose withdrawal branch reads the recorded paths.
             remote.start
           end
 
@@ -405,19 +413,12 @@ module Datadog
           # di_implicitly_enabled distinguishes RC-driven start from explicit
           # start (env var or programmatic) so that an explicit
           # `enabled = false` on reconfiguration can take effect.
-          #
-          # using_default? — not `!enabled` — because Datadog.configure has
-          # already mutated the singleton settings by the time #state runs,
-          # so `!enabled` would treat a customer's explicit
-          # `enabled = false` as "implicitly enabled" and restart DI.
-          # using_default? asks "did the customer ever touch this setting",
-          # which is the right question for RC carry-over.
-          di_implicit = dynamic_instrumentation&.started? &&
-            @settings.dynamic_instrumentation.using_default?(:enabled)
+          di_implicit = dynamic_instrumentation&.implicitly_enabled?
           ComponentsState.new(
             telemetry_enabled: telemetry.enabled,
             remote_started: remote&.started?,
             di_implicitly_enabled: di_implicit || false,
+            rc_enablement_signal_paths: dynamic_instrumentation&.rc_enablement_signal_paths || [],
           )
         end
 

data/lib/datadog/core/configuration/components_state.rb

@@ -5,10 +5,12 @@ module Datadog
     module Configuration
       # Stores the state of component tree when replacing the tree.
       class ComponentsState
-        def initialize(telemetry_enabled:, remote_started:, di_implicitly_enabled: false)
+        def initialize(telemetry_enabled:, remote_started:, di_implicitly_enabled: false,
+          rc_enablement_signal_paths: [])
           @telemetry_enabled = !!telemetry_enabled
           @remote_started = !!remote_started
           @di_implicitly_enabled = !!di_implicitly_enabled
+          @rc_enablement_signal_paths = rc_enablement_signal_paths || []
         end
 
         def telemetry_enabled?
@@ -22,6 +24,11 @@ module Datadog
         def di_implicitly_enabled?
           @di_implicitly_enabled
         end
+
+        # The RC enable-signal carrier paths recorded by the replaced tree's DI component.
+        #
+        # @return [Array<Core::Remote::Configuration::Path>]
+        attr_reader :rc_enablement_signal_paths
       end
     end
   end

data/lib/datadog/core/configuration/settings.rb

@@ -519,7 +519,7 @@ module Datadog
                   Datadog.logger.warn(
                     "The profiling.advanced.preview_gvl_enabled setting has been deprecated for removal and " \
                     "no longer does anything. Please remove it from your Datadog.configure block. " \
-                    "GVL profiling is now controlled by the profiling.advanced.gvl_enabled setting instead."
+                    "GVL profiling is now controlled by the profiling.advanced.gvl_enabled setting instead.",
                   )
                 end
               end
@@ -646,10 +646,13 @@ module Datadog
             end
 
             # Whether the profiler samples include the class/module name in stack frames, like `Foo::Bar#baz`, or not (`baz`)
+            #
+            # @default `DD_PROFILING_EXPERIMENTAL_SHOW_CLASSES_ENABLED` environment variable as a boolean, otherwise `true`
             option :experimental_show_classes_enabled do |o|
               o.type :bool
               o.env "DD_PROFILING_EXPERIMENTAL_SHOW_CLASSES_ENABLED"
-              o.default false
+              # Keep in sync with latest_show_classes in collectors_thread_context.c
+              o.default true
             end
           end
 

data/lib/datadog/core/configuration/supported_configurations.rb

@@ -53,6 +53,7 @@ module Datadog
           "DD_DISABLE_DATADOG_RAILS",
           "DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS",
           "DD_DYNAMIC_INSTRUMENTATION_ENABLED",
+          "DD_DYNAMIC_INSTRUMENTATION_EVALUATION_TIMEOUT_MS",
           "DD_DYNAMIC_INSTRUMENTATION_MAX_TIME_TO_SERIALIZE",
           "DD_DYNAMIC_INSTRUMENTATION_PROBE_FILE",
           "DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS",
@@ -72,6 +73,7 @@ module Datadog
           "DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS",
           "DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS",
           "DD_FEATURE_FLAGS_ENABLED",
+          "DD_FEATURE_FLAGS_EVALUATION_TELEMETRY_PER_SUBJECT_OPT_OUT_ENABLED",
           "DD_FLAGGING_EVALUATION_COUNTS_ENABLED",
           "DD_GIT_COMMIT_SHA",
           "DD_GIT_REPOSITORY_URL",
@@ -242,6 +244,7 @@ module Datadog
           "DD_TRACE_HTTP_ANALYTICS_ENABLED",
           "DD_TRACE_HTTP_ANALYTICS_SAMPLE_RATE",
           "DD_TRACE_HTTP_CLIENT_ERROR_STATUSES",
+          "DD_TRACE_HTTP_CLIENT_RESOURCE_NAME_QUANTIZE",
           "DD_TRACE_HTTP_DISTRIBUTED_TRACING",
           "DD_TRACE_HTTP_ENABLED",
           "DD_TRACE_HTTP_ERROR_STATUS_CODES",

data/lib/datadog/core/configuration.rb

@@ -90,7 +90,7 @@ module Datadog
               replace_components!(configuration, @components)
             else
               build_components(configuration)
-            end
+            end,
           )
         end
 
@@ -240,7 +240,7 @@ module Datadog
           logger_without_components.error(
             "Detected deadlock during datadog initialization: #{e.class}: #{e.message}. " \
             "Please report this at https://github.com/datadog/dd-trace-rb/blob/master/CONTRIBUTING.md#found-a-bug" \
-            "\n\tSource:\n\t#{Array(e.backtrace).join("\n\t")}"
+            "\n\tSource:\n\t#{Array(e.backtrace).join("\n\t")}",
           )
           nil
         end

data/lib/datadog/core/crashtracking/component.rb

@@ -37,7 +37,7 @@ module Datadog
             agent_base_url: agent_base_url,
             ld_library_path: ld_library_path,
             path_to_crashtracking_receiver_binary: path_to_crashtracking_receiver_binary,
-            logger: logger
+            logger: logger,
           ).tap(&:start)
         end
 

data/lib/datadog/core/diagnostics/environment_logger.rb

@@ -53,7 +53,7 @@ module Datadog
           end
         rescue => e
           logger.warn(
-            "Failed to collect core environment information: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}"
+            "Failed to collect core environment information: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}",
           )
         end
       end

data/lib/datadog/core/environment/cgroup.rb

@@ -15,7 +15,7 @@ module Datadog
           :hierarchy,
           :controllers,
           :path,
-          :inode
+          :inode,
         )
 
         module_function
@@ -52,7 +52,7 @@ module Datadog
             hierarchy,
             controllers,
             path,
-            inode_for(controllers, path)
+            inode_for(controllers, path),
           )
         end
 

data/lib/datadog/core/environment/container.rb

@@ -27,7 +27,7 @@ module Datadog
           :platform,
           :task_uid,
           :container_id,
-          :inode
+          :inode,
         )
 
         module_function
@@ -108,7 +108,7 @@ module Datadog
             end
           rescue => e
             Datadog.logger.debug(
-              "Error while checking cgroup namespace. Cause: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}"
+              "Error while checking cgroup namespace. Cause: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}",
             )
             false
           end
@@ -172,7 +172,7 @@ module Datadog
           @entry = Entry.new # Empty entry if no valid cgroup entry is found
         rescue => e
           Datadog.logger.debug(
-            "Error while reading container entry. Cause: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}"
+            "Error while reading container entry. Cause: #{e.class}: #{e.message} Location: #{Array(e.backtrace).first}",
           )
           @entry = Entry.new unless defined?(@entry)
           @entry

data/lib/datadog/core/metrics/client.rb

@@ -101,7 +101,7 @@ module Datadog
           statsd.count(stat, value, metric_options(options))
         rescue => e
           logger.error(
-            "Failed to send count stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}"
+            "Failed to send count stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}",
           )
           telemetry.report(e, description: "Failed to send count stat")
         end
@@ -115,7 +115,7 @@ module Datadog
           statsd.distribution(stat, value, metric_options(options))
         rescue => e
           logger.error(
-            "Failed to send distribution stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}"
+            "Failed to send distribution stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}",
           )
           telemetry.report(e, description: "Failed to send distribution stat")
         end
@@ -128,7 +128,7 @@ module Datadog
           statsd.increment(stat, metric_options(options))
         rescue => e
           logger.error(
-            "Failed to send increment stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}"
+            "Failed to send increment stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}",
           )
           telemetry.report(e, description: "Failed to send increment stat")
         end
@@ -142,7 +142,7 @@ module Datadog
           statsd.gauge(stat, value, metric_options(options))
         rescue => e
           logger.error(
-            "Failed to send gauge stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}"
+            "Failed to send gauge stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}",
           )
           telemetry.report(e, description: "Failed to send gauge stat")
         end
@@ -162,7 +162,7 @@ module Datadog
           rescue => e
             # TODO: Likely to be redundant, since `distribution` handles its own errors.
             logger.error(
-              "Failed to send time stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}"
+              "Failed to send time stat. Cause: #{e.class}: #{e.message} Source: #{Array(e.backtrace).first}",
             )
             telemetry.report(e, description: "Failed to send time stat")
           end
@@ -196,7 +196,7 @@ module Datadog
           IGNORED_STATSD_ONLY_ONCE.run do
             logger.warn(
               "Ignoring user-supplied statsd instance as currently-installed version of dogstastd-ruby is incompatible. " \
-              "To fix this, ensure that you have `gem 'dogstatsd-ruby', '~> 5.3'` on your Gemfile or gems.rb file."
+              "To fix this, ensure that you have `gem 'dogstatsd-ruby', '~> 5.3'` on your Gemfile or gems.rb file.",
             )
           end
         end

data/lib/datadog/core/process_discovery.rb

@@ -26,7 +26,7 @@ module Datadog
           @file_descriptor = _native_store_tracer_metadata(
             Datadog.logger,
             settings.tracing.otel_thread_context_enabled,
-            **metadata
+            **metadata,
           )
         end
 

data/lib/datadog/core/remote/client.rb

@@ -16,6 +16,12 @@ module Datadog
 
         attr_reader :transport, :repository, :id, :dispatcher, :settings, :logger
 
+        # Whether the initial reconcile is still pending, to run on the first
+        # sync whose response contains targets.
+        #
+        # @return [Boolean]
+        attr_reader :pending_initial_reconcile
+
         def initialize(transport, capabilities, settings:, logger:, repository: Configuration::Repository.new)
           @transport = transport
           @settings = settings
@@ -25,27 +31,52 @@ module Datadog
           @id = SecureRandom.uuid
           @capabilities = capabilities
           @dispatcher = Dispatcher.new(@capabilities.receivers)
+          @pending_initial_reconcile = true
         end
 
+        # Polls the agent for remote configuration, applies the response to
+        # the repository and dispatches the resulting changes to the receivers.
+        #
+        # The agent sends an empty response when it holds no targets newer
+        # than the targets version the client reported. Until the client
+        # applies a response that carries targets, it reports the initial
+        # targets version, so an empty response then means the agent has not
+        # received targets from the backend. The initial reconcile therefore
+        # waits for a response that carries targets.
+        #
+        # @return [void]
+        # @raise [TransportError] when the agent reports an internal error
+        # @raise [SyncError] when the response cannot be applied to the repository
         def sync
           # TODO: Skip sync if no capabilities are registered
           response = transport.send_config(payload)
 
           if response.ok?
-            process_response(response)
+            changes = process_response(response)
+            if pending_initial_reconcile && !response.empty?
+              dispatcher.reconcile(changes, repository)
+              @pending_initial_reconcile = false
+            end
           elsif response.internal_error?
             raise TransportError, response.to_s
           end
+          nil
         end
 
         private
 
+        # Applies an OK response to the repository and returns the resulting
+        # change set, which is empty when the response is empty.
+        #
+        # @param response [Transport::Config::Response] the response returned by the agent
+        # @return [Configuration::Repository::ChangeSet] the changes applied by this response
+        # @raise [SyncError] when the response cannot be applied to the repository
         def process_response(response)
           # when response is completely empty, do nothing as in: leave as is
           if response.empty?
             logger.debug { "remote: empty response => NOOP" }
 
-            return
+            return Configuration::Repository::ChangeSet.new
           end
 
           begin
@@ -61,7 +92,7 @@ module Datadog
           end
 
           # To make sure steep does not complain
-          return unless paths && targets && contents
+          return Configuration::Repository::ChangeSet.new unless paths && targets && contents
 
           # TODO: sometimes it can strangely be so that paths.empty?
           # TODO: sometimes it can strangely be so that targets.empty?
@@ -69,6 +100,14 @@ module Datadog
           apply_config(paths, targets, contents)
         end
 
+        # Applies the response to the repository in a transaction, dispatches the
+        # resulting changes to the receivers and returns them.
+        #
+        # @param paths [Array<Configuration::Path>] ingress paths from the response
+        # @param targets [Configuration::TargetMap] targets keyed by path
+        # @param contents [Configuration::ContentList] contents from the response
+        # @return [Configuration::Repository::ChangeSet] the changes applied by the transaction
+        # @raise [SyncError] when a path has no matching target or content
         def apply_config(paths, targets, contents)
           changes = repository.transaction do |current, transaction|
             # paths to be removed: previously applied paths minus ingress paths
@@ -121,6 +160,8 @@ module Datadog
           else
             dispatcher.dispatch(changes, repository)
           end
+
+          changes
         end
 
         def payload # standard:disable Metrics/MethodLength