Skip to main content
Odigos can instrument front-end web applications with the OpenTelemetry Web SDK, capturing browser-side telemetry such as page loads, fetch/XHR requests, and user interactions.
Browser instrumentation is fundamentally different from Odigos’ server-side language agents. The telemetry SDK runs in the end user’s browser, not in a process inside the pod, so it cannot be auto-detected from /proc and must be enabled explicitly (see Enabling below).

​
How it works

Because the OpenTelemetry Web SDK runs in the browser, Odigos does not mount agent files into the application container or set runtime environment variables. Instead it injects a hardened same-origin gateway sidecar, odigos-browser-proxy, in front of the web server container: The sidecar:
  1. Injects CSP-safe external <script src="/__odigos/config.js"> and <script src="/__odigos/agent.js"> tags into text/html responses (gzip-aware). No inline JavaScript is injected, so default script-src 'self' CSPs keep working. When the upstream response CSP includes a nonce, that nonce is copied onto the injected tags.
  2. Serves /__odigos/config.js (assigns window.__ODIGOS__, including a per-sidecar export token) and the SDK bundle at /__odigos/agent.js.
  3. Receives authenticated browser OTLP/HTTP at /__odigos/v1/* (Bearer token + rate limits + same-site Origin checks) and forwards it to the node-local Odigos collector. Because telemetry is sent same-origin, no public collector endpoint is required.
An init container installs an iptables rule (Istio-style) that transparently redirects the application’s inbound traffic to the sidecar, so the Kubernetes Service does not need to change. Design docs for the security model live in the agent repo: odigos-io/opentelemetry-browser/docs.

​
Enabling

Front-end workloads cannot be reliably auto-detected, so browser instrumentation is opt-in per container. Create (or edit) a Source for the workload and set a container override that selects the browser-community distribution on the serving container:
If your front-end is served by a process Odigos would otherwise auto-instrument as server-side code (for example a Node.js static-file server), the browser-community override takes precedence and the server-side agent is not applied to that container.
When the workload’s pods are (re)created, Odigos injects the odigos-browser-proxy sidecar and the traffic-redirect init container. Open the application in a browser and confirm that browser traces arrive at your configured destination.

​
Requirements & notes

  • The serving container must expose a TCP containerPort; the sidecar fronts that port.
  • The redirect init container requires the NET_ADMIN capability. Namespaces enforcing a restrictive Pod Security Standard may need an exception for the instrumented workload.
  • Only text/html responses are rewritten; all other responses (assets, APIs) pass through unchanged.
  • One distro per container: selecting browser-community replaces any server-side language agent on that container. To instrument both a Node.js API and browser HTML, split them into separate containers (or workloads) and override only the HTML-serving one.
  • Service meshes: browser instrumentation is not supported alongside sidecar meshes such as Istio or Linkerd. Both use iptables redirects; co-injecting them would collide. Odigos skips browser-proxy injection when an istio-proxy / linkerd-proxy container is already present.
  • CSP: prefer script-src 'self' (or allow /__odigos/*.js). Hash-only CSPs without 'self' need an explicit allow-list update. Nonce-based CSPs are honored automatically when present on the HTML response.
  • Security: OTLP paths reject unauthenticated requests and apply per-IP / per-token rate limits. The export token is a telemetry write credential embedded in config.js, not a user session secret.