Add @StaticLifetime and @Singleton marker annotations (AI perf review)

[dougqh]

What Does This Do

Adds two marker annotations to datadog.trace.api.function...

• @StaticLifetime (internal-api/.../function/StaticLifetime.java): marks a field that must live for the whole program, not merely for its enclosing instance's lifetime — targets the shape where a cache is constructed per-request as an instance field and never amortizes anything.
• @Singleton (internal-api/.../function/Singleton.java): class-level marker declaring exactly one process-wide instance — the escape valve @StaticLifetime needs to accept an instance field on a genuinely singleton-scoped class.

Also wires a matching AI-review check into .agents/skills/perf-review/references/checks.md (item 9), mirroring the existing @NoEscape field-storage check, and cross-references the pre-existing "static/once" deterministic-lint candidate line.

No call sites are annotated in this PR — annotations only, per plan. Selective application to real classes (e.g. the already-singleton DECORATE/GETTER-style decorators) may follow separately.

Motivation

Sparked by a real production defect (found by Andrea's automation): a DDCache constructed per-request as an instance field on a per-request object, instead of once as a static field — the cache was allocated and thrown away on every request and never actually amortized anything.

Additional Notes

@StaticLifetime and @Singleton are being delivered together because they're tightly coupled — @StaticLifetime's checker can't express its accepted forms without @Singleton's escape-valve semantics existing first.

• Checked and confirmed no collision risk for @Singleton vs javax.inject.Singleton/jakarta.inject.Singleton — the only occurrences of those are in isolated Play-framework smoke-test fixtures, nowhere near internal-api/dd-trace-api/dd-trace-core/components.
• A third sibling referenced by these tickets, @Borrowed, does not actually exist in the repo yet — filed as a separate follow-on: APMLP-1873.
• ./gradlew :internal-api:spotlessApply :internal-api:compileJava run — compiles clean, formatted.

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 (no change needed — new files land under existing internal-api ownership)
• Update public documentation with any new configuration flags or behaviors (n/a — no config/behavior change)
• Once approved, use merge queue to merge the PR

🤖 Generated with Claude Code

[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	13.99 s	13.94 s	[-0.5%; +1.2%] (no difference)
startup:insecure-bank:tracing:Agent	13.02 s	13.03 s	[-0.8%; +0.6%] (no difference)
startup:petclinic:appsec:Agent	17.08 s	17.02 s	[-0.5%; +1.2%] (no difference)
startup:petclinic:iast:Agent	16.62 s	17.00 s	[-6.5%; +2.0%] (no difference)
startup:petclinic:profiling:Agent	16.54 s	16.86 s	[-3.3%; -0.6%] (maybe better)
startup:petclinic:sca:Agent	16.97 s	16.78 s	[+0.2%; +2.1%] (maybe worse)
startup:petclinic:tracing:Agent	16.05 s	16.23 s	[-1.9%; -0.3%] (maybe better)

Commit: 4ef7e11d · 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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0848e09635

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[datadog-prod-us1-6]

The @StaticLifetime annotation contract has two enforcement gaps: the checker trigger does not cover mutable static fields (allowing replaceable static caches to pass), and the singleton-scoped instance-field form does not require final, meaning a reassignable field can incorrectly satisfy the annotation.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 0848e09 · @DataDog review to ask questions}