feat(otlp-exporter-base): accept fetch parameter in createFetchTransport, and export createFetchTransport and createRetryingTransport

[zakcutner]

Which problem is this PR solving?

I'm using OpenTelemetry JS in Cloudflare Workers and I need to send telemetry to a collector running in a private network via Workers VPC. Workers VPC provides a custom fetch function that can route requests through private networks, but there was no way to easily pass this to the OTLP exporters.

Before this change, the only way to achieve this was to create a custom version FetchTransport, which would require duplicating much of its implementation, or to monkey patch globalThis.fetch.

Specifying a custom fetch function could also be useful for other scenarios like adding request/response interceptors, using fetch polyfills, or testing with mocks.

Short description of the changes

Adds a fetch configuration option to createFetchTransport, allowing users to provide a custom fetch implementation instead of using globalThis.fetch.

Exports createFetchTransport and createRetryingTransport, so these can be used in place of a new OTLPTraceExporter().

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

• Unit tests for FetchTransport using custom fetch
• Ran npm test

Checklist:

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

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: zakcutner / name: Zak Cutner (653f26f)

[zakcutner]

@blumamir @hectorhdzg @JacksonWeber @martinkuba @maryliag @raphael-theriault-swi @svetlanabrennan Would it be possible for a review of these changes, when you get a moment? I'm also happy to open an issue for discussion or change the approach if you would prefer. Sorry for the pings by the way, the contributing guide included that I should @ the approvers on my PR.

[pichlermarc]

@zakcutner - my original idea was to provide an interface for people to pass their own transports to the exporters, because different transport implementations are so widely requested.

My idea was that people would be able to do something like this, but I ran out of time to work on it:

const exporter = createOtlpExporter({
  serializer: ProtobufTraceSerializer,
  transport: createMyCustomFetchTransport() // returns a custom IExporterTransport impl
});

the underlying implementation is already somewhat setup for such a thing, but requires a bit more boilerplate

import { createOtlpNetworkExportDelegate } from '@opentelemetry/otlp-exporter-base';
import { ProtobufTraceSerializer } from `@opentelemetry/otlp-transformer`;

const exporter: SpanExporter = new createOtlpExportDelegate({
  options: { /** provide all required options accoding to type**/ },
  serializer: ProtobufTraceSerializer, // or JsonTraceSerializer
  transport: createMyCustomFetchTransport() /** implement this yourself, a wrapper around your custom fetch, make sure to set the content-type header to what you're sending: `application/x-protobuf` or `application/json` **/
}); /* delegate happens to match the SpanExporter type, this won't work for metrics today though, because some methods are missing */

I suppose this is what you mean by

the only way to achieve this was to create a custom version FetchTransport, which would require duplicating much of its implementation

IMO this is a good enough workaround for now. Once we drop support for older Node.js versions (around July 2026), we can also finally use fetch in Node.js. Then, all HTTP-based exporters (json/protobuf) will use fetch as a transport regardless of runtime. Introducing that feature then will not result in it being a no-op on Node.js (as is the case in the proposal of this PR) and will therefore be a lot easier to justify adding.

[pichlermarc]

So my recommendation for this feature is:

• decline for now
• use workaround for the time being
• drop node:http based exporter transport in July 2026
• add this feature as proposed in this PR to the now streamlined interface where it also works for Node.js
• feature is released alongside SDK 3.0, everybody can use it

[zakcutner]

@pichlermarc Thank you so much for the review, and apologies for the delay getting back to you!

Your suggestion makes sense to me, but I noticed that a few things are missing to achieve this workaround:

1. createRetryingTransport is not exported.
2. createFetchTransport is not exported.
3. createFetchTransport does not support providing a custom fetch implementation.

I've reduced the scope of the change to fix these three limitations, so I can replace new OTLPTraceExporter() with something like the following, as you described.

createOtlpNetworkExportDelegate(
  getSharedConfigurationDefaults(),
  JsonTraceSerializer,
  createRetryingTransport({
    transport: createFetchTransport({
      fetch: myCustomFetch,
      headers: { "Content-Type": "application/json" },
    }),
  }),
)

When you get a moment, let me know what you think 😄

[overbalance]

please add FetchTransportParameters as well

[overbalance]

if the user-provided fetch already has __original, it gets wiped out since this runs unconditionally. it would be good to have a test for that case also

[overbalance]

it looks like fetchStub will execute, increasing its call count. you might want to call it directly: sinon.stub().resolves(new Response('test response', { status: 200 }));

[overbalance]

a custom fetch function might not have the same structure as the default browser fetch, potentially creating an issue with code that does very specific checks like this. we probably want to call out this one in particular in the docs since retry is an important feature

[overbalance]

i recommend checking that fetch is a function so this fails early if it's not callable. if the failure occurs inside send(), it may look like the wrong kind of error

[overbalance]

Of course, my comments only apply if js core team approves.