Add HTTP header selectors to the Restlet and Servlet library instrumentations

[trask]

The Restlet 1.1, Restlet 2.0, Servlet 3.0, and Servlet 5.0 library instrumentations can now select which HTTP headers to capture by glob pattern instead of by an exact list of names.

// before
ServletTelemetry.builder(openTelemetry)
    .setCapturedRequestHeaders(asList("x-request-id", "x-tenant-id"))
    .build();

// after
ServletTelemetry.builder(openTelemetry)
    .setRequestHeaders(
        IncludeExclude.builder().setIncluded("x-*").setExcluded("x-secret-*").build())
    .build();

Matching semantics

? matches one character and * matches any number of characters, including none. Excluded patterns take precedence over included patterns, so a selector with no included patterns captures every header that is not excluded. Matching is case-insensitive, since HTTP header names are. No headers are captured when no selector is configured, or when the configured selector is empty.

Header name enumeration

A wildcard or exclude-only selector has to know which headers a message actually carries, so it resolves names through HttpCommonAttributesGetter#getHttpRequestHeaderNames and #getHttpResponseHeaderNames, added in #19598. Restlet reads the names from the header Form/Series attached to the message, and the servlet implementation lives once in servlet-common, since the getter is shared across servlet versions.

Response header enumeration goes through a new ServletAccessor.getResponseHeaderNames method that defaults to an empty collection, because HttpServletResponse.getHeaderNames() only exists from Servlet 3.0 onward. The Servlet 3.0 and 5.0 accessors override it, so an exclude-only selector captures no response headers on Servlet 2.2 and on the container-specific accessors.

Compatibility

setCapturedRequestHeaders and setCapturedResponseHeaders on RestletTelemetryBuilder (1.1 and 2.0) and ServletTelemetryBuilder (3.0 and 5.0) are deprecated in favor of setRequestHeaders(IncludeExclude) and setResponseHeaders(IncludeExclude). They keep matching header names literally, so * and ? in their values are not glob patterns: a configured * still captures only a header literally named *, which is nothing, and their javadoc says so. Moving a value to a selector is therefore a deliberate behavior change to review rather than a rename.

Part of #19444.

[github-actions]

📋 Deprecation Notice

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

📝 Deprecation Details Required

Please add details to help users understand:

• What is being deprecated and why
• What should be used instead (if applicable)
• Timeline for removal (if known)
• Any migration guidance

📋 Checklist

• Deprecation details added to the PR description
• Deprecation is documented in the "Unreleased" section of the Changelog, preferably as part of this PR.
• Consider adding deprecation warnings in code/documentation

Your deprecation notes will be included in the release notes to help users prepare for future changes.

---

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

[Copilot]

Pull request overview

Adds pattern-based HTTP header capture selectors to Restlet and Servlet library instrumentation.

Changes:

• Adds IncludeExclude request/response header APIs while deprecating legacy setters.
• Implements request and response header-name enumeration.
• Adds wildcard, exclusion, and case-insensitive capture tests.

Reviewed changes

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

Show a summary per file

File	Description
CHANGELOG.md	Documents the API migration.
servlet-common/.../ServletAccessor.java	Adds response header-name access.
servlet-common/.../ServletHttpAttributesGetter.java	Exposes servlet header names.
servlet-3.0/.../ServletTelemetryBuilder.java	Adds selector-based APIs.
servlet-3.0/.../Servlet3Accessor.java	Enumerates response headers.
servlet-3.0/.../ServletHeaderCaptureTest.java	Tests selector capture.
servlet-3.0/.../ServletTestUtil.java	Uses the new APIs.
servlet-5.0/.../ServletTelemetryBuilder.java	Adds selector-based APIs.
servlet-5.0/.../Servlet5Accessor.java	Enumerates response headers.
servlet-5.0/.../ServletHeaderCaptureTest.java	Tests selector capture.
servlet-5.0/.../tomcat/ServletTestUtil.java	Updates deprecation context.
restlet-1.1/.../RestletTelemetryBuilder.java	Adds selector-based APIs.
restlet-1.1/.../RestletHttpAttributesGetter.java	Enumerates header names.
restlet-1.1/.../RestletHttpAttributesGetterTest.java	Tests selector behavior.
restlet-1.1/.../RestletServerTest.java	Uses the new APIs.
restlet-1.1/.../spring/AbstractSpringServerLibraryTest.java	Suppresses intentional deprecated usage.
restlet-2.0/.../RestletTelemetryBuilder.java	Adds selector-based APIs.
restlet-2.0/.../RestletHttpAttributesGetter.java	Enumerates header names.
restlet-2.0/.../RestletHttpAttributesGetterTest.java	Tests selector behavior.
restlet-2.0/.../RestletServerTest.java	Uses the new APIs.
restlet-2.0/.../spring/AbstractSpringServerLibraryTest.java	Suppresses intentional deprecated usage.

Suppressed comments (4)

instrumentation/restlet/restlet-1.1/library/src/main/java/io/opentelemetry/instrumentation/restlet/v1_1/RestletTelemetryBuilder.java:103

• [General] The removal timeline conflicts with #19444, which keeps legacy setters through 2.x and removes them in 3.0; the delegated extractor API also documents removal in 3.0. Saying “next minor release” incorrectly tells users this API may disappear during 2.x. Please align the Javadoc and annotation comment with the 3.0 timeline.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.
   */
  @Deprecated // may be removed in the next minor release

instrumentation/restlet/restlet-2.0/library/src/main/java/io/opentelemetry/instrumentation/restlet/v2_0/RestletTelemetryBuilder.java:103

• [General] The removal timeline conflicts with #19444, which keeps legacy setters through 2.x and removes them in 3.0; the delegated extractor API also documents removal in 3.0. Saying “next minor release” incorrectly tells users this API may disappear during 2.x. Please align the Javadoc and annotation comment with the 3.0 timeline.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.
   */
  @Deprecated // may be removed in the next minor release

instrumentation/servlet/servlet-3.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v3_0/ServletTelemetryBuilder.java:149

• [General] The removal timeline conflicts with #19444, which keeps legacy setters through 2.x and removes them in 3.0; the delegated extractor API also documents removal in 3.0. Saying “next minor release” incorrectly tells users this API may disappear during 2.x. Please align the Javadoc and annotation comment with the 3.0 timeline.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.
   */
  @Deprecated // may be removed in the next minor release

instrumentation/servlet/servlet-5.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v5_0/ServletTelemetryBuilder.java:149

• [General] The removal timeline conflicts with #19444, which keeps legacy setters through 2.x and removes them in 3.0; the delegated extractor API also documents removal in 3.0. Saying “next minor release” incorrectly tells users this API may disappear during 2.x. Please align the Javadoc and annotation comment with the 3.0 timeline.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.
   */
  @Deprecated // may be removed in the next minor release

---

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

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

Suppressed comments (8)

instrumentation/servlet/servlet-5.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v5_0/ServletTelemetryBuilder.java:116

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setRequestHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

instrumentation/servlet/servlet-5.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v5_0/ServletTelemetryBuilder.java:147

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

instrumentation/servlet/servlet-3.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v3_0/ServletTelemetryBuilder.java:116

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setRequestHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

instrumentation/servlet/servlet-3.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v3_0/ServletTelemetryBuilder.java:147

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

instrumentation/restlet/restlet-2.0/library/src/main/java/io/opentelemetry/instrumentation/restlet/v2_0/RestletTelemetryBuilder.java:70

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setRequestHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

instrumentation/restlet/restlet-2.0/library/src/main/java/io/opentelemetry/instrumentation/restlet/v2_0/RestletTelemetryBuilder.java:101

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

instrumentation/restlet/restlet-1.1/library/src/main/java/io/opentelemetry/instrumentation/restlet/v1_1/RestletTelemetryBuilder.java:70

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setRequestHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

instrumentation/restlet/restlet-1.1/library/src/main/java/io/opentelemetry/instrumentation/restlet/v1_1/RestletTelemetryBuilder.java:101

• The linked issue says deprecated Java setters remain through 2.x and are removed in 3.0, but this notice permits removal in the next minor release. Align the Javadoc and annotation with the 3.0 compatibility window.

   * @deprecated Use {@link #setResponseHeaders(IncludeExclude)} instead. May be removed in the next
   *     minor release.

[Copilot]

Pull request overview

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

Suppressed comments (4)

instrumentation/restlet/restlet-1.1/library/src/main/java/io/opentelemetry/instrumentation/restlet/v1_1/RestletTelemetryBuilder.java:106

• [General] This literal-matching guarantee is not currently preserved. The delegated DefaultHttpServerInstrumenterBuilder#setCapturedResponseHeaders wraps these names in an IncludeExclude; with the new response-header enumeration, legacy values containing * or ? are evaluated as globs. A legacy "*" value can therefore capture every response header rather than a literal header named *. Please add an exact-name path for deprecated setters and route this method through it.

   * <p>The header names are matched literally. Unlike {@link #setResponseHeaders(IncludeExclude)},
   * {@code *} and {@code ?} are not treated as glob patterns, since this setting never documented
   * them as wildcards.

instrumentation/servlet/servlet-3.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v3_0/ServletTelemetryBuilder.java:152

• [General] This literal-matching guarantee is not currently preserved. The delegated DefaultHttpServerInstrumenterBuilder#setCapturedResponseHeaders wraps these names in an IncludeExclude; with the new response-header enumeration, legacy values containing * or ? are evaluated as globs. A legacy "*" value can therefore capture every response header rather than a literal header named *. Please add an exact-name path for deprecated setters and route this method through it.

   * <p>The header names are matched literally. Unlike {@link #setResponseHeaders(IncludeExclude)},
   * {@code *} and {@code ?} are not treated as glob patterns, since this setting never documented
   * them as wildcards.

instrumentation/servlet/servlet-5.0/library/src/main/java/io/opentelemetry/instrumentation/servlet/v5_0/ServletTelemetryBuilder.java:152

• [General] This literal-matching guarantee is not currently preserved. The delegated DefaultHttpServerInstrumenterBuilder#setCapturedResponseHeaders wraps these names in an IncludeExclude; with the new response-header enumeration, legacy values containing * or ? are evaluated as globs. A legacy "*" value can therefore capture every response header rather than a literal header named *. Please add an exact-name path for deprecated setters and route this method through it.

   * <p>The header names are matched literally. Unlike {@link #setResponseHeaders(IncludeExclude)},
   * {@code *} and {@code ?} are not treated as glob patterns, since this setting never documented
   * them as wildcards.

instrumentation/restlet/restlet-2.0/library/src/main/java/io/opentelemetry/instrumentation/restlet/v2_0/RestletTelemetryBuilder.java:106

• [General] This literal-matching guarantee is not currently preserved. The delegated DefaultHttpServerInstrumenterBuilder#setCapturedResponseHeaders wraps these names in an IncludeExclude; with the new response-header enumeration, legacy values containing * or ? are evaluated as globs. A legacy "*" value can therefore capture every response header rather than a literal header named *. Please add an exact-name path for deprecated setters and route this method through it.

   * <p>The header names are matched literally. Unlike {@link #setResponseHeaders(IncludeExclude)},
   * {@code *} and {@code ?} are not treated as glob patterns, since this setting never documented
   * them as wildcards.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

Suppressed comments (1)

CHANGELOG.md:76

• [General] This release note conflicts with the PR description: it says legacy */? values are matched literally, while the description says they are dropped and produce a warning. The implementation delegates to the exact-name path (CapturedHttpHeaders.createExact), which performs literal lookups and does not log a warning. Please align the PR description with the implemented behavior, or implement the documented filtering and warning, so users receive unambiguous migration guidance.

  exact name only. The deprecated methods still match header names literally, so `*` and `?` are not
  treated as glob patterns.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Merged · refreshed 2026-08-18 21:11 UTC

Status above doesn't look right?

• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[laurit]

I guess using Iterable instead of Collection could open possibilities for implementing this method without copying headers into a new list.

[trask]

Will bundle into a follow-up PR