Skip to content

Tidy up the OpenTelemetry dependencies and propagators - #1495

Open
unflxw wants to merge 5 commits into
mainfrom
otel-housekeeping
Open

Tidy up the OpenTelemetry dependencies and propagators#1495
unflxw wants to merge 5 commits into
mainfrom
otel-housekeeping

Conversation

@unflxw

@unflxw unflxw commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Remove the global BlobPropertyBag declaration

This declaration stood in for a DOM type that the undici typings
bundled with @types/node referred to, which this project does not pull
in because its lib is set to es2018. Those typings no longer refer
to it, so the declaration is only a stand-in for nothing.

Leaving it in place breaks the build outright from @types/node version
25 onwards, because that version declares BlobPropertyBag itself and
TypeScript reports the two declarations as a conflict. That went
unnoticed because the committed package-lock.json holds @types/node
at version 22, so only an install that resolves versions afresh runs
into it.

Stop sending the trace context in B3 headers

Version 3.7.0 set out to stop propagating the trace context, because two
applications that both report to AppSignal would join the same trace and
the second one's data would be reported against the first one's
application. It kept propagating it anyway, for a year.

The pull request that did this first disabled every propagator, which
was reviewed and agreed. A later commit on the same branch added
propagators back, to keep baggage working for customers who use it, and
took the OTEL_PROPAGATORS factory map in @opentelemetry/sdk-node for
the list of defaults. That map is the set of propagators a user can name
in that environment variable. The defaults are the W3C trace context and
baggage propagators, so "the defaults without trace context" became
baggage plus the two B3 propagators, and the B3 ones went on sending the
trace context in b3 and x-b3-* headers.

Keep the part that was deliberate, which is baggage, and drop the part
that was not.

This costs the span link between a BullMQ publish and the job that
processes it, because that link travels through the propagators. The
agent does not read span links, so nothing reported to AppSignal
changes. The instrumentation's useProducerSpanAsConsumerParent option
would stop working, but it is off by default and we do not turn it on.

Update two test apps' @opentelemetry/api bound

The express-redis and express-rabbitmq apps are the only test apps
whose own code creates spans, so they are the only ones that have to
declare @opentelemetry/api themselves: npm link does not make the
integration's copy available to them the way a normal install would.

Their bound had been left at version 1.6, which the integration stopped
supporting in 2024. Both apps therefore installed one copy of the API
for themselves and resolved a second one inside the linked integration.
Their custom spans still arrived, but only because an older copy of the
API is allowed to read a global registered by a newer one. Had the two
versions been the other way around, the apps would have reported no
custom spans at all and both suites would have failed with no indication
of why.

Check for duplicate @opentelemetry/api copies

Two copies of @opentelemetry/api in one project make the integration
report nothing, without saying so. The API keeps its global tracer
provider on globalThis and a copy only reads that global when its own
version is compatible with the version that wrote it, so the copy that
loses the comparison receives a tracer that discards every span. Nothing
is logged, so no test fails and no user-visible error appears.

Whether that happens is decided by npm's resolution, which depends on
the version bounds in package.json and on what else the application
has installed. It is not visible in the source, so a check is the only
way to hold it.

The check installs the packed package into a throwaway project with an
empty npm cache. Both parts matter. Our own node_modules is not what a
customer resolves, because npm link and our package-lock.json both
change the answer. A populated cache can serve a resolution that a fresh
install would not pick.

Copies of other OpenTelemetry packages are reported but do not fail the
check. The tree currently holds several, and they are wasteful rather
than broken: the API package is the only one whose copies share state
through a version-checked global.

Stop Dependabot from widening version ranges

Dependabot defaults to widening a range for a library, so it turned the
@opentelemetry/sdk-node bound from >= 0.213.0 < 0.214.0 into >= 0.213.0 < 0.219.0. That is the opposite of what these bounds are for.
They are narrow so that the OpenTelemetry packages released together
each resolve to a single version, and a widened bound lets npm resolve a
different version of @opentelemetry/core for sdk-node than for the
rest of the tree, which is what happened.

Group the OpenTelemetry packages too. They are only correct as a set, so
one update covering all of them is reviewable in a way that a pull
request per package is not.

This declaration stood in for a DOM type that the `undici` typings
bundled with `@types/node` referred to, which this project does not pull
in because its `lib` is set to `es2018`. Those typings no longer refer
to it, so the declaration is only a stand-in for nothing.

Leaving it in place breaks the build outright from `@types/node` version
25 onwards, because that version declares `BlobPropertyBag` itself and
TypeScript reports the two declarations as a conflict. That went
unnoticed because the committed `package-lock.json` holds `@types/node`
at version 22, so only an install that resolves versions afresh runs
into it.
@backlog-helper

Copy link
Copy Markdown

Hi @unflxw,

We've found some issues with your Pull Request.

  • This Pull Request is missing labels. Please add labels to help identify types of Pull Requests. - (More info)
  • This Pull Request is missing reviewers. Either convert this Pull Request into a draft or ignore this rule by adding [skip review] to your Pull Request body. - (More info)

New issue guide | Backlog management | Rules | Feedback

@unflxw
unflxw force-pushed the otel-housekeeping branch 3 times, most recently from 4e25540 to 3c37320 Compare August 21, 2026 10:08
@unflxw unflxw changed the title Tidy up the OpenTelemetry dependency declarations Tidy up the OpenTelemetry dependencies and propagators Aug 21, 2026
unflxw added 4 commits August 21, 2026 12:35
Version 3.7.0 set out to stop propagating the trace context, because two
applications that both report to AppSignal would join the same trace and
the second one's data would be reported against the first one's
application. It kept propagating it anyway, for a year.

The pull request that did this first disabled every propagator, which
was reviewed and agreed. A later commit on the same branch added
propagators back, to keep baggage working for customers who use it, and
took the `OTEL_PROPAGATORS` factory map in `@opentelemetry/sdk-node` for
the list of defaults. That map is the set of propagators a user can name
in that environment variable. The defaults are the W3C trace context and
baggage propagators, so "the defaults without trace context" became
baggage plus the two B3 propagators, and the B3 ones went on sending the
trace context in `b3` and `x-b3-*` headers.

Keep the part that was deliberate, which is baggage, and drop the part
that was not.

This costs the span link between a BullMQ publish and the job that
processes it, because that link travels through the propagators. The
agent does not read span links, so nothing reported to AppSignal
changes. The instrumentation's `useProducerSpanAsConsumerParent` option
would stop working, but it is off by default and we do not turn it on.
The `express-redis` and `express-rabbitmq` apps are the only test apps
whose own code creates spans, so they are the only ones that have to
declare `@opentelemetry/api` themselves: `npm link` does not make the
integration's copy available to them the way a normal install would.

Their bound had been left at version 1.6, which the integration stopped
supporting in 2024. Both apps therefore installed one copy of the API
for themselves and resolved a second one inside the linked integration.
Their custom spans still arrived, but only because an older copy of the
API is allowed to read a global registered by a newer one. Had the two
versions been the other way around, the apps would have reported no
custom spans at all and both suites would have failed with no indication
of why.
Two copies of `@opentelemetry/api` in one project make the integration
report nothing, without saying so. The API keeps its global tracer
provider on `globalThis` and a copy only reads that global when its own
version is compatible with the version that wrote it, so the copy that
loses the comparison receives a tracer that discards every span. Nothing
is logged, so no test fails and no user-visible error appears.

Whether that happens is decided by npm's resolution, which depends on
the version bounds in `package.json` and on what else the application
has installed. It is not visible in the source, so a check is the only
way to hold it.

The check installs the packed package into a throwaway project with an
empty npm cache. Both parts matter. Our own `node_modules` is not what a
customer resolves, because `npm link` and our `package-lock.json` both
change the answer. A populated cache can serve a resolution that a fresh
install would not pick.

Copies of other OpenTelemetry packages are reported but do not fail the
check. The tree currently holds several, and they are wasteful rather
than broken: the API package is the only one whose copies share state
through a version-checked global.
Dependabot defaults to widening a range for a library, so it turned the
`@opentelemetry/sdk-node` bound from `>= 0.213.0 < 0.214.0` into `>=
0.213.0 < 0.219.0`. That is the opposite of what these bounds are for.
They are narrow so that the OpenTelemetry packages released together
each resolve to a single version, and a widened bound lets npm resolve a
different version of `@opentelemetry/core` for `sdk-node` than for the
rest of the tree, which is what happened.

Group the OpenTelemetry packages too. They are only correct as a set, so
one update covering all of them is reviewable in a way that a pull
request per package is not.
@unflxw
unflxw force-pushed the otel-housekeeping branch from 3c37320 to 9b455f2 Compare August 21, 2026 10:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant