Overview

If you need to proxy telemetry requests through your own infrastructure (e.g., to avoid ad blockers or to keep the auth token server-side), here's what you need to know.

General Guidelines

The SDK sends telemetry data to two endpoints adhering to the OpenTelemetry Collector's HTTP/JSON API specification:

POST /v1/traces
POST /v1/logs

You can proxy these endpoints using Nginx, Vercel, Envoy, and many others. Most of the time, following the proxies' general guidelines is sufficient. Watch out for these gotchas though:

IP address visibility: See separate section below
CORS: Depending on your targeted setup, your proxy must handle CORS preflight (OPTIONS) requests and return appropriate Access-Control-Allow-* headers
Body Size: The SDK batches requests. Ensure your proxy can handle request bodies up to ~512KB
Keepalive: The SDK uses the fetch API with keepalive: true for smaller payloads, which allows requests to complete even after page navigation. Ensure your infrastructure supports this behavior

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.address for 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.

info

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

Capture Inbound Metadata on the OTLP Receiver

Configure your OTLP receiver to capture the X-Forwarded-For header from incoming requests.

yaml

12345
receivers:
  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.

yaml

1234
processors:
  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.

yaml

123456789101112131415161718
extensions:
  headers_setter:
    headers:
    - action: insert
      key: Authorization
      value: "Bearer ${env:DASH0_TOKEN]"
    - action: insert
      key: X-Forwarded-For
      from_context: X-Forwarded-For

exporters:
  otlp:
    endpoint: "{{endpoint_otlp_grpc_hostname}}:{{endpoint_otlp_grpc_port}}"
    auth:
      authenticator: headers_setter

service:
  extensions: [headers_setter]

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.

Proxying the ingestion endpoint

Overview

General Guidelines

IP Addresses

Proxying via the OpenTelemetry Collector

Capture Inbound Metadata on the OTLP Receiver

Preserve the Header Through the Pipeline

Reattach the Header on Outgoing Requests

Result