Connecting an HTML / JavaScript site (browser) with OTel
Any site with no build step needs one <script> tag; your Spitfire serves the loader at https://<spitfire>/rum/spitfire-rum.js. Requests link to your backend with traceparent, and the result shows under APM → End users. Shared values: overview.
Version table
| Part | Package | Version |
|---|---|---|
Loader /rum/spitfire-rum.js |
@opentelemetry/sdk-trace, sdk-logs, core, resources |
3.0.0 |
@opentelemetry/exporter-trace-otlp-http, exporter-logs-otlp-http, instrumentation, instrumentation-fetch, instrumentation-xml-http-request |
0.300.0 | |
@opentelemetry/instrumentation-document-load |
0.69.0 | |
@opentelemetry/instrumentation-user-interaction |
0.68.0 | |
@opentelemetry/browser-instrumentation (Web Vitals, errors, navigation) |
0.9.0 | |
@opentelemetry/api |
1.10.0 | |
| Browser | ES2020 (Chrome 85, Firefox 79, Safari 14 and later) | – |
The loader is built from these packages along with Spitfire. The browser loads it from your Spitfire, not from a CDN, and it updates with Spitfire. Its version, in the browser console: SpitfireRUM.version. OTel marks browser instrumentation as experimental.
Verified: 2026-11-09. Source: OTel JS browser, npm @opentelemetry/browser-instrumentation.
What you need
- Spitfire address
https://<spitfire>; service name<service-name>, version<service-version>, environment<environment> - The site's address (here
https://<app-origin>) and the HTML file every page uses (here/srv/web/index.html) - Your API address, as a regular expression (here
^https://api\.example\.com/)
HTML
Create the key: Admin → Integrations → Add integration → Browser and app key, Allowed origins
https://<app-origin>; copysfrum_…(APM).Paste this into
<head>of/srv/web/index.html, before your other scripts (every page that should be measured needs it):
<!-- IS_OTEL_ENABLED=true: remove this tag to turn it off -->
<script src="https://<spitfire>/rum/spitfire-rum.js"
data-endpoint="https://<spitfire>/otlp"
data-key="sfrum_…"
data-service="<service-name>"
data-version="<service-version>"
data-env="<environment>"
data-sample="1"
data-propagate="^https://api\.example\.com/"></script>- If your site sends a
Content-Security-Policy, add your Spitfire toscript-srcandconnect-src:
Content-Security-Policy: script-src 'self' https://<spitfire>; connect-src 'self' https://<spitfire>- Publish the page and open it in a browser.
Settings
| Attribute | Meaning |
|---|---|
data-key |
The sfrum_… key (required) |
data-service |
The app's name in APM (required) |
data-endpoint |
OTLP address; default: the script's own address + /otlp |
data-version, data-env |
Version and environment |
data-sample |
Share of sessions sent, 0 to 1; default 1 |
data-propagate |
Regular expression of the API addresses that get traceparent (your own page's address always does) |
What it sends
- Page load: a
documentLoadspan and abrowser.page_timingevent with the step-by-step times from DNS to load, the resource count and the slowest resource. - In a single-page app, a
screen.viewspan for each route change. - fetch and XHR client spans (address without its query string); the ones matching
data-propagatecarrytraceparent. click/submitspans,exceptionevents with the stack.- LCP, INP, CLS, FCP, TTFB events; the element they were measured on comes in
browser.web_vital.targetas a CSS selector of at most 200 characters, never its text. - One
browser.long_tasksevent per page view (tasks of 50 ms or more).
Everything carries one session.id per tab. Browser, OS, device type and country are worked out on your Spitfire; the sender's address is not kept (What is kept).
Signed-in user (optional)
Nothing about the user is sent unless your code names them. To see sessions per user, call this after sign-in with your own user id (not an e-mail address):
<script>SpitfireRUM.setUser('<user-id>')</script>On sign-out: SpitfireRUM.setUser(null)
Your backend
- Let the backend's CORS allow the trace headers from
https://<app-origin>:
Access-Control-Allow-Headers: traceparent, tracestate, baggageVerify
- Spitfire serves the loader:
curl -s -o /dev/null -w '%{http_code}' https://<spitfire>/rum/spitfire-rum.js | grep -q '^200$' && echo OK- The browser may send:
curl -s -o /dev/null -w '%{http_code}' -X OPTIONS https://<spitfire>/otlp/v1/logs -H 'Origin: https://<app-origin>' -H 'Access-Control-Request-Method: POST' | grep -q '^204$' && echo OK- Spitfire takes the key:
curl -s -o /dev/null -w '%{http_code}' -X POST https://<spitfire>/otlp/v1/traces -H 'Origin: https://<app-origin>' -H 'Authorization: Bearer sfrum_…' -H 'Content-Type: application/json' -d '{}' | grep -q '^200$' && echo OK- Open the page, then APM → End users: the app
<service-name>shows a page load within a minute.
Turning off and removing
- Turn off for a while: write
data-sample="0". - Remove: delete the
<script … spitfire-rum.js>tag and the CSP lines you added.
Common problems
| Symptom | Fix |
|---|---|
Console: spitfire-rum: data-key must be … |
data-key is the sfrum_… key |
| Console: CSP refused the script or the connection | HTML step 3 |
| Verify step 2 prints nothing | Add https://<app-origin> to the key's Allowed origins; wait 30 s |
401 |
The key is sfrum_… and enabled |
429 |
Raise the key's Exports per minute or lower data-sample |
| Your API calls fail with CORS | Your backend step 1 |
| Requests are not linked to a backend trace | data-propagate must match your API address |
| No Web Vitals | LCP and INP are reported when the page is hidden or left; switch tabs once |