feat(@effect/platform): add tracer header filter combinators to HttpClient

[Zelys-DFKH]

Type

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update

Description

Closes #6198.

HttpClient currently records every request and response header as an OTEL span attribute with no way to filter them. If you've ever looked at a span from a Notion API call and seen 30+ entries (cf-ray, alt-svc, server, x-cache, strict-transport-security, all the CDN noise), you know exactly why this matters. Sensitive headers like cookies and auth tokens end up in trace backends too, which is the harder problem.

This PR adds three combinators:

• withTracerRequestHeadersFilter(predicate): filter which request headers are recorded as span attributes
• withTracerResponseHeadersFilter(predicate): filter which response headers are recorded as span attributes
• withTracerHeadersFilter(predicate): set the same predicate for both at once (the common case)

const allowedHeaders = new Set(["content-type", "x-request-id"])

const client = (yield* HttpClient.HttpClient).pipe(
  HttpClient.withTracerHeadersFilter((name) => allowedHeaders.has(name))
)

Each combinator is backed by a FiberRef, so the filter scopes to the effect it wraps and doesn't bleed into other clients. The default is constTrue, so existing behavior is unchanged.

The implementation follows the same FiberRef + globalValue + dual + transformResponse pattern as withTracerDisabledWhen and withTracerPropagation. Once I found those, the rest slotted in pretty naturally.

I went with three functions instead of one because request and response filtering are genuinely independent needs. You might want to capture all request headers for debugging but strip CDN noise from responses, or vice versa. Happy to collapse to a single combinator if you'd prefer a smaller API surface.

Thanks for building Effect — it's a genuinely well-designed library and I'm glad to contribute back.

Related

• Closes HttpClient: allow filtering HTTP header span attributes (e.g. allowlist) #6198

[changeset-bot]

🦋 Changeset detected

Latest commit: f9b1fe7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 31 packages

Name	Type
@effect/platform	Patch
@effect/cli	Patch
@effect/cluster	Patch
@effect/experimental	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-node-shared	Patch
@effect/platform-node	Patch
@effect/rpc	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-drizzle	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-node	Patch
@effect/sql	Patch
@effect/workflow	Patch
@effect/ai	Patch
@effect/ai-amazon-bedrock	Patch
@effect/ai-anthropic	Patch
@effect/ai-google	Patch
@effect/ai-openai	Patch
@effect/ai-openrouter	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/sql-kysely	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tim-smart]

Effect v3 is under a feature freeze, feel free to move this contribution to the effect-smol repository.