Last updated: March 26, 2026
Proxy the Ingestion Endpoint
By default, the Dash0 Web SDK sends telemetry directly from your application to Dash0's ingestion endpoints.
This works well, but there are situations where routing that traffic through your own infrastructure makes more sense:
- Auth token security: Keeping credentials server-side rather than exposing them in client bundles
- Ad blocker avoidance: Requests originating from a first-party domain are far less likely to be blocked
- Network policy compliance: Organizations that require all egress traffic to pass through controlled infrastructure
This topic covers what you need to know to set up such a proxy correctly — including common pitfalls around CORS, body size limits, and connection behavior — as well as how to preserve original client IP addresses so geo-location data in Dash0 remains accurate.
General Guidelines
The SDK sends telemetry data to two endpoints adhering to the OpenTelemetry Collector's HTTP/JSON API specification:
POST /v1/tracesPOST /v1/logs
Most reverse proxies — Nginx, Vercel, Envoy, and others — can forward these endpoints with minimal configuration. Following your proxy's standard setup guide is usually enough, but watch out for these gotchas:
- IP address visibility: See separate section below
- CORS: Depending on your targeted setup, your proxy must handle CORS preflight (
OPTIONS) requests and return appropriateAccess-Control-Allow-*headers - Body Size: The SDK batches requests. Ensure your proxy can handle request bodies up to ~512KB
- Keepalive: The SDK uses the
fetchAPI withkeepalive: truefor smaller payloads, which allows requests to complete even after page navigation. Ensure your infrastructure supports this behavior
Browsers cap keepalive request bodies at 64KB. Payloads larger than this automatically fall back to a standard fetch without keepalive, meaning they may not complete if the user navigates away before the request finishes. If losing in-flight data on navigation is a concern, consider reducing the SDK's batch size.
IP Addresses
When you deploy a proxy between your applications and Dash0, all telemetry data flows through the proxy before reaching Dash0.
This architecture introduces a challenge: Dash0 only observes the outbound requests from the proxy itself, not from the original clients and specifically their web browsers.
- Dash0 uses the proxy's IP address as the
source.addressfor all telemetry - Geo-location enrichment reflects the proxy's location rather than the actual client locations
- All sessions appear to originate from a single IP address (wherever your proxy is hosted)
To preserve the original client IP addresses and enable accurate geo-location enrichment, configure your proxy to forward the X-Forwarded-For header downstream to Dash0.
This approach only works when the X-Forwarded-For header is already present in requests arriving at the proxy. This header is typically set automatically when requests pass through load balancers, reverse proxies, or API gateways before reaching the proxy. If your telemetry is sent directly from applications to the proxy without any intermediary infrastructure, the header will not be available.
Proxying via the OpenTelemetry Collector
If you're already running an OpenTelemetry Collector in your infrastructure, you can use it as the proxy.
The configuration below threads the X-Forwarded-For header through the full Collector pipeline so that Dash0 receives the original client IP addresses rather than the Collector's own address.
Capture Inbound Metadata on the OTLP Receiver
Configure your OTLP receiver to capture the X-Forwarded-For header from incoming requests.
12345receivers:otlp:protocols:http:include_metadata: true
Preserve the Header Through the Pipeline
Ensure the captured header is maintained as telemetry data flows through your processing pipeline.
1234processors:batch:metadata_keys:- X-Forwarded-For
Reattach the Header on Outgoing Requests
Configure the OTLP exporter to include the X-Forwarded-For header when forwarding telemetry to Dash0.
123456789101112131415161718extensions:headers_setter:headers:- action: insertkey: Authorizationvalue: "Bearer ${env:DASH0_TOKEN}"- action: insertkey: X-Forwarded-Forfrom_context: X-Forwarded-Forexporters:otlp:endpoint: "{{endpoint_otlp_grpc_hostname}}:{{endpoint_otlp_grpc_port}}"auth:authenticator: headers_setterservice:extensions: [headers_setter]
The headers_setter extension handles both authentication and header forwarding in a single place. If you are already using a headers_setter extension elsewhere in your Collector configuration, merge these entries into your existing definition rather than declaring a second one.
Result
With this configuration in place, Dash0 will receive the X-Forwarded-For header containing the original client IP addresses.
This enables Dash0 to perform GeoIP resolution based on the actual client locations rather than the Collector's address, providing accurate geo-location data for your telemetry.