Pin the OpenTelemetry SDK 2.x generation in the docs #1344

Problem

OpenTelemetry JS SDK 3.x became the latest version on npm on 20 October 2026. Fedify 2.x is built against the 2.x generation: @opentelemetry/sdk-trace-base ^2.7.1, @opentelemetry/core ^2.7.1, @opentelemetry/sdk-metrics 2.7.1, and @opentelemetry/api ~1.9.1. SDK 2.x peers require @opentelemetry/api below 1.10, while SDK 3.x requires 1.10 or later, so the two generations cannot be installed as direct dependencies in one project.

The manual still tells readers to install the SDK without a version:

npm add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto

That command installs @opentelemetry/sdk-node 0.300.0, which requires @opentelemetry/api 1.10. The advanced examples then install @opentelemetry/sdk-trace-base, and npm fails with a peer dependency conflict:

npm error Conflicting peer dependency: @opentelemetry/api@1.9.1
npm error   peer @opentelemetry/api@">=1.3.0 <1.10.0" from @opentelemetry/sdk-trace-base@2.12.0
npm error   peer @opentelemetry/api@">=1.10.0 <1.11.0" from @opentelemetry/sdk-node@0.300.0

Affected sections

• docs/manual/opentelemetry.md installs @opentelemetry/sdk-node and @opentelemetry/exporter-trace-otlp-proto without versions, and its examples import BasicTracerProvider, SimpleSpanProcessor, and NodeTracerProvider from the 2.x packages.
• docs/manual/debug.md has an advanced setup with the same imports.
• docs/package.json already resolves the 2.x generation through the workspace catalog, so the Twoslash examples build. Only the prose install commands are unversioned.

Proposed change

Pin every install command to the generation Fedify 2.x supports:

• @opentelemetry/sdk-node@^0.211.0
• @opentelemetry/exporter-trace-otlp-proto@^0.211.0
• @opentelemetry/sdk-trace-base@^2.7.1
• @opentelemetry/sdk-trace-node@^2.7.1
• @opentelemetry/context-async-hooks@^2.7.1
• @opentelemetry/core@^2.7.1

Add a short compatibility note to the setup section: Fedify 2.x pairs with OpenTelemetry JS SDK 2.x, and SDK 3.x support is planned for Fedify 3.0. Link the note to #1345. Mention --legacy-peer-deps only as a stopgap for existing projects, not as the recommended fix.

Keep the examples on @opentelemetry/sdk-trace-node and @opentelemetry/sdk-trace-base. @opentelemetry/sdk-trace-node has no 3.x release; its replacement is @opentelemetry/sdk-trace, which #1345 covers.

Branch and release

Fix this on 2.4-maintenance and cut a 2.4.x patch release. Forward-port the same change to main. Docs deploy from tag pushes and from main, so the website shows the fix after either the 2.4.x tag or the forward-port.

No changelog fragment: the change only corrects documentation.

Acceptance criteria

• No install command in the manual uses an unversioned OpenTelemetry package.
• A strict-peer npm install of the documented set succeeds in an empty project.
• mise run docs:build and mise run check:md pass.
• The compatibility note states which SDK generation Fedify 2.x supports.

Out of scope

Migrating the examples to SDK 3.x. That is tracked in #1345.