Require explicit Instrumenter schema selection by trask · Pull Request #20761 · open-telemetry/opentelemetry-java-instrumentation

trask · 2026-10-20T05:31:02Z

Make InstrumenterBuilder.setSchemaUrl(...) the only source of the schema URL shared by spans, operation metrics, and exception logs. The schema identifies the conventions defining those signals, independent of supporting attributes.

 Instrumenter.<Request, Response>builder(openTelemetry, "my-instrumentation", spanNameExtractor)
+    .setSchemaUrl("https://opentelemetry.io/schemas/1.41.0")
     .addAttributesExtractor(attributesExtractor)
     .buildInstrumenter();

Breaking change: Builders that relied on attribute-derived schemas must add the setter shown above. Without it, telemetry has no schema URL in any mode. Explicit custom URLs remain supported.

Fourth and final layer on #20760, tracking #20755.

github-actions · 2026-10-20T05:31:25Z

⚠️ Breaking Change Documentation Required

This PR has been labeled as a breaking change. Please ensure you provide the following information:

Migration Notes Required

Please add detailed migration notes to help users understand:

What is changing and why
How to update their code/configuration
Any alternative approaches if applicable
Code examples showing before/after usage

Checklist

Migration notes added to the PR description
Breaking change is documented in the "Unreleased" section of the Changelog, preferably as part of this PR.
Consider if this change requires a major version bump

Your migration notes will be included in the release notes to help users upgrade smoothly. The more detailed and helpful they are, the better the user experience will be.

This comment was automatically generated because the breaking change label was applied to this PR.

opentelemetry-pr-dashboard · 2026-10-20T05:31:37Z

Pull request dashboard status

Waiting on reviewers · refreshed 2026-10-20 23:26 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.

Copilot

🟢 Approval recommended

The supplied changes consistently implement explicit schema selection, with focused regression coverage and migration documentation and no unresolved findings.

No open issues 🎉

What changed in this PR

Completes the schema-selection migration by making InstrumenterBuilder.setSchemaUrl(...) the sole source of schema URLs across instrumenter telemetry.

Changes:

Removes attribute-based schema inference and provider implementations.
Adds coverage for explicit, custom, and absent schemas across signals.
Documents the breaking change and required migration.

File	Description
instrumentation/camel-2.20/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/camel/v2_20/CamelSingletons.java	Removes schema forwarding from the extractor wrapper.
instrumentation/aws-lambda/aws-lambda-events-common-2.2/library/src/main/java/io/opentelemetry/instrumentation/awslambdaevents/common/v2_2/internal/SpanKeyOmittingAttributesExtractor.java	Removes schema forwarding while retaining attribute delegation.
instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterTest.java	Tests schema propagation across spans, metrics, and logs.
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/SchemaUrlProvider.java	Deletes the internal schema-provider interface.
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java	Uses only explicitly selected schemas.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcAttributesExtractorTest.java	Removes obsolete schema-provider assertions.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractorTest.java	Removes obsolete schema-provider coverage.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/SqlClientAttributesExtractorTest.java	Removes obsolete SQL schema-provider coverage.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/DbClientAttributesExtractorTest.java	Removes obsolete database schema-provider assertions.
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/HttpInstrumenterSchemaTest.java	Tests independence from supporting attributes and span names.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcCommonAttributesExtractor.java	Removes RPC extractor schema provision.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/messaging/MessagingAttributesExtractor.java	Removes messaging extractor schema provision.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/SqlClientAttributesExtractor.java	Removes SQL extractor schema provision.
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/db/DbClientAttributesExtractor.java	Removes database extractor schema provision.
docs/contributing/using-instrumenter-api.md	Explains explicit schema selection and its scope.
CHANGELOG.md	Records the breaking change and migration.

_{Review effort: Balanced}

trask · 2026-10-20T20:56:53Z

+  }
+
+  @Test
+  void conventionalSpanNameDoesNotSelectSchema() {


@copilot Simplify the schema-selection tests in this PR according to .github/instructions/java-tests.instructions.md. Update this PR directly on its existing head branch; do not create a separate follow-up PR as a workaround. Preserve its existing draft/ready state.

The requested cleanup is in instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/HttpInstrumenterSchemaTest.java. Remove the newly added conventionalSpanNameDoesNotSelectSchema() test: span naming never participated in schema inference, and this PR does not change that behavior. Remove the newly added attributeExtractorsDoNotSelectSchema(boolean multipleDomains) domain-combination test rather than preserving the removed inference algorithm's cases as historical-absence tests.

Keep focused central coverage of the supported schema default and explicit schema propagation, without duplicating it in HTTP or per-domain tests. The PR already adds schemaUrl_allSignals(String schemaUrl) in instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterTest.java, including a null case that omits setSchemaUrl() and explicit URLs, with span, metric, and conditional exception-log assertions. Inspect and reuse that coverage; do not add another default-schema test if it is already sufficient.

Assess the newly added supportingAttributesDoNotChangeSignalSchema() against that central all-signals test and the existing emitsHttpSchemaOnSignals() and customClientInstrumenterEmitsHttpSchema() tests. Remove it if it only repeats supported behavior those tests already establish. Retain it only if it adds distinct coverage of a supported contract that would merit testing independently of the removed inference feature. Do not add absence tests merely to prove removed functionality stays removed or to cover unrelated combinations.

Limit changes to this test cleanup and directly resulting unused imports, mocks, or fixtures. Preserve the PR's production behavior and useful existing schema coverage. Follow the repository testing guidance, run the narrowest relevant formatting and tests, and commit and push the cleanup to this PR's existing head branch.

Removed the three redundant/non-contract tests and their unused fixtures/imports, retaining the HTTP-specific schema coverage. The focused tests and formatting checks passed. Commit: 14d292de.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Co-authored-by: trask <218610+trask@users.noreply.github.com>

opentelemetry-pr-dashboard Bot mentioned this pull request Oct 20, 2026

Pull Request Dashboard #18435

Open

trask added the breaking change label Oct 20, 2026

trask requested a balanced review from Copilot October 20, 2026 05:31

Copilot started reviewing on behalf of trask October 20, 2026 05:31

View session

trask added this pull request to stack #20762 October 20, 2026 05:34

Copilot AI reviewed Oct 20, 2026

View reviewed changes

trask mentioned this pull request Oct 20, 2026

Select schema URLs from the primary semantic-convention domain #20755

Open

trask force-pushed the trask-explicit-only-instrumenter-schemas branch from 2811749 to 9916458 Compare October 20, 2026 18:12

trask commented Oct 20, 2026

View reviewed changes

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

trask commented Oct 20, 2026

View reviewed changes

Copilot started work on behalf of trask October 20, 2026 20:57

View session

Copilot finished work on behalf of trask October 20, 2026 21:04

trask commented Oct 20, 2026

View reviewed changes

Comment thread docs/contributing/using-instrumenter-api.md Outdated

Copilot started work on behalf of trask October 20, 2026 21:06

View session

Copilot finished work on behalf of trask October 20, 2026 21:09

trask marked this pull request as ready for review October 20, 2026 21:10

trask requested a review from a team as a code owner October 20, 2026 21:10

trask and others added 3 commits October 20, 2026 15:18

Require explicit Instrumenter schema selection

817728d

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Apply suggestion from @trask

83903b0

Clarify Instrumenter schema documentation

22ca7c4

Co-authored-by: trask <218610+trask@users.noreply.github.com>

trask force-pushed the trask-explicit-only-instrumenter-schemas branch from b64c2cf to 22ca7c4 Compare October 20, 2026 22:32

Navigation Menu

Repository navigation

Require explicit Instrumenter schema selection - #20761

Require explicit Instrumenter schema selection#20761
trask wants to merge 3 commits into
trask-explicit-signal-schema-selectionfrom
trask-explicit-only-instrumenter-schemas

trask commented Oct 20, 2026

Uh oh!

github-actions Bot commented Oct 20, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

trask Oct 20, 2026

Uh oh!

Copilot AI Oct 20, 2026

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

trask commented Oct 20, 2026

Uh oh!

github-actions Bot commented Oct 20, 2026

⚠️ Breaking Change Documentation Required

Migration Notes Required

Checklist

Uh oh!

opentelemetry-pr-dashboard Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

trask Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

opentelemetry-pr-dashboard Bot commented Oct 20, 2026 •

edited

Loading