Retain invalid span links with attributes or trace state

[trask]

The SDK now retains links with invalid IDs when their attributes or trace state are nonempty, following the tracing API's SHOULD recommendation:

Implementations SHOULD record links containing SpanContext with empty TraceId or SpanId (all zeros) as long as either the attribute set or TraceState is non-empty.

This applies to links added both before and after span creation.

spanBuilder.addLink(
    SpanContext.getInvalid(),
    Attributes.of(AttributeKey.stringKey("messaging.message.id"), "message-123"));

Eligibility is checked before attribute truncation. Null contexts and empty invalid links remain ignored; trace flags alone do not qualify.

Existing link limits, ordering, and sampling behavior apply. Links added after span creation also preserve the original attribute count for dropped-attribute reporting.

SDK portion of open-telemetry/opentelemetry-java-instrumentation#20272.

[Copilot]

🟢 Approval recommended

The implementation matches the tracing specification and is comprehensively covered across SDK paths and serialization.

0 open findings

What changed in this PR

Updates tracing APIs and SDK behavior to retain invalid span links when attributes or trace state provide useful metadata.

Changes:

• Retains qualifying invalid links before and after span creation.
• Preserves limits, ordering, sampling input, and original attribute counts.
• Adds SDK and OTLP serialization coverage.

File	Description
api/​all/​.../​Span.java	Documents invalid-link behavior.
api/​all/​.../​SpanBuilder.java	Documents builder behavior.
sdk/​trace/​.../​SdkSpan.java	Retains qualifying runtime links.
sdk/​trace/​.../​SdkSpanBuilder.java	Retains qualifying creation-time links.
sdk/​trace/​.../​SdkSpanTest.java	Tests runtime links and limits.
sdk/​trace/​.../​SdkSpanBuilderTest.java	Tests builder links, limits, and sampling.
exporters/​otlp/​.../​TraceRequestMarshalerTest.java	Verifies invalid-context OTLP encoding.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.60%. Comparing base (0d0b0ca) to head (5c788f0).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #8917      +/-   ##
============================================
+ Coverage     90.58%   90.60%   +0.01%     
- Complexity    10742    10749       +7     
============================================
  Files          1007     1007              
  Lines         29205    29210       +5     
  Branches       3786     3788       +2     
============================================
+ Hits          26456    26466      +10     
+ Misses         1850     1847       -3     
+ Partials        899      897       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-10-08 21:46 UTC

Review the latest changes.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.