feat(instrumentation-http): add an experimental useDiagnosticsChannel option

[YangJonghun]

Which problem is this PR solving?

Patching the http/https exports only works when the instrumentation is registered before the modules are loaded, which isn't always possible. Since Node.js 22.12.0 / 23.2.0 there is a http.client.request.created diagnostics channel has fired before the headers are flushed, allowing propagation headers to be injected without patching - this was the blocker in #4319 .

Fixes #4319

Short description of the changes

Add an experimental useDiagnosticsChannel option, which can also be set via the OTEL_INSTRUMENTATION_HTTP_USE_DIAGNOSTICS_CHANNEL env var. When enabled, the instrumentation subscribes to http.client.request.created and http.server.request.start and reuses the existing span & metrics code paths, so that the resulting telemetry remains consistent with patching mode. On runtimes without these channels, it falls back to patching.

Known limitations

• Expect: 100-continue requests can't have propagation headers injected because the headers have already been flushed when the channel fires.
• Requests that never construct a real ClientRequest (invalid options, nock) aren't observable because the channels are never published.
• DNS lookups and TCP connections triggered by a request may not be parented to the client span, the socket is requested from the agent before the channel fires
• An Authorization: Basic header set directly by the caller can't be distinguished from one generated from the auth option. As a result, url.full may contain REDACTED credentials even though the request URL had none. This results only in over-redaction; nothing is leaked.

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• The existing suites now run twice: once in patching mode and once through the diagnostics channels. Run with npm test.
• Added a new functional suite for channel-specific behavior.

Checklist:

• Followed the style guidelines of this project
• Unit tests have been added
• Documentation has been updated

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-07-30 13:48 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.

[codecov]

Codecov Report

❌ Patch coverage is 94.70588% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.07%. Comparing base (a0267be) to head (37bc69b).

Files with missing lines	Patch %	Lines
...ry-instrumentation-http/src/diagnostics-channel.ts	93.85%	7 Missing ⚠️
...ges/opentelemetry-instrumentation-http/src/http.ts	96.42%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #6947    +/-   ##
========================================
  Coverage   95.07%   95.07%            
========================================
  Files         409      410     +1     
  Lines       14256    14406   +150     
  Branches     3267     3306    +39     
========================================
+ Hits        13554    13697   +143     
- Misses        702      709     +7     

Files with missing lines	Coverage Δ
...ges/opentelemetry-instrumentation-http/src/http.ts	94.11% <96.42%> (+0.62%)	⬆️
...ry-instrumentation-http/src/diagnostics-channel.ts	93.85% <93.85%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.