SymDB: TracePoint :class hot-load hook for incremental class extraction

[p-datadog]

JIRA: DEBUG-5367

What does this PR do?

Adds a TracePoint :class hook to the symdb Component so that classes loaded after initial extraction (request-time autoloads, late initializers, plugin systems, STI subclasses on first query, dynamically-created classes) reach the symbol DB. Closes a cross-tracer parity gap with Java (ClassFileTransformer), Python (BaseModuleWatchdog#after_import), and .NET (AppDomain.AssemblyLoad) — all of which combine an initial scan with a hot-load hook for continuous coverage.

Motivation:

Ruby's symdb today scans ObjectSpace.each_object(Module) once per process. Anything not loaded by :after_initialize is invisible to the upload — under eager_load=false, that's most of the app; under eager_load=true, that's still anything that loads later (request-time autoloads, plugin code, dynamically-created classes, STI subclasses on first query). Java/Python/.NET don't have this gap because they hook the runtime's class-load mechanism. This PR closes it.

Design background:

• Cross-tracer comparison and Ruby-native equivalents evaluated in the symdb project research notes.
• TracePoint :class chosen over Zeitwerk on_load (Rails-only), Module#const_added (Ruby 3.1+ only), and polling (high latency).
• Per-class incremental extraction via existing Extractor#extract(mod) chosen over full re-scan (matches Java/Python; bandwidth scales with what changed, not total app size).

Behavioral changes (intentional):

1. Multiple uploads per process. Initial upload + one upload per debounce window of new class loads. Backend dedupes overlapping FILE scopes.
2. No more class-level once-per-process flag. Component.uploaded_this_process? and the surrounding machinery removed. The two-uploads bug fix that introduced the flag is preserved by the per-instance scheduler debounce — multiple start_upload calls on one Component still collapse into one extraction within the debounce window. Cross-Component dedup is intentionally removed: each Component (e.g. after a Datadog.configure reconfigure) does its own initial extraction, which the new Component needs in order to have a hot-load baseline.
3. eager_load=false no longer suppresses auto-deferred upload. Under eager_load=false, the initial upload may be small but the hot-load hook covers the rest as the app exercises code.
4. wait_for_idle semantics unchanged from the script's perspective but the implementation waits on @last_upload_time advance instead of the removed flag.

Change log entry

None.

Additional Notes:

• Hot-load coverage is on by default; no env-var opt-out for MVP. If telemetry surfaces excessive uploads in some app shape, an opt-out can be added.
• Open question: backend dedup of overlapping FILE scopes from one process. The agnostic provider's merge-on-query path should handle this, but verifying against staging is on the verification list.
• The eager_load gate removal (add Rubocop for style guidelines #3) interacts with the two-uploads investigation. The actual fix that resolved that bug was the per-instance scheduler + the gate; with hot-load present, the gate is no longer needed because under-extracted initial uploads self-correct. A dedicated regression test ('debounce regression') exercises the per-instance scheduler half of the original fix to confirm it still holds.

How to test the change?

```
bundle exec rspec spec/datadog/symbol_database/
bundle exec steep check sig/datadog/symbol_database lib/datadog/symbol_database
bundle exec rake standard
```

316/316 specs pass; steep clean; standardrb clean. New regression test (`hot-load coverage (TracePoint :class)`) defines a class via `eval` after initial upload and asserts `Extractor#extract` is called for it.

End-to-end: gobo `bin/extract_symbols` produces an initial upload then incremental uploads as the test app exercises code. Backend dedup of overlapping FILE scopes is a verification step before un-drafting.

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-05-19 20:09:04

Comparing candidate commit 9c7dcf0 in PR branch symdb-hot-load-hook with baseline commit 87c5373 in branch master.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 46 metrics, 0 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 ----------------------------------'

[dd-octo-sts]

Typing analysis

Note: Ignored files are excluded from the next sections.

steep:ignore comments

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

steep:ignore comments (+1-1)

❌ Introduced:

lib/datadog/symbol_database/component.rb:472

✅ Cleared:

lib/datadog/symbol_database/component.rb:170

Untyped methods

This PR introduces 4 partially typed methods. It decreases the percentage of typed methods from 63.0% to 62.89% (-0.11%).

Partially typed methods (+4-0)

❌ Introduced:

sig/datadog/symbol_database/component.rbs:42
└── def initialize: (Datadog::Core::Configuration::Settings settings, Datadog::Core::Configuration::AgentSettings agent_settings, untyped logger, ?telemetry: Datadog::Core::Telemetry::Component?) -> void
sig/datadog/symbol_database/component.rbs:65
└── def self.environment_supported?: (untyped logger) -> bool
sig/datadog/symbol_database/remote.rbs:12
└── def self.receiver: (?::Array[::String] products) { (Datadog::Core::Remote::Configuration::Repository repository, ::Array[untyped] changes) -> void } -> ::Array[Datadog::Core::Remote::Dispatcher::Receiver]
sig/datadog/symbol_database/remote.rbs:16
└── def self.process_change: (Component component, untyped change, Datadog::Core::Telemetry::Component? telemetry) -> void

Untyped other declarations

This PR introduces 1 untyped other declaration.

Untyped other declarations (+1-0)

❌ Introduced:

sig/datadog/symbol_database/component.rbs:18
└── @logger: 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.