add thread details for declarative config by zeitlinger · Pull Request #15209 · open-telemetry/opentelemetry-java-instrumentation

zeitlinger · 2025-11-03T07:46:39Z

Part of #14087
Alternative for #14564

Summary

Moves thread details (thread.id, thread.name) from the AddThreadDetailsSpanProcessor to an InstrumenterCustomizer-based approach using ThreadDetailsAttributesExtractor. This means thread attributes are added via AttributesExtractor at instrumentation build time rather than via SpanProcessor at span start time.

The existing AddThreadDetailsSpanProcessor is still used for non-declarative-config agent mode (where it remains on by default via otel.javaagent.add-thread-details=true). The new InstrumenterCustomizer path is used for declarative config, where it is off by default — users must explicitly enable it:

Agent (declarative config): thread_details_enabled: true under the java_agent distribution node (default: false)
Spring starter (declarative config): thread_details.enabled: true under spring_starter instrumentation config (default: false)
Agent (env var / system properties): otel.javaagent.add-thread-details (default: true, unchanged)

Making it off by default in 3.0 for non-declarative-config users is tracked in #15334.

Approach

ThreadDetailsAttributesExtractor in instrumentation-api-incubator captures thread.id and thread.name on span start
InstrumenterCustomizerProvider implementations (one for agent, one for spring starter) register the extractor when enabled
Agent provider reads from AgentDistributionConfig.isThreadDetailsEnabled()
Spring starter provider reads from ExtendedOpenTelemetry.getInstrumentationConfig("spring_starter")
Config lives under distribution nodes (not instrumentation.common) per SIG feedback — this is controlled by agent/starter, not individual instrumentations
The AddThreadDetailsSpanProcessor registration is removed from AgentTracerProviderConfigurer (the processor class itself is retained for non-DC use)

Copilot

Pull Request Overview

This PR adds support for configuring thread details (thread ID and thread name) as span attributes through declarative configuration in the instrumentation API. When enabled via configuration, an AttributesExtractor automatically adds thread information to spans created by instrumenters.

Adds ThreadDetailsAttributesExtractor to InstrumenterBuilder to capture thread ID and name
Integrates with declarative configuration under instrumentation/java/thread_details/enabled
Adds comprehensive test coverage for both enabled and disabled states

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
`InstrumenterBuilder.java`	Implements thread details extraction logic and configuration parsing
`AddThreadDetailsTest.java`	Tests thread details functionality with parameterized enabled/disabled scenarios
`build.gradle.kts`	Adds test dependency for declarative configuration support

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

.../opentelemetry/javaagent/tooling/config/ThreadDetailsInstrumenterCustomizerProviderTest.java

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java

.../opentelemetry/javaagent/tooling/config/ThreadDetailsInstrumenterCustomizerProviderTest.java

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java

trask

can you update the PR description with a summary of the relationship between this and the existing thread details span processor? and mention it's off by default when using declarative config (and we can consider making it off by default in 3.0 for others)

zeitlinger · 2025-11-17T13:11:08Z

and we can consider making it off by default in 3.0 for others)

created #15334

zeitlinger · 2025-11-20T07:42:31Z

@trask please check again

trask

@jaydeluca can you take a look also?

let's also figure out where to document this, ideally in same place as other declarative config "common" attributes

zeitlinger · 2025-12-02T10:43:55Z

@trask please have another look

zeitlinger · 2026-01-14T09:22:05Z

@trask please have another look

...t/java/io/opentelemetry/instrumentation/kafkaconnect/v2_6/MongoKafkaConnectSinkTaskTest.java

zeitlinger · 2026-01-15T13:39:08Z

@trask please have a look

.../io/opentelemetry/instrumentation/api/incubator/thread/ThreadDetailsAttributesExtractor.java

trask · 2026-01-22T16:11:46Z

discussed in Java declarative config SIG: let's move configuration under java agent and spring starter nodes, since this is something controlled by them as opposed to controlled by individual instrumentations

zeitlinger · 2026-01-22T18:24:20Z

discussed in Java declarative config SIG: let's move configuration under java agent and spring starter nodes, since this is something controlled by them as opposed to controlled by individual instrumentations

OK waiting on #15822 then

zeitlinger · 2026-03-12T11:34:41Z

Rebased onto main and reworked based on SIG feedback:

Thread details now use InstrumenterCustomizer instead of SpanProcessor (as discussed with @trask and @laurit)
Config moved from instrumentation.common to distribution nodes:
- Agent: AgentDistributionConfig.thread_details_enabled (DC) / otel.javaagent.add-thread-details (env var, default true)
- Spring starter: instrumentation.spring_starter.thread_details.enabled (DC, default false)
No longer baked into instrumentation-api — uses the customizer pattern
Test rewritten without reflection

All previous review comments should be addressed by this rework.

Thread details (thread.id, thread.name) are now added via InstrumenterCustomizer instead of SpanProcessor, allowing native instrumentations to opt in. Configuration moves under distribution nodes: - javaagent: distribution.javaagent.thread_details_enabled (DC) / otel.javaagent.add-thread-details (env var, default true) - spring starter: instrumentation.spring_starter.thread_details.enabled (DC, default false) Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

…rTest Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

@configuration

Java8RuntimeMetricsProvider and Java17RuntimeMetricsProvider are not @configuration classes and should not be registered as Spring auto-configurations. Their presence causes Spring AOT processing to fail with FileNotFoundException when the classes are not on the classpath. Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

…nfig registries Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

The Spring Boot starter's ThreadDetailsInstrumenterCustomizerProvider reads from the declarative config path spring_starter > thread_details > enabled, but the ConfigPropertiesBackedDeclarativeConfigProperties bridge only handles paths starting with "java." or explicitly listed in SPECIAL_MAPPINGS. This caused the property otel.instrumentation.common.thread-details.enabled to have no effect in non-declarative-config mode, breaking smoke tests. Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger requested a review from a team as a code owner November 3, 2025 07:46

zeitlinger self-assigned this Nov 3, 2025

zeitlinger requested a review from Copilot November 3, 2025 07:47

zeitlinger mentioned this pull request Nov 3, 2025

declarative config: add thread details resource processor #14564

Closed

Copilot AI reviewed Nov 3, 2025

View reviewed changes

zeitlinger mentioned this pull request Nov 3, 2025

Support otel.javaagent.add-thread-details and span logging with declarative config #14087

Open

8 tasks

zeitlinger marked this pull request as draft November 3, 2025 17:55

zeitlinger force-pushed the declarative-config-thread-details-provider2 branch from 6fb9796 to 29883b5 Compare November 9, 2025 12:51

zeitlinger marked this pull request as ready for review November 9, 2025 12:51

laurit reviewed Nov 10, 2025

View reviewed changes

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java Outdated Show resolved Hide resolved

laurit reviewed Nov 10, 2025

View reviewed changes

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java Outdated Show resolved Hide resolved

trask reviewed Nov 13, 2025

View reviewed changes

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java Outdated Show resolved Hide resolved

trask reviewed Nov 13, 2025

View reviewed changes

zeitlinger force-pushed the declarative-config-thread-details-provider2 branch from acdc794 to dd2b211 Compare November 17, 2025 12:56

zeitlinger mentioned this pull request Nov 17, 2025

turn thread details off by default in 3.0 #15334

Open

trask approved these changes Nov 24, 2025

View reviewed changes

jaydeluca approved these changes Nov 26, 2025

View reviewed changes

zeitlinger force-pushed the declarative-config-thread-details-provider2 branch from fff4d30 to 8c8a96c Compare December 5, 2025 09:06

zeitlinger added this to the v2.23.0 milestone Dec 5, 2025

zeitlinger requested a review from trask December 5, 2025 13:07

trask removed this from the v2.23.0 milestone Dec 12, 2025

github-actions bot added the test native This label can be applied to PRs to trigger them to run native tests label Jan 14, 2026

zeitlinger force-pushed the declarative-config-thread-details-provider2 branch from 46e9ee9 to aaea68d Compare January 14, 2026 13:59

zeitlinger commented Jan 14, 2026

View reviewed changes

...t/java/io/opentelemetry/instrumentation/kafkaconnect/v2_6/MongoKafkaConnectSinkTaskTest.java Show resolved Hide resolved

jaydeluca reviewed Jan 16, 2026

View reviewed changes

.../io/opentelemetry/instrumentation/api/incubator/thread/ThreadDetailsAttributesExtractor.java Outdated Show resolved Hide resolved

zeitlinger marked this pull request as draft January 22, 2026 18:24

zeitlinger force-pushed the declarative-config-thread-details-provider2 branch 3 times, most recently from afa0353 to babfd95 Compare March 12, 2026 11:24

zeitlinger marked this pull request as ready for review March 12, 2026 15:01

zeitlinger added 2 commits March 13, 2026 11:22

Fix spotless formatting in ThreadDetailsInstrumenterCustomizerProvide…

6b0e17a

…rTest Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

zeitlinger force-pushed the declarative-config-thread-details-provider2 branch from 33a00b1 to 6b0e17a Compare March 13, 2026 11:22

zeitlinger added 4 commits March 13, 2026 13:31

Fix runtimemetrics -> runtimetelemetry package typo in Spring auto-co…

f2cb45e

…nfig registries Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Add java.agent -> otel.javaagent mapping in resolvePropertyKey

b0b303f

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Conversation

zeitlinger commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Approach

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trask left a comment

Choose a reason for hiding this comment

Uh oh!

zeitlinger commented Nov 17, 2025

Uh oh!

zeitlinger commented Nov 20, 2025

Uh oh!

trask left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zeitlinger commented Dec 2, 2025

Uh oh!

zeitlinger commented Jan 14, 2026

Uh oh!

Uh oh!

zeitlinger commented Jan 15, 2026

Uh oh!

Uh oh!

trask commented Jan 22, 2026

Uh oh!

zeitlinger commented Jan 22, 2026

Uh oh!

zeitlinger commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

zeitlinger commented Nov 3, 2025 •

edited

Loading

trask left a comment •

edited

Loading