Add Symbol Database Upload for Ruby Tracer

[p-datadog]

What does this PR do?

Implements symbol database upload for dd-trace-rb. Extracts class, method, and variable information from running Ruby applications and uploads it to the Datadog backend to support Dynamic Instrumentation auto-completion and search.

Motivation:

Brings Ruby tracer to parity with Java and Python for symbol database support. Enables IDE-like auto-completion when creating DI probes — users see class fields, method arguments, and local variables as they type.

Change log entry

Yes. Add symbol database upload support for Dynamic Instrumentation. When enabled, the tracer extracts and uploads symbol information (class names, method signatures, variable names) to enable auto-completion and search features in the DI UI.

Implementation:

• Datadog::SymbolDatabase namespace (peer to DI, not under it)
• 8 components: data models, extractor, batching, uploader, remote config, configuration, lifecycle, logging
• Filters to user code only (excludes Datadog::*, stdlib, gems)
• Multipart upload to /symdb/v1/input via Core::Transport::HTTP
• 122 tests passing (unit + integration + telemetry verification)
• Validated end-to-end with a real Rails app (demo-ruby)

Ruby version differences:

On Ruby 2.6, Module#const_source_location is unavailable (added in Ruby 2.7). This means namespace-only modules (e.g., module ApplicationCable; class Channel...; end; end where the module has no methods) and classes with only generated methods (e.g., ActiveRecord models with only associations) may not appear in the symbol database. On Ruby 2.7+, const_source_location locates these via their constant declarations. This is a graceful degradation — fewer symbols in the DI auto-completion UI on 2.6, no errors.

How to test the change?

# Run symbol database tests
bundle exec rspec spec/datadog/symbol_database/

# Run with a real Rails app
cd /path/to/demo-ruby
DD_TRACER=/path/to/dd-trace-rb bundle exec bin/extract_symbols

[github-actions]

Thank you for updating Change log entry section 👏

^{Visited at: 2026-03-17 18:37:08 UTC}

[github-actions]

Typing analysis

Note: Ignored files are excluded from the next sections.

steep:ignore comments

This PR introduces 20 steep:ignore comments, and clears 1 steep:ignore comment.

steep:ignore comments (+20-1)

❌ Introduced:

lib/datadog/symbol_database/component.rb:224
lib/datadog/symbol_database/configuration/settings.rb:28
lib/datadog/symbol_database/extractor.rb:225
lib/datadog/symbol_database/extractor.rb:237
lib/datadog/symbol_database/extractor.rb:251
lib/datadog/symbol_database/extractor.rb:388
lib/datadog/symbol_database/extractor.rb:561
lib/datadog/symbol_database/extractor.rb:591
lib/datadog/symbol_database/extractor.rb:676
lib/datadog/symbol_database/extractor.rb:737
lib/datadog/symbol_database/extractor.rb:738
lib/datadog/symbol_database/extractor.rb:816
lib/datadog/symbol_database/extractor.rb:864
lib/datadog/symbol_database/remote.rb:52
lib/datadog/symbol_database/scope.rb:85
lib/datadog/symbol_database/scope_context.rb:98
lib/datadog/symbol_database/scope_context.rb:125
lib/datadog/symbol_database/scope_context.rb:142
lib/datadog/symbol_database/scope_context.rb:237
lib/datadog/symbol_database/transport.rb:44

✅ Cleared:

lib/datadog/symbol_database/scope.rb:77

Untyped methods

This PR introduces 4 untyped methods and 32 partially typed methods, and clears 3 partially typed methods. It increases the percentage of typed methods from 61.33% to 61.41% (+0.08%).

Untyped methods (+4-0)

❌ Introduced:

sig/datadog/symbol_database/component.rbs:23
└── def initialize: (untyped settings, untyped agent_settings, untyped logger, ?telemetry: untyped?) -> void
sig/datadog/symbol_database/extractor.rbs:11
└── def initialize: (logger: untyped, settings: untyped, ?telemetry: untyped?) -> void
sig/datadog/symbol_database/transport/http/endpoint.rbs:13
└── def call: (untyped env) ?{ (untyped) -> untyped } -> untyped
sig/datadog/symbol_database/uploader.rbs:22
└── def initialize: (untyped config, untyped agent_settings, logger: untyped, ?telemetry: untyped) -> void

Partially typed methods (+32-3)

❌ Introduced:

sig/datadog/symbol_database/component.rbs:21
└── def self.build: (untyped settings, untyped agent_settings, untyped logger, ?telemetry: untyped?) -> Component?
sig/datadog/symbol_database/component.rbs:42
└── def self.environment_supported?: (untyped logger) -> bool
sig/datadog/symbol_database/configuration/settings.rbs:5
└── def self.extended: (untyped base) -> void
sig/datadog/symbol_database/configuration/settings.rbs:7
└── def self.add_settings!: (untyped base) -> void
sig/datadog/symbol_database/extractor.rbs:35
└── def build_class_language_specifics: (Class klass) -> Hash[::Symbol, untyped]
sig/datadog/symbol_database/extractor.rbs:53
└── def collect_extractable_modules: () -> Hash[String, untyped]
sig/datadog/symbol_database/extractor.rbs:55
└── def group_methods_by_file: (Module mod) -> Hash[String, Array[untyped]]
sig/datadog/symbol_database/extractor.rbs:57
└── def build_file_trees: (Hash[String, untyped] entries) -> Hash[String, untyped]
sig/datadog/symbol_database/extractor.rbs:59
└── def place_in_tree: (untyped root, Array[String] name_parts, Module mod, Array[untyped] methods, String file_path) -> void
sig/datadog/symbol_database/extractor.rbs:63
└── def convert_trees_to_scopes: (Hash[String, untyped] file_trees) -> Array[Scope]
sig/datadog/symbol_database/extractor.rbs:65
└── def convert_node_to_scope: (untyped node) -> Scope
sig/datadog/symbol_database/file_hash.rbs:4
└── def self.compute: (String? file_path, logger: untyped) -> String?
sig/datadog/symbol_database/file_hash.rbs:6
└── def compute: (String? file_path, logger: untyped) -> String?
sig/datadog/symbol_database/logger.rbs:10
└── def initialize: (untyped settings, ::Logger target) -> void
sig/datadog/symbol_database/logger.rbs:17
└── def debug: (?untyped? message) ?{ () -> untyped } -> void
sig/datadog/symbol_database/logger.rbs:18
└── def warn: (?untyped? message) ?{ () -> untyped } -> void
sig/datadog/symbol_database/logger.rbs:19
└── def trace: () { () -> untyped } -> void
sig/datadog/symbol_database/remote.rbs:8
└── def self.capabilities: () -> Array[untyped]
sig/datadog/symbol_database/remote.rbs:10
└── def self.receivers: (untyped telemetry) -> Array[Core::Remote::Dispatcher::Receiver]
sig/datadog/symbol_database/remote.rbs:12
└── def self.receiver: (?Array[String] products) { (untyped repository, untyped changes) -> void } -> Array[Core::Remote::Dispatcher::Receiver]
sig/datadog/symbol_database/remote.rbs:14
└── def self.process_change: (Component component, untyped change, ?telemetry: untyped?) -> void
sig/datadog/symbol_database/remote.rbs:16
└── def self.enable_upload: (Component component, untyped content) -> void
sig/datadog/symbol_database/remote.rbs:20
└── def self.parse_config: (untyped content) -> Hash[String, untyped]?
sig/datadog/symbol_database/scope.rbs:22
└── def initialize: (
        scope_type: String,
        ?name: String?,
        ?source_file: String?,
        ?start_line: Integer?,
        ?end_line: Integer?,
        ?injectible_lines: Array[Hash[::Symbol, Integer]]?,
        ?language_specifics: Hash[::Symbol, untyped]?,
        ?symbols: Array[Datadog::SymbolDatabase::Symbol]?,
        ?scopes: Array[Scope]?
      ) -> void
sig/datadog/symbol_database/scope.rbs:54
└── def to_h: () -> Hash[::Symbol, untyped]
sig/datadog/symbol_database/scope.rbs:56
└── def to_json: (?untyped _state) -> String
sig/datadog/symbol_database/scope_context.rbs:36
└── def initialize: (Uploader uploader, logger: Logger, ?telemetry: untyped, ?on_upload: Proc?, ?timer_enabled: bool) -> void
sig/datadog/symbol_database/transport/http/endpoint.rbs:11
└── def initialize: (String path, untyped encoder) -> void
sig/datadog/symbol_database/transport/http.rbs:7
└── def self.build: (
          agent_settings: ::Datadog::Core::Configuration::AgentSettings,
          logger: untyped,
          ?headers: Hash[String, String]?
        ) ?{ (untyped) -> void } -> SymbolDatabase::Transport::Transport
sig/datadog/symbol_database/transport.rbs:9
└── def initialize: (Hash[untyped, untyped] form) -> void
sig/datadog/symbol_database/transport.rbs:17
└── def send_symdb_payload: (Hash[untyped, untyped] form) -> Core::Transport::Response
sig/datadog/symbol_database/uploader.rbs:48
└── def handle_response: (untyped response, Integer scope_count) -> bool

✅ Cleared:

sig/datadog/symbol_database/scope.rbs:24
└── def initialize: (
        scope_type: String,
        ?name: String?,
        ?source_file: String?,
        ?start_line: Integer?,
        ?end_line: Integer?,
        ?has_injectible_lines: bool,
        ?injectible_lines: Array[Hash[::Symbol, Integer]]?,
        ?language_specifics: Hash[::Symbol, untyped]?,
        ?symbols: Array[Datadog::SymbolDatabase::Symbol]?,
        ?scopes: Array[Scope]?
      ) -> void
sig/datadog/symbol_database/scope.rbs:57
└── def to_h: () -> Hash[::Symbol, untyped]
sig/datadog/symbol_database/scope.rbs:59
└── def to_json: (?untyped _state) -> String

Untyped other declarations

This PR introduces 20 untyped other declarations and 4 partially typed other declarations, and clears 2 partially typed other declarations. It decreases the percentage of typed other declarations from 77.75% to 77.24% (-0.51%).

Untyped other declarations (+20-0)

❌ Introduced:

sig/datadog/symbol_database/component.rbs:7
└── @settings: untyped
sig/datadog/symbol_database/component.rbs:8
└── @agent_settings: untyped
sig/datadog/symbol_database/component.rbs:9
└── @logger: untyped
sig/datadog/symbol_database/component.rbs:10
└── @telemetry: untyped?
sig/datadog/symbol_database/component.rbs:25
└── attr_reader settings: untyped
sig/datadog/symbol_database/extractor.rbs:7
└── @logger: untyped
sig/datadog/symbol_database/extractor.rbs:8
└── @settings: untyped
sig/datadog/symbol_database/extractor.rbs:9
└── @telemetry: untyped?
sig/datadog/symbol_database/logger.rbs:6
└── @settings: untyped
sig/datadog/symbol_database/logger.rbs:12
└── attr_reader settings: untyped
sig/datadog/symbol_database/scope_context.rbs:14
└── @telemetry: untyped
sig/datadog/symbol_database/transport/http/endpoint.rbs:7
└── @encoder: untyped
sig/datadog/symbol_database/transport/http/endpoint.rbs:9
└── attr_reader encoder: untyped
sig/datadog/symbol_database/uploader.rbs:12
└── @config: untyped
sig/datadog/symbol_database/uploader.rbs:14
└── @agent_settings: untyped
sig/datadog/symbol_database/uploader.rbs:16
└── @logger: untyped
sig/datadog/symbol_database/uploader.rbs:18
└── @telemetry: untyped
sig/datadog/symbol_database/uploader.rbs:20
└── @transport: untyped
sig/datadog/symbol_database.rbs:7
└── @mutex: untyped
sig/datadog/symbol_database.rbs:9
└── @component: untyped

Partially typed other declarations (+4-2)

❌ Introduced:

sig/datadog/symbol_database/scope.rbs:16
└── @language_specifics: Hash[::Symbol, untyped]
sig/datadog/symbol_database/scope.rbs:48
└── attr_reader language_specifics: Hash[::Symbol, untyped]
sig/datadog/symbol_database/transport.rbs:5
└── @form: Hash[untyped, untyped]
sig/datadog/symbol_database/transport.rbs:7
└── attr_reader form: Hash[untyped, untyped]

✅ Cleared:

sig/datadog/symbol_database/scope.rbs:18
└── @language_specifics: Hash[::Symbol, untyped]
sig/datadog/symbol_database/scope.rbs:51
└── attr_reader language_specifics: Hash[::Symbol, untyped]

If you believe a method or an attribute is rightfully untyped or partially typed, you can add # untyped:accept on the line before the definition to remove it from the stats.

[datadog-prod-us1-5]

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 97.00%
• Overall Coverage: 97.19% (-0.08%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: f9f4092 | Docs | Datadog PR Page | Give us feedback!}

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-04-26 02:45:55

Comparing candidate commit c92737e in PR branch symbol-database-upload with baseline commit 617c212 in branch master.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 45 metrics, 1 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

• 🟩 = significantly better candidate vs. baseline
• 🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

[p-datadog]

Thank you for the thorough review! All feedback has been addressed.

[p-datadog]

Backend dependency: DataDog/debugger-backend#1974 adds RUBY to the storage-level Language enum. Without it, Ruby symbol database uploads are silently dropped by the extractor — the tracer and agent work correctly, but data never appears in the symdb API.

[vpellan]

Is it possible to add an environment variable to these two configs ?