SpitfireLoad Testing & APMWhat's new

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

  1. Create the key: Admin → Integrations → Add integration → Browser and app key, Allowed origins https://<app-origin>; copy sfrum_… (APM).

  2. Paste this into <head> of /srv/web/index.html, before your other scripts (every page that should be measured needs it):

html
<!-- 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>
  1. If your site sends a Content-Security-Policy, add your Spitfire to script-src and connect-src:
text
Content-Security-Policy: script-src 'self' https://<spitfire>; connect-src 'self' https://<spitfire>
  1. 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 documentLoad span and a browser.page_timing event with the step-by-step times from DNS to load, the resource count and the slowest resource.
  • In a single-page app, a screen.view span for each route change.
  • fetch and XHR client spans (address without its query string); the ones matching data-propagate carry traceparent.
  • click / submit spans, exception events with the stack.
  • LCP, INP, CLS, FCP, TTFB events; the element they were measured on comes in browser.web_vital.target as a CSS selector of at most 200 characters, never its text.
  • One browser.long_tasks event 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):

html
<script>SpitfireRUM.setUser('<user-id>')</script>

On sign-out: SpitfireRUM.setUser(null)

Your backend

  1. Let the backend's CORS allow the trace headers from https://<app-origin>:
text
Access-Control-Allow-Headers: traceparent, tracestate, baggage

Verify

  1. Spitfire serves the loader:
bash
curl -s -o /dev/null -w '%{http_code}' https://<spitfire>/rum/spitfire-rum.js | grep -q '^200$' && echo OK
  1. The browser may send:
bash
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
  1. Spitfire takes the key:
bash
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
  1. Open the page, then APM → End users: the app <service-name> shows a page load within a minute.

Turning off and removing

  1. Turn off for a while: write data-sample="0".
  2. 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