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.

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

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

@trask please have a look

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

zeitlinger · 2026-06-02T10:54:16Z

@trask can this be merged now?

Copilot

Pull request overview

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

+  public void customize(InstrumenterCustomizer customizer) {
+    if (AgentDistributionConfig.get().isThreadDetailsEnabled()) {
+      customizer.addAttributesExtractor(new ThreadDetailsAttributesExtractor<>());
+    }


+  /** Called from OpenTelemetryAutoConfiguration for declarative config. */
+  public static void configureDeclarativeConfig(Object model) {
+    enabled = isEnabled(model);
+  }
+
+  /** Called from OpenTelemetryAutoConfiguration for properties-based config. */
+  public static void configureProperties(Environment environment) {
+    enabled = Boolean.TRUE.equals(environment.getProperty(LEGACY_PROPERTY, Boolean.class));
+  }
+
+  @Override
+  public void customize(InstrumenterCustomizer customizer) {
+    if (enabled) {
+      customizer.addAttributesExtractor(new ThreadDetailsAttributesExtractor<>());
+    }


Registers AddThreadDetailsSpanProcessor through declarative config (a named ComponentProvider plus a DeclarativeConfigurationCustomizerProvider that injects the processor node) for both the javaagent and the spring starter. Because it is a SpanProcessor, thread.id/thread.name are added to manually-created spans too, not only Instrumenter-built spans. - agent: enabled via distribution.javaagent (otel.javaagent.add-thread-details) - spring starter: enabled via distribution.spring_starter.thread_details_enabled Alternative to the InstrumenterCustomizer/AttributesExtractor approach in open-telemetry#15209. Signed-off-by: Trask Stalnaker <trask.stalnaker@gmail.com>

trask · 2026-06-16T03:20:56Z

I decided against moving thread attributes from span processor to instrumenter due to losing coverage for manual spans. I think losing coverage for manual spans may be worse (or at least no better) than the current situation of samplers not having access to thread attributes. See new PR #19008.

zeitlinger · 2026-06-16T09:53:26Z

Close in favor of #19008

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

Closed

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

Comment thread ...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java Outdated

laurit reviewed Nov 10, 2025

View reviewed changes

Comment thread ...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java Outdated

trask reviewed Nov 13, 2025

View reviewed changes

Comment thread ...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java Outdated

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

Closed

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

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

jaydeluca reviewed Jan 16, 2026

View reviewed changes

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

zeitlinger and others added 5 commits May 12, 2026 12:50

Refactor thread-details preview default

9cc5675

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

Inline thread-details preview default

9f5223a

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

Avoid spring config model compile dependency

9487352

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

fix: accept string spring thread-details flag

ab1fce4

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

Run spotless

22fe763

zeitlinger added this to Java Instrumentation 3.0 Jun 11, 2026

zeitlinger added this to the v3.0.0 milestone Jun 11, 2026

trask modified the milestones: v3.0.0, v2.29.0 Jun 12, 2026

trask requested a review from Copilot June 12, 2026 14:23

Copilot started reviewing on behalf of trask June 12, 2026 14:23 View session

Copilot AI reviewed Jun 12, 2026

View reviewed changes

trask mentioned this pull request Jun 15, 2026

Add thread details for declarative config via span processor #19008

Merged

trask removed this from the v2.29.0 milestone Jun 16, 2026

zeitlinger closed this Jun 16, 2026

github-project-automation Bot moved this to Done in Java Instrumentation 3.0 Jun 16, 2026

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!

zeitlinger commented Jun 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

trask commented Jun 16, 2026

Uh oh!

zeitlinger commented Jun 16, 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