Skip to main content

Use a proxy URL

Every Coralogix Real User Monitoring (RUM) SDK sends its data straight to the Coralogix ingress. However, some content blockers and corporate firewalls reject Coralogix domains and drop your data on its way to Coralogix. This means Coralogix can't monitor users whose browsers blocked the request.

To make sure your data reaches Coralogix, create and host a proxy server on your own domain to relay your outgoing data to Coralogix. The proxy keeps the public key out of your pages, lets you inspect the data before it leaves your network, and makes sure your data reaches Coralogix without being blocked. This article explains how to build one with Node.js or Nginx, though you can use any server-side technology that can accept POST requests over HTTPS and forward them to Coralogix.

Coralogix does not host the proxy for you

Coralogix has chosen not to offer a custom-domain reverse proxy for Real User Monitoring the way some vendors do. Relaying telemetry through customer-branded domains expands the attack surface, complicates tenant isolation at ingestion, and obscures the data flow from end users and their compliance teams. Beacons sent straight to Coralogix under a per-tenant token keep the data processor relationship auditable and simpler to govern under GDPR, so first-party collection on your own infrastructure is the supported answer to ad blockers.

What you need​

  • A server you control that can accept POST requests over HTTPS and reach ingress.<region>.rum-ingress-coralogix.com, where <region> is the region associated with your Coralogix domain. For example, eu1.
  • A Coralogix RUM application with its public key. The proxy holds the key instead of your pages.
  • One of the RUM SDKs installed in your application.

Because the proxy runs entirely on your infrastructure, you don't need any Coralogix permissions.

How it works​

When you initialize the SDK, it checks whether the proxyUrl parameter holds a proxy server's address. When it does, the SDK sends every request to that address instead of to Coralogix. To let your proxy know which Coralogix endpoint the request was bound for, the SDK appends a cxforward query parameter to that URL.

This example uses the Browser SDK:

CoralogixRum.init({
// ...
coralogixDomain: 'EU1',
proxyUrl: 'https://www.example.com/rum',
});

The SDK builds the cxforward value on every request from your coralogixDomain and the endpoint for the kind of data it is sending. Set coralogixDomain to your Coralogix region in uppercase, such as EU1. The region appears in lowercase only inside the ingress hostname. When your account ingress has no region key, set the coralogixDomainUrl parameter to the full ingress URL instead.

The value is URL-encoded so that it survives as a parameter value. For example, a proxy URL relaying RUM events to the EU1 ingress looks like this:

https://www.example.com/rum?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Fv1beta%2Flogs

The request goes to your proxy at https://www.example.com/rum, and cxforward tells it to relay the request body to https://ingress.eu1.rum-ingress-coralogix.com/browser/v1beta/logs. Everything the proxy needs in order to route a request is in that one parameter, so the proxy needs no per-endpoint configuration of its own.

proxyUrl must not include a query string

The SDK appends ?cxforward= to proxyUrl as it appears. When proxyUrl already contains a query string, the request URL ends up with two ? and the request fails.

Every RUM SDK accepts the proxy server's address in the same optional proxyUrl parameter:

Authorization​

When the public key is set in the SDK, both kinds of request carry an Authorization: Bearer <public key> header. Your proxy can forward that header unchanged, or leave the key out of the SDK altogether and add the header itself. See Build your proxy.

Traffic the proxy does not carry​

The proxy carries only the data the SDK sends, never the files it loads. A Browser SDK installed from the CDN downloads its script from cdn.rum-ingress-coralogix.com, and Session Recording loads its compression library from the same host, falling back to cdnjs.cloudflare.com. When both hosts are blocked, Session Recording stops, and a proxy does not change that.

The SDK also keeps its own calls to the proxy out of the network events it reports, so they never appear in your RUM data.

Handling RUM events vs recording uploads​

Each request's cxforward parameter names one Coralogix ingress endpoint, chosen by the kind of data the request carries:

Data typeEndpointBody
RUM events: logs, errors, network requests, Web Vitals, and user interactions/browser/v1beta/logsJSON, with Content-Type: application/json
Recording uploads: Session Recording segments and screenshots/browser/alpha/sessionrecordingmultipart/form-data, with a chunk field and a metaData field

Recording uploads​

The ingress endpoint for recording uploads is included in cxforward, but requests of this type have a different kind of body. Session Recording does not send a session's recording as a single file at the end of the session. Rather, the SDK uploads that recording continuously in segments of up to 1 MB, one request per segment.

A multipart/form-data body is divided into named fields, each with its own headers and its own encoding. A recording upload uses both:

  • chunk: Recording data itself, gzip-compressed by the SDK.
  • metaData: JSON object describing the segment, sent uncompressed.

For example, a recording upload might look like this:

POST /rum?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Falpha%2Fsessionrecording HTTP/1.1
Host: www.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryAbc123
Content-Encoding: gzip

------WebKitFormBoundaryAbc123
Content-Disposition: form-data; name="chunk"
Content-Type: application/octet-stream

<gzip-compressed recording bytes>
------WebKitFormBoundaryAbc123
Content-Disposition: form-data; name="metaData"

{"segmentIndex":0,"segmentSize":48213,"segmentTimestamp":1762425600000,"sessionCreationDate":1762425000000,"sessionId":"0f9c4a1e","snapshotId":"","application":"my-app","subIndex":-1}
------WebKitFormBoundaryAbc123--

In this example, the Content-Type header specifies the boundary string that tells the receiver where one field ends and the next begins. The request-level Content-Encoding: gzip describes the chunk field alone: the body as a whole is a multipart envelope, not a gzip stream, so a proxy that reads that header and decompresses the body corrupts the recording. Both are why the proxy has to forward the body unchanged.

Requests without the cxforward parameter​

With some SDKs, cxforward can be omitted altogether. The Browser SDK and the Roku SDK let you remove it by setting ignoreProxyUrlParams to true.

Since the proxy server uses the endpoint included in the cxforward parameter to relay data based on its content type, requests without the parameter arrive at the proxy with nothing for it to route on. Your proxy must therefore tell them apart by examining the content type: multipart/form-data indicates a recording upload; application/json indicates RUM events.

Build your proxy​

Your proxy must do all the following with every request it receives:

  1. Forward to a fixed ingress: Send requests to https://ingress.<region>.rum-ingress-coralogix.com, or to the URL you set in coralogixDomainUrl. Take only the path from the cxforward query parameter, and only when that path is /browser/v1beta/logs or /browser/alpha/sessionrecording. Reject anything else.
  2. Forward the body unchanged: Pass the bytes through as received, with the Content-Type header, which carries the multipart boundary, and Content-Encoding. Do not decompress a recording upload.
  3. Authenticate: Forward the Authorization header, or set Authorization: Bearer <public key> on the proxy and leave the public key out of the SDK's initialization.
  4. Forward the user's IP address: Coralogix reads the user's address from the first public address in X-Forwarded-For and derives their location from it, so append the client address to that header. Without it, every user appears to be located wherever the proxy runs. This does not apply when collectIPData is false. The address also has to be in a form Coralogix reads as public, so see Troubleshooting when every user resolves to the same place.
  5. Return the same status code Coralogix returns: The SDK does not retry a failed request, and a failed recording upload stops Session Recording for the rest of the session.
  6. Accept bodies of at least 4 MB: A recording segment reaches 1 MB, and the multipart envelope around it adds more, so a request can exceed 1 MB.
  7. Serve on HTTPS: A page served over HTTPS cannot send requests to an http:// proxy.
  8. Drop cookies: When the proxy shares your application's origin, the browser sends your site's cookies with every request. Do not pass them on to Coralogix.
A proxy that trusts cxforward is an open relay

The client controls cxforward, so a proxy that forwards to whatever URL the parameter names lets anyone use your server to send requests to any host. Fix the ingress host on the server and take only the path from cxforward.

Host your proxy​

When possible, serve the proxy from the same origin as your application, for example as a /rum path on the reverse proxy or load balancer that already serves your site. The requests then go to your own domain, and the browser sends no Cross-Origin Resource Sharing (CORS) preflight.

When the proxy has an origin of its own, such as https://rum.example.com, it must answer that preflight. Respond to OPTIONS with these headers, and send Access-Control-Allow-Origin on the POST response as well:

  • Access-Control-Allow-Origin: your application's origin
  • Access-Control-Allow-Methods: POST, OPTIONS
  • Access-Control-Allow-Headers: Content-Type, Content-Encoding, Authorization

Server examples​

Both examples satisfy every item in Build your proxy. Replace eu1 with your own region.

Node.js​

This server has no dependencies and runs on Node.js 22 or later. It answers CORS preflights from the origins in ALLOWED_ORIGINS:

// In rum-proxy.mjs
// Relays Coralogix RUM SDK requests to the Coralogix ingress
import { createServer } from 'node:http';

const PORT = Number(process.env.PORT ?? 8080);
// Your Coralogix region's ingress, for example https://ingress.eu1.rum-ingress-coralogix.com
const INGRESS_URL = process.env.CORALOGIX_INGRESS_URL;
// Optional. When set, the proxy adds the key, so the page does not need to carry it.
const PUBLIC_KEY = process.env.CORALOGIX_PUBLIC_KEY;
// Comma-separated origins allowed to call the proxy, for example https://www.example.com.
// Not required when the proxy is served from the same origin as your application.
const ALLOWED_ORIGINS = new Set(
(process.env.ALLOWED_ORIGINS ?? '')
.split(',')
.map((origin) => origin.trim())
.filter(Boolean)
);

// The two endpoints the SDK sends to. The proxy forwards nothing else.
const CORALOGIX_PATHS = new Set([
'/browser/v1beta/logs',
'/browser/alpha/sessionrecording',
]);
const FORWARDED_HEADERS = ['content-type', 'content-encoding', 'authorization'];
const MAX_BODY_BYTES = 4 * 1024 * 1024;
const UPSTREAM_TIMEOUT_MS = 30_000;

if (!INGRESS_URL) {
console.error('Set CORALOGIX_INGRESS_URL to your Coralogix ingress URL.');
process.exit(1);
}

createServer(async (req, res) => {
// 1. Answer the browser's CORS preflight, and refuse anything that is not a POST.
setCorsHeaders(req, res);
if (req.method === 'OPTIONS') return reply(res, 204);
if (req.method !== 'POST') return reply(res, 405);

// 2. Work out the Coralogix path from cxforward. A request including anything
// other than the two SDK endpoints is rejected rather than forwarded.
const path = coralogixPath(req.url);
if (!path) return reply(res, 400);

// 3. Buffer the body, rejecting anything over the size limit with 413.
// The bytes are never decoded: a recording upload must reach Coralogix as it was sent.
let body;
try {
body = await readBody(req);
} catch {
return reply(res, 413);
}

// 4. Relay the request to Coralogix and return its status code to the SDK.
// A non-2xx on a recording upload stops Session Recording for that session.
try {
const upstream = await fetch(`${INGRESS_URL}${path}`, {
method: 'POST',
headers: upstreamHeaders(req),
body,
signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
});
// Read the whole response first. If it fails, the catch block can still send its own status code.
const responseBody = Buffer.from(await upstream.arrayBuffer());
res.writeHead(upstream.status, {
'content-type': upstream.headers.get('content-type') ?? 'text/plain',
});
res.end(responseBody);
} catch (error) {
console.error('Forwarding to Coralogix failed:', error);
reply(res, 502);
}
}).listen(PORT, () => console.log(`RUM proxy listening on port ${PORT}`));

// The SDK sets the Coralogix endpoint in the `cxforward` query parameter.
// Only its path is used. The host always comes from INGRESS_URL, so a caller cannot make the proxy send requests anywhere else.
function coralogixPath(requestUrl) {
try {
const cxforward = new URL(requestUrl, 'http://proxy').searchParams.get('cxforward');
if (!cxforward) return null;
const { pathname } = new URL(cxforward);
return CORALOGIX_PATHS.has(pathname) ? pathname : null;
} catch {
return null;
}
}

function upstreamHeaders(req) {
const headers = {};
for (const name of FORWARDED_HEADERS) {
if (req.headers[name]) headers[name] = req.headers[name];
}
if (PUBLIC_KEY) headers.authorization = `Bearer ${PUBLIC_KEY}`;

// Read the client's address off the socket and append it to X-Forwarded-For,
// preserving any addresses an upstream load balancer already set. Coralogix
// locates the user from the first public address in that header. Node reports
// IPv4 clients as ::ffff:a.b.c.d, which Coralogix does not read as public, so
// strip the prefix.
const clientIp = req.socket.remoteAddress?.replace(/^::ffff:/, '');
headers['x-forwarded-for'] = [req.headers['x-forwarded-for'], clientIp]
.filter(Boolean)
.join(', ');
return headers;
}

function readBody(req) {
return new Promise((resolve, reject) => {
const chunks = [];
let size = 0;
req.on('data', (chunk) => {
size += chunk.length;
if (size > MAX_BODY_BYTES) reject(new Error('Request body too large'));
else chunks.push(chunk);
});
req.on('end', () => resolve(Buffer.concat(chunks)));
req.on('error', reject);
});
}

function setCorsHeaders(req, res) {
const { origin } = req.headers;
if (!origin || !ALLOWED_ORIGINS.has(origin)) return;
res.setHeader('access-control-allow-origin', origin);
res.setHeader('access-control-allow-methods', 'POST, OPTIONS');
res.setHeader(
'access-control-allow-headers',
'Content-Type, Content-Encoding, Authorization'
);
res.setHeader('access-control-max-age', '86400');
res.setHeader('vary', 'Origin');
}

function reply(res, status) {
res.writeHead(status).end();
}

Run it with your region's ingress and your application's origin. To add the key on the proxy, also set CORALOGIX_PUBLIC_KEY:

CORALOGIX_INGRESS_URL=https://ingress.eu1.rum-ingress-coralogix.com \
ALLOWED_ORIGINS=https://www.example.com \
node rum-proxy.mjs

The server listens over plain HTTP, so run it behind the load balancer or ingress controller that terminates TLS for your domain. When that load balancer sets X-Forwarded-For, the proxy keeps the user's address from it and appends its own peer's address, which Coralogix skips because it is not public.

To deploy it as a container, build this image:

FROM node:24-alpine
WORKDIR /app
COPY rum-proxy.mjs .
USER node
EXPOSE 8080
CMD ["node", "rum-proxy.mjs"]

Build the image, then pass the same variables to the container. The proxy exits at startup when CORALOGIX_INGRESS_URL is unset:

docker build -t rum-proxy .

docker run -p 8080:8080 \
-e CORALOGIX_INGRESS_URL=https://ingress.eu1.rum-ingress-coralogix.com \
-e ALLOWED_ORIGINS=https://www.example.com \
rum-proxy

Nginx​

When Nginx serves your application, add a location that relays to Coralogix from the same origin. Put the map block in the http context and the location block in your application's server block:

# Pick the Coralogix endpoint from the SDK's cxforward parameter. Nginx sees the parameter still URL-encoded, so match on how it ends.
map $arg_cxforward $coralogix_path {
default "";
"~%2Fbrowser%2Fv1beta%2Flogs$" /browser/v1beta/logs;
"~%2Fbrowser%2Falpha%2Fsessionrecording$" /browser/alpha/sessionrecording;
}

server {
# ...your existing configuration for www.example.com...

location = /rum {
if ($coralogix_path = "") {
return 400;
}

# Recording uploads can exceed the 1 MB default.
client_max_body_size 4m;

# Resolve the ingress at request time rather than once at startup.
# Use your network's DNS resolver.
resolver 8.8.8.8 valid=60s;
set $coralogix_ingress ingress.eu1.rum-ingress-coralogix.com;

proxy_pass https://$coralogix_ingress$coralogix_path;
proxy_ssl_server_name on;
proxy_ssl_verify on;
proxy_ssl_verify_depth 2;
# Your system's CA bundle. Debian, Ubuntu and Alpine use the path below;
# RHEL and CentOS use /etc/pki/tls/certs/ca-bundle.crt.
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;

# Nginx forwards the client's Authorization header by default.
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Requests from your own origin carry your site's cookies. Do not send them on.
proxy_set_header Cookie "";
# Optional: add the key here and leave it out of the SDK's initialization.
# proxy_set_header Authorization "Bearer <your public key>";
}
}

Because proxy_pass names its target with variables, Nginx sends the request to the Coralogix path alone, without the cxforward parameter.

Verify the setup​

Make sure your proxy is reachable from the browser and that it forwards requests to Coralogix:

  1. Load your application with the browser's developer tools open. On the Network tab, requests to your proxy's address carrying a cxforward parameter return 200.
  2. Confirm the data arrives in Coralogix. Select RUM, then Sessions, and find the session you just generated.
  3. To test the proxy without a browser, send it an empty batch of events. A 200 response means the request reached Coralogix and the key was accepted. When the response code is 403, the request doesn't have a key.

The command below carries the key itself. When your proxy adds the key instead, leave the Authorization header out:

curl -i -X POST \
'https://www.example.com/rum?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Fv1beta%2Flogs' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <public key>' \
--data '{"logs":[]}'

Troubleshooting​

Several of the symptoms below surface as log output. The Browser SDK reports its own failures to the browser console, so open developer tools before you reproduce a problem. The other SDKs report theirs to their platform's log output, and most of them expose a debug option that raises the verbosity.

SymptomCauseWhat to do
Every user is located wherever the proxy runsThe proxy does not append the client address to X-Forwarded-ForAppend it. On Node.js, strip the ::ffff: prefix that IPv4 clients arrive with, because Coralogix does not read that form as a public address
The proxy returns 400 to every requestproxyUrl carries a query string of its own, so cxforward never arrivesRemove the query string from proxyUrl
Session Recording stops a few seconds into a sessionThe proxy rejected a recording upload, most often on a body-size limit below 4 MBRaise the limit to at least 4 MB. A non-2xx response to a recording upload stops Session Recording for the rest of the session
Recordings arrive but do not play backThe proxy decompressed the body of a recording uploadForward the body unchanged, along with Content-Type and Content-Encoding
No requests reach the proxy, and the console reports a CORS errorThe proxy runs on its own origin and does not answer the preflightAdd the CORS response headers listed in Where to host the proxy
The console logs rumAuth will be required in the future on every page loadThe public key is left out of the SDK's initialization so the proxy can add itExpected. Requests the proxy authenticates still reach Coralogix
The SDK never initializes and nothing reaches the proxy, and the console logs Initialization abortedcoralogixDomain is missing, or set to something other than a known region key, most often the region in lowercaseSet it to your region in uppercase, such as EU1. The region appears in lowercase only inside the ingress hostname. When your ingress is not one of the listed regions, set coralogixDomainUrl to the full URL instead

Learn more​

Last updated on