Automatic injection, first-party beacons and CSP

You can paste the tag by hand, but on a machine with the server agent you often don't have to. This page covers three related topics: how the agent puts the tag on pages by itself, how to route everything through your own domain, and what your Content Security Policy needs to allow.

Injection through nginx

On Linux, the agent reads nginx's resolved configuration, lists the virtual hosts, and probes each one the way a browser would. For every site that answers with HTML, it creates an application and adds the tag. It does this through one file, /etc/nginx/conf.d/00-obscenter-rum.conf, which uses nginx's sub_filter to insert the tag before </head>, plus the one line described below where a vhost needs it, and then reloads nginx. It does not edit your pages or your application. sudo obscenter-agent rum --disable removes the file and every such line and keeps them out; switching off measure the browsers on sites these machines serve in Settings takes the tag out on every machine.

• The tag it inserts carries the nginx request id as data-trace, so the page load is linked to the request that served it.
• sub_filter cannot rewrite a body the backend has already compressed. For tagged sites only, the file therefore asks the backend for uncompressed HTML. nginx can still compress the response on its way to the visitor.
• Where a location block sets proxy headers of its own, nginx does not inherit them from the http level. In that case the agent adds one marked line (# obscenter-ae) inside that block. Adding and removing the line is idempotent and exactly reversible.
• Every change is tested with nginx -t before a reload, and undone if the test fails.
• It needs nginx's http_sub_module, and the machine must allow the agent to write configuration. That permission is on by default for a new install. See Instrumentation.
• Up to 20 sites per machine are tagged this way.

Injection inside a Node.js service

On a machine with no nginx, the agent inside an instrumented Node.js service can add the tag itself. It works out the site from the Host header of the requests it answers, and checks that name against DNS before adopting it. It rewrites a response only when all of these hold:

• the response is text/html, not already encoded, and has a 2xx status;
• the request is not HEAD;
• the headers have not been sent yet;
• </head> appears in the first 64 KB.

Anything else is left untouched. On any error it falls back to the original response.

A page never gets two tags from these two paths. Each site records which agent found it. nginx wins a tie, because it sits at the edge in front of every backend.

Turning it off

• For the whole install: in Settings, untick measure the browsers on sites these machines serve. The tags come off within a minute. No application and no data is deleted.
• For one site: on the host's settings page, under Web sites on this machine, choose leave alone. Measure again undoes it.
• For one machine: run sudo obscenter-agent rum --disable, which removes the file and the marked lines, or set OBSCENTER_NO_RUM=1 in the agent's environment. obscenter-agent rum lists the sites that carry the tag.

Serving it from your own domain

By default the tag loads from your install and reports to it. That means a second origin in your CSP, a CORS request for every beacon, and an address that privacy extensions may block. Install → Web application → Serve it from your own domain moves all of it onto your site's own origin. Your web server proxies one path, /_o/, back to the collector, and the tag, the measurements and the replay recorder all travel through it.

1. Press Generate the secret. The page shows an nginx location block that contains it.
2. Paste the block into your site's server block, run nginx -t, and reload nginx.
3. Replace your tag with the one the page shows, which points at your own origin.

The secret matters. Once your web server forwards the beacons, every hit arrives from that server's address. The secret is what makes the collector believe the visitor address your server passes along. Without it, the whole site would read as one visitor in one country. This is why the secret lives in the server configuration and not in the page. Rotating it takes effect immediately, so edit nginx in the same sitting. Turn it off stops accepting forwarded addresses for the application.

The block also blanks Cookie and Authorization on the way through, so your visitors' credentials never reach the collector. An instrumented Node.js service can serve the same /_o/ paths itself, without nginx.

Content Security Policy

Setup	script-src	connect-src
Plain tag from your install	your install's origin (the tag and the replay recorder)	your install's origin (/collect, /collect/replay, /rum-config)
First-party (/_o/)	'self'	'self'

With a nonce-based policy, use the inline loader from Application settings → Tag to paste. It copies its nonce onto the script it creates, and the tag copies its own nonce onto the replay recorder. When the agent inside a Node.js service injects the tag, it also adds the collector origin to that response's script-src and connect-src. It never widens a policy of 'none' or one that uses 'strict-dynamic'.

Linking the page to the backend

A page load cannot carry a request header, so the trace id comes back the other way. nginx and the in-process agent write it into the tag, or return it in a Server-Timing entry. For calls the page makes, the tag adds traceparent to the origins you trace. New applications trace same-origin by default, which you can change under Application settings → Backend correlation. With also send which visitor and session the request belongs to ticked (the default), a baggage header goes along too. An API on another origin must allow both headers in its CORS answer: Access-Control-Allow-Headers: traceparent, baggage.