Annotate DDCache/SimpleUtf8Cache/GenerationalUtf8Cache with @ForegroundSafe / @BackgroundOnly (AI perf review)

[dougqh]

What Does This Do

• Marks DDCache @ForegroundSafe — every implementation looks up a key via a small, bounded number of probes, cheap enough to call from an application thread.
• Marks SimpleUtf8Cache and GenerationalUtf8Cache @BackgroundOnly — both trade CPU for allocation savings that only pay off when run on a background thread (their own Javadoc already notes they're more CPU-expensive than a direct String.getBytes call); confine them to the background serializer thread.
• Each annotation site carries a short rationale in the Javadoc per APMLP-1544's acceptance criteria.

Motivation

Implements APMLP-1544. Stacked on #12471 (the annotation types themselves) — this PR only exists once that one lands.

Additional Notes

• techdebt review: no issues.
• perf-review review: no findings (documentation-only, zero behavior change, SOURCE retention).
• :internal-api:compileJava / :communication:compileJava succeed.
• ./gradlew spotlessCheck still pending.

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
• Update the CODEOWNERS file on source file addition, migration, or deletion (n/a — no new module/ownership boundary)
• Update public documentation with any new configuration flags or behaviors (n/a — internal-only marker annotations)
• Once approved, use merge queue to merge the PR

Jira ticket: APMLP-1544

🤖 Generated with Claude Code

[datadog-official]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 58.85% (-0.24%)

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

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.00 s	13.93 s	[-0.4%; +1.4%] (no difference)
startup:insecure-bank:tracing:Agent	12.98 s	13.05 s	[-1.3%; +0.1%] (no difference)
startup:petclinic:appsec:Agent	17.56 s	17.46 s	[-0.4%; +1.6%] (no difference)
startup:petclinic:iast:Agent	17.49 s	17.58 s	[-1.4%; +0.4%] (no difference)
startup:petclinic:profiling:Agent	16.99 s	16.88 s	[-5.4%; +6.8%] (unstable)
startup:petclinic:sca:Agent	17.50 s	17.44 s	[-0.6%; +1.2%] (no difference)
startup:petclinic:tracing:Agent	16.53 s	16.60 s	[-1.5%; +0.6%] (no difference)

Commit: 7792b1de · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[dougqh]

Superseded by #12606, which was created when unstacking #12474 from the paused dd-apm-sdk-review framework branch — #12474's branch had already merged in this PR's branch, so #12606 carries this PR's full scope.