DEBUG-5089 Enable symbol database when dynamic instrumentation is enabled

docs/DynamicInstrumentation.md

@@ -343,12 +343,19 @@ names, method names, and method parameters when creating probes.
 
 ### Enabling the Symbol Database
 
-Symbol Database upload is disabled by default. To enable it, set:
+Symbol Database upload follows Dynamic Instrumentation. By default it
+uploads symbols only when Dynamic Instrumentation is actually enabled —
+either explicitly (`DD_DYNAMIC_INSTRUMENTATION_ENABLED=true`) or implicitly
+when you open the DI UI for your service (which enables Dynamic
+Instrumentation via Remote Configuration).
+
+To upload symbols regardless of Dynamic Instrumentation:
 
     export DD_SYMBOL_DATABASE_UPLOAD_ENABLED=true
 
-Once enabled, the upload activates via Remote Configuration when you open
-the DI UI for your service.
+To explicitly disable it:
+
+    export DD_SYMBOL_DATABASE_UPLOAD_ENABLED=false
 
 ## Rate Limiting and Performance
 

docs/GettingStarted.md

@@ -2970,15 +2970,15 @@ Alternatively, set DI parameters inside a `Datadog.configure` block:
 
 #### Symbol Database
 
-When Dynamic Instrumentation is enabled, the tracer can extract and upload symbol information (class names, method signatures, parameter names) from your application to enable auto-completion in the DI UI. Symbol Database upload is disabled by default; enable it to allow Remote Configuration to activate uploads.
+When Dynamic Instrumentation is enabled, the tracer can extract and upload symbol information (class names, method signatures, parameter names) from your application to enable auto-completion in the DI UI. Symbol Database upload follows Dynamic Instrumentation: by default it uploads symbols only when Dynamic Instrumentation is actually enabled (via `DD_DYNAMIC_INSTRUMENTATION_ENABLED` or implicit enablement through the DI UI), and stays off otherwise. When it uploads, it activates automatically using Remote Configuration. Set `DD_SYMBOL_DATABASE_UPLOAD_ENABLED` (or `c.symbol_database.enabled`) to `true`/`false` to override: `true` uploads regardless of Dynamic Instrumentation, `false` disables it entirely.
 
 | Environment variable | Type | Description | Default |
 |---|---|---|---|
-| `DD_SYMBOL_DATABASE_UPLOAD_ENABLED` | `Boolean` | Enable or disable symbol database upload. | `false` |
+| `DD_SYMBOL_DATABASE_UPLOAD_ENABLED` | `Boolean` | Enable or disable symbol database upload. | Unset: uploads only when Dynamic Instrumentation is actually enabled |
 
 | Setting | Type | Description | Default |
 |---|---|---|---|
-| `c.symbol_database.enabled` | `Boolean` | Enable or disable symbol database upload. | `false` |
+| `c.symbol_database.enabled` | `Boolean, nil` | Enable or disable symbol database upload; `nil` (unset) follows Dynamic Instrumentation. | Unset (`nil`): uploads only when Dynamic Instrumentation is actually enabled |
 
 Symbol Database requires MRI Ruby 2.7+ and Remote Configuration (enabled by default). For details on what is extracted, which code is included, and behavior differences across Ruby versions, see [Dynamic Instrumentation — Symbol Database](DynamicInstrumentation.md#symbol-database).
 

lib/datadog.rb

@@ -12,6 +12,7 @@
 require_relative 'datadog/ai_guard'
 require_relative 'datadog/appsec'
 require_relative 'datadog/di'
+require_relative 'datadog/symbol_database/extensions'
 require_relative 'datadog/data_streams'
 require_relative 'datadog/open_feature'
 

lib/datadog/core/configuration/components.rb

@@ -46,6 +46,38 @@ def build_health_metrics(settings, logger, telemetry)
             Core::Diagnostics::Health::Metrics.new(telemetry: telemetry, logger: logger, **options)
           end
 
+          # Decides whether to build the SymbolDatabase component, for the
+          # tri-state symbol_database.enabled setting: true/false are explicit
+          # overrides; nil (the default) mirrors Dynamic Instrumentation by
+          # building whenever DI's component was built. dynamic_instrumentation
+          # is DI's build result — nil only when DI is explicitly disabled or the
+          # runtime can't support it (Rails development mode, missing C
+          # 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?)
+          # 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.
+          # force_upload (internal/testing) always builds, since it uploads
+          # regardless of DI or the enabled setting.
+          # @param settings [Configuration::Settings]
+          # @param dynamic_instrumentation [DI::Component, nil]
+          # @return [Boolean]
+          def enable_symbol_database?(settings, dynamic_instrumentation)
+            # The symbol_database settings group is only registered on the full
+            # library load path; a partial load (e.g. require 'datadog/di') leaves
+            # it absent, in which case the feature cannot be enabled.
+            return false unless settings.respond_to?(:symbol_database)
+
+            # force_upload uploads unconditionally, so the component must be built
+            # even when the setting is nil and DI's component was not built.
+            return true if settings.symbol_database.internal.force_upload
+
+            # nil (the default) follows whether DI's component was built.
+            Datadog::SymbolDatabase.resolve_enabled(settings.symbol_database.enabled, !dynamic_instrumentation.nil?)
+          end
+
           def build_logger(settings)
             logger = settings.logger.instance || Core::Logger.new($stderr)
             logger.level = settings.diagnostics.debug ? ::Logger::DEBUG : settings.logger.level
@@ -174,7 +206,21 @@ def initialize(settings)
           @ai_guard = Datadog::AIGuard::Component.build(settings, logger: @logger, telemetry: telemetry)
           @open_feature = OpenFeature::Component.build(settings, agent_settings, logger: @logger, telemetry: telemetry)
           @dynamic_instrumentation = Datadog::DI::Component.build(settings, agent_settings, @logger, telemetry: telemetry)
-          @symbol_database = Datadog::SymbolDatabase::Component.build(settings, agent_settings, @logger, telemetry: telemetry)
+          # Only build symbol database when enabled, so a disabled component is
+          # never constructed.
+          @symbol_database =
+            if self.class.enable_symbol_database?(settings, @dynamic_instrumentation)
+              # di_active is a live predicate, not a snapshot: DI may start after
+              # this component is built (implicit enablement via remote config).
+              # Symbol Database holds only this opaque proc, never a DI reference,
+              # so the two modules stay independent — the orchestration layer
+              # owns the cross-feature knowledge.
+              Datadog::SymbolDatabase::Component.build(
+                settings, agent_settings, @logger,
+                telemetry: telemetry,
+                di_active: -> { dynamic_instrumentation&.started? || false },
+              )
+            end
           @error_tracking = Datadog::ErrorTracking::Component.build(settings, @tracer, @logger)
           @data_streams = self.class.build_data_streams(settings, agent_settings, @logger, @agent_info)
           # Reflects "the customer configured DI to be on" — true iff the

lib/datadog/core/configuration/settings.rb

@@ -14,7 +14,6 @@
 
 require_relative '../../tracing/configuration/settings'
 require_relative '../../opentelemetry/configuration/settings'
-require_relative '../../symbol_database/configuration'
 
 module Datadog
   module Core
@@ -1130,8 +1129,6 @@ def initialize(*_)
         extend Datadog::Tracing::Configuration::Settings
 
         extend Datadog::OpenTelemetry::Configuration::Settings
-
-        extend Datadog::SymbolDatabase::Configuration::Settings
       end
       # standard:enable Metrics/BlockLength
     end

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

@@ -4,6 +4,7 @@
 require_relative '../../../appsec/remote'
 require_relative '../../../tracing/remote'
 require_relative '../../../di/remote'
+require_relative '../../../symbol_database'
 require_relative '../../../symbol_database/remote'
 require_relative '../../../open_feature/remote'
 
@@ -62,13 +63,20 @@ def register(settings)
             end
 
             # Skip symbol database registration on runtimes that cannot run it
-            # (JRuby, Ruby < 2.7): advertising LIVE_DEBUGGING_SYMBOL_DB there
-            # would invite symbol-upload configs the component can never serve.
-            if settings.respond_to?(:symbol_database) && settings.symbol_database.enabled &&
-                Datadog::SymbolDatabase.supported_runtime?
-              register_capabilities(Datadog::SymbolDatabase::Remote.capabilities)
-              register_products(Datadog::SymbolDatabase::Remote.products)
-              register_receivers(Datadog::SymbolDatabase::Remote.receivers(@telemetry))
+            # (JRuby, Ruby < 2.7): DI supports Ruby 2.6 but Symbol Database does
+            # not, so advertising LIVE_DEBUGGING_SYMBOL_DB there would invite
+            # symbol-upload configs the component can never serve.
+            if settings.respond_to?(:symbol_database) && Datadog::SymbolDatabase.supported_runtime?
+              # Symbol database follows DI: when unset it advertises whenever DI
+              # advertises (mirror the DI branch above, including the unset/default
+              # case that RC may enable). An explicit symbol_database.enabled wins.
+              di_enabled = settings.respond_to?(:dynamic_instrumentation) &&
+                !Datadog::DI::Remote.explicitly_disabled?(settings)
+              if Datadog::SymbolDatabase.resolve_enabled(settings.symbol_database.enabled, di_enabled)
+                register_capabilities(Datadog::SymbolDatabase::Remote.capabilities)
+                register_products(Datadog::SymbolDatabase::Remote.products)
+                register_receivers(Datadog::SymbolDatabase::Remote.receivers(@telemetry))
+              end
             end
 
             if settings.respond_to?(:open_feature) && settings.open_feature.enabled

lib/datadog/symbol_database.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'ruby_version'
+
 module Datadog
   # Namespace for Datadog symbol database upload.
   #
@@ -46,14 +48,24 @@ module SymbolDatabase
     # @see https://www.postgresql.org/docs/current/datatype-numeric.html
     UNKNOWN_MAX_LINE = 2147483647
 
-    class << self
-      # Whether the current Ruby runtime can run symbol database extraction:
-      # MRI (CRuby) on Ruby 2.7 or later.
-      #
-      # @return [Boolean]
-      def supported_runtime?
-        RUBY_ENGINE == 'ruby' && RubyVersion.is?('>= 2.7')
-      end
+    # Collapses the symbol_database.enabled tri-state setting to a boolean.
+    # An explicit true/false wins; nil (unconfigured) yields the caller-supplied
+    # fallback.
+    # @param setting_value [Boolean, nil] the symbol_database.enabled setting
+    # @param di_fallback [Boolean] value used when the setting is unconfigured
+    # @return [Boolean]
+    def self.resolve_enabled(setting_value, di_fallback)
+      setting_value.nil? ? di_fallback : setting_value
+    end
+
+    # Whether the current Ruby runtime can run symbol database extraction:
+    # MRI (CRuby) on Ruby 2.7 or later. Used by the remote-config layer to avoid
+    # advertising the product on runtimes where Component.build would return nil
+    # (e.g. Ruby 2.6, which Dynamic Instrumentation supports but Symbol Database
+    # does not).
+    # @return [Boolean]
+    def self.supported_runtime?
+      RUBY_ENGINE == 'ruby' && RubyVersion.is?('>= 2.7')
     end
   end
 end