Browser (Web) Instrumentation

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:

apiVersion: odigos.io/v1alpha1
kind: Source
metadata:
  name: my-frontend-source
  namespace: my-namespace
spec:
  workload:
    name: my-frontend
    namespace: my-namespace
    kind: Deployment
  containerOverrides:
    - containerName: my-frontend          # the container serving the HTML
      otelDistroName: browser-community

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.