From 50d856fb57256f3f84af9ce6be4d0c7867218076 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Thu, 19 Feb 2026 18:53:49 +0100 Subject: [PATCH 1/6] Add EDOT Browser documentation --- docs/reference/edot-browser/configuration.md | 148 +++++++++++++++++ docs/reference/edot-browser/index.md | 136 ++++++++++++++++ docs/reference/edot-browser/setup.md | 127 +++++++++++++++ .../edot-browser/supported-technologies.md | 153 ++++++++++++++++++ docs/reference/edot-browser/toc.yml | 5 + docs/reference/toc.yml | 1 + 6 files changed, 570 insertions(+) create mode 100644 docs/reference/edot-browser/configuration.md create mode 100644 docs/reference/edot-browser/index.md create mode 100644 docs/reference/edot-browser/setup.md create mode 100644 docs/reference/edot-browser/supported-technologies.md create mode 100644 docs/reference/edot-browser/toc.yml diff --git a/docs/reference/edot-browser/configuration.md b/docs/reference/edot-browser/configuration.md new file mode 100644 index 00000000..aa219d0a --- /dev/null +++ b/docs/reference/edot-browser/configuration.md @@ -0,0 +1,148 @@ +--- +navigation_title: Configuration +description: Configure the Elastic Distribution of OpenTelemetry Browser (EDOT Browser). +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Configure EDOT Browser + +This page explains how configuration works in EDOT Browser, which settings are supported, and what’s required to start exporting browser telemetry. + +EDOT Browser follows OpenTelemetry configuration conventions where possible, while accounting for the constraints of running in a web browser. + +## Configuration model in the browser [configuration-model-in-the-browser] + +Unlike backend OpenTelemetry SDKs, EDOT Browser runs in your users’ browsers. This has important implications: + +- Environment variables are not available at runtime. +- You must provide configuration at build time (for example, using bundler-defined constants) or at runtime by passing options to an initialization function. +- Never embed secrets in browser configuration. + +Because environment variables aren’t available at runtime in the browser, EDOT Browser does not read `OTEL_*` variables directly. Instead, it accepts configuration values passed explicitly during initialization. + +### Common configuration patterns + +Typical configuration patterns include: + +- Injecting values during build (for example, `process.env.*` replaced by a bundler). +- Passing configuration from a server-rendered page. +- Loading configuration from a global object populated at runtime. + +The best approach depends on your application architecture and build tooling. + +## Supported configuration settings [supported-configuration-settings] + +EDOT Browser supports a subset of OpenTelemetry configuration options, plus Elastic-specific extensions. + +### OpenTelemetry configuration + +EDOT Browser supports a subset of OpenTelemetry SDK configuration options (often associated with `OTEL_*` environment variables in non-browser SDKs). + +:::{note} +Some OpenTelemetry options are not applicable in a browser context. Unsupported options are ignored. +::: + +Commonly used options include: + +| Setting | Description | +|---|---| +| `service.name` | Logical name of the frontend service. Required. | +| `service.version` | Version of the application (optional). | +| `deployment.environment.name` | Environment name (for example, `prod` or `staging`). | +| `OTEL_LOG_LEVEL` | Log level for OpenTelemetry components (`error`, `warn`, `info`, `debug`, `verbose`). | + + + +### Elastic-specific configuration + +EDOT Browser may expose Elastic-specific configuration options prefixed with `ELASTIC_OTEL_`. + +You can use these options to: + +- Apply Elastic-specific defaults. +- Enable compatibility with {{product.observability}}. +- Control optional enhancements. + +:::{note} +Elastic-specific configuration options are still evolving. Refer to the configuration reference for the current list of supported settings. +::: + + + +## Minimal required configuration [minimal-required-configuration] + +At a minimum, EDOT Browser requires: + +- A service name to identify the frontend application +- An export endpoint that points to a reverse proxy + +You can also set a log level, which is recommended during setup. + +```js +import { initEDOTBrowser } from '@elastic/opentelemetry-browser'; + +initEDOTBrowser({ + serviceName: 'my-web-app', + endpoint: 'https://telemetry.example.com', + logLevel: 'info', +}); +``` + +- `serviceName` identifies the browser application in {{product.observability}}. +- `endpoint` points to a reverse proxy, not directly to {{product.observability}}. +- `logLevel` controls diagnostic output in the browser console. + +## Export endpoint configuration [export-endpoint-configuration] + +Configure the export endpoint to point to a reverse proxy that forwards OTLP traffic to {{product.observability}}. Use the base URL of the proxy only: do not include signal paths such as `/v1/traces`, `/v1/metrics`, or `/v1/logs` in the endpoint. EDOT Browser adds these paths when exporting each signal. + +Do not configure EDOT Browser to send data directly to: + +- {{ecloud}} Managed OTLP endpoints +- An EDOT Collector that requires authentication + +In a browser, authentication headers and secrets must be injected by the reverse proxy. + +Use a service name that identifies your frontend application and does not contain special characters, so that data is correctly categorized in {{product.observability}}. + +For details on reverse proxy and auth, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). + +## Logging and diagnostics [logging-and-diagnostics] + +EDOT Browser uses the OpenTelemetry diagnostic logger. + +To troubleshoot setup issues, increase the log level during initialization: + +```js +initEDOTBrowser({ + serviceName: 'my-web-app', + endpoint: 'https://telemetry.example.com', + logLevel: 'debug', +}); +``` + +Diagnostic logs are written to the browser console. + +## Configuration reference [configuration-reference] + +The following sections will be expanded as EDOT Browser matures: + +- Full list of supported OpenTelemetry options +- Elastic-specific `ELASTIC_OTEL_*` options +- Default values and behavior +- Configuration precedence rules + + + +## Next steps [next-steps] + +- Refer to [Set up EDOT Browser](setup.md) for installation and initialization. +- Review [Supported technologies](supported-technologies.md) for browser and instrumentation support. +- Refer to [Troubleshooting](supported-technologies.md#troubleshooting) on the Supported technologies page for EDOT Browser–specific issues, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/index.md b/docs/reference/edot-browser/index.md new file mode 100644 index 00000000..b8e47849 --- /dev/null +++ b/docs/reference/edot-browser/index.md @@ -0,0 +1,136 @@ +--- +navigation_title: EDOT Browser +description: Overview of the Elastic Distribution of OpenTelemetry Browser (EDOT Browser). +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# {{edot}} Browser + +EDOT Browser is Elastic’s distribution of the OpenTelemetry Browser SDK. It provides a bundled, opinionated setup for collecting traces, metrics, and logs from real user interactions in web applications and exporting that data to {{product.observability}} using the OpenTelemetry Protocol (OTLP). + +EDOT Browser is intended for Real User Monitoring (RUM) use cases, where telemetry is collected directly from users’ browsers to understand frontend performance, user interactions, and end-to-end request flows between frontend and backend services. + +## What EDOT Browser provides [what-edot-browser-provides] + +EDOT Browser is a wrapper around the contrib OpenTelemetry Browser SDK with Elastic-specific packaging and defaults. Its goals are to: + +- Provide a single bundle that includes commonly used OpenTelemetry browser components and instrumentations. +- Offer opinionated defaults for collecting browser telemetry, optimized for use with {{product.observability}}. +- Ensure compatibility with Elastic ingest pipelines and data models when exporting OpenTelemetry data. +- Minimize Elastic-specific concepts and contribute improvements to the upstream OpenTelemetry project where possible. + +EDOT Browser collects the following signals: + +- **Traces**: For distributed tracing and frontend-to-backend correlation +- **Metrics**: Browser-side performance and runtime metrics +- **Logs**: Using the OpenTelemetry Logs API + +## How it works [how-it-works] + +EDOT Browser runs in the user's browser as part of your web application. When initialized, it instruments the page and captures telemetry (traces, metrics, logs) from document load, user interactions, and network requests. Data is exported using the OpenTelemetry Protocol (OTLP) over HTTP to an endpoint you configure, typically a reverse proxy that injects authentication and forwards the data to {{product.observability}} or an OpenTelemetry Collector. Because the SDK runs in the browser, it cannot hold credentials; the reverse proxy is responsible for adding API keys or other auth before sending data to {{product.observability}}. + +## Limitations [limitations] + +EDOT Browser is currently under active development. While the long-term goal is to provide feature parity with classic Elastic {{product.apm}} browser agents, that parity doesn't yet exist. + +In particular: + +- EDOT Browser is not a drop-in replacement for classic Elastic {{product.apm}} RUM agents. +- There is no supported migration path from classic agents at this time. +- Some features available in classic agents are not yet implemented. +- The exact set of provided instrumentations and defaults might change as development continues. + +The following capabilities are not currently available in EDOT Browser: + +- Web Vitals instrumentation +- Full feature parity with classic Elastic {{product.apm}} browser agents +- Migration tooling from classic agents + +Some of these features might be introduced in the future, potentially through contrib OpenTelemetry contributions. + +## EDOT Browser versus classic Elastic {{product.apm}} agents [edot-browser-versus-classic-agents] + +Classic Elastic {{product.apm}} browser agents and EDOT Browser serve similar use cases but are built on different architectures. + +Classic agents: + +- Are Elastic-specific +- Provide mature RUM features out of the box +- Support features not yet available in EDOT Browser + +EDOT Browser: + +- Is based on OpenTelemetry standards +- Aims to align with contrib OpenTelemetry behavior +- Is still evolving toward feature parity + +If you require full feature parity with classic Elastic {{product.apm}} RUM agents today, continue using the classic agents. + +## Browser telemetry and authentication [browser-telemetry-and-authentication] + +Because EDOT Browser runs in the user’s browser, it cannot safely embed authentication credentials such as API keys. Telemetry must be exported through a reverse proxy that sits between the browser and your OTLP endpoint ({{ecloud}} Managed OTLP or an EDOT Collector). The reverse proxy is required for three reasons: + +- **Authentication**: The EDOT Collector or Managed OTLP endpoint expects an `Authorization` header with an API key. Putting that key in browser code would expose it to end users. The reverse proxy injects the header so the key stays on the server. +- **Cross-origin requests**: Your web application and the OTLP endpoint often have different origins. Browsers enforce Cross-Origin Resource Sharing (CORS); without the right headers, export requests are blocked. A reverse proxy on the same origin as your app (or configured to allow it) can add the required CORS headers and handle preflight `OPTIONS` requests. +- **Traffic control**: You can apply rate limiting or other controls at the proxy before traffic reaches the Collector or {{product.observability}}. + +:::{warning} +Avoid using EDOT Browser alongside any other {{product.apm}} or RUM agent (including classic Elastic {{product.apm}} browser agents). Running multiple agents can cause conflicting instrumentation, duplicate telemetry, or unexpected behavior. +::: + +### Example [example-reverse-proxy] + +Example NGINX reverse proxy configuration that forwards telemetry from `webapp.example.com` to an EDOT Collector at `collector.example.com`, injects the required `Authorization` header, and handles CORS preflight: + +```nginx +server { + # Configuration for HTTP/HTTPS goes here + location / { + # Take care of preflight requests + if ($request_method = 'OPTIONS') { + add_header 'Access-Control-Max-Age' 1728000; + add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; + add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; + add_header 'Access-Control-Allow-Credentials' 'true' always; + add_header 'Content-Type' 'text/plain charset=UTF-8'; + add_header 'Content-Length' 0; + return 204; + } + + add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; + add_header 'Access-Control-Allow-Credentials' 'true' always; + add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + # Set the auth header for the Collector here. Follow security best practices + # for adding secrets (for example Docker secrets, Kubernetes Secrets). + proxy_set_header Authorization 'ApiKey ...your Elastic API key...'; + proxy_pass https://collector.example.com:4318; + } +} +``` + +### Browser constraints [browser-constraints] + +If your site uses a Content Security Policy (CSP), add the domain of your OTLP endpoint (or reverse proxy) to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. + +If your app and the export endpoint have different origins, the browser may block requests unless CORS is correctly configured. The reverse proxy must send `Access-Control-Allow-Origin` matching your application origin, handle `OPTIONS` preflight requests with a 204 response, and include `Authorization` in `Access-Control-Allow-Headers` when using API key authentication. The NGINX example above shows one way to do this. + +For more details on reverse proxy setup, CORS, and CSP, see [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). + +## Next steps [next-steps] + +To get started with EDOT Browser: + +- Follow the setup instructions in [Set up EDOT Browser](setup.md) +- Review configuration options in [Configure EDOT Browser](configuration.md) +- Refer to [Supported technologies](supported-technologies.md) for details on browsers and instrumentations \ No newline at end of file diff --git a/docs/reference/edot-browser/setup.md b/docs/reference/edot-browser/setup.md new file mode 100644 index 00000000..64326ea2 --- /dev/null +++ b/docs/reference/edot-browser/setup.md @@ -0,0 +1,127 @@ +--- +navigation_title: Set up +description: Set up the Elastic Distribution of OpenTelemetry Browser (EDOT Browser). +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Set up EDOT Browser + +This guide shows you how to set up the {{edot}} Browser (EDOT Browser) in a web application and export browser telemetry to {{product.observability}}. + +EDOT Browser runs directly in users’ browsers. Because of browser security constraints, setup differs from backend OpenTelemetry SDKs, especially for authentication and data export. Review the reverse proxy requirements before you begin. + +:::{warning} +Do not run EDOT Browser alongside another {{product.apm}} or RUM agent (including classic Elastic {{product.apm}} browser agents). Multiple agents can cause conflicting instrumentation, duplicate telemetry, or unexpected behavior. +::: + +## Prerequisites [prerequisites] + +Before you set up EDOT Browser, you need: + +- An {{product.observability}} deployment ({{ecloud}} or self-managed) +- An OTLP ingest endpoint ({{ecloud}} Managed OTLP or an EDOT Collector) +- A reverse proxy that accepts telemetry from the browser, injects authentication headers, and forwards data to your OTLP endpoint. You need a reverse proxy because: + - API keys cannot be stored in browser code. + - The browser and endpoint often have different origins, so CORS must be handled. + - You can apply rate limiting or other controls at the proxy. + +For more on OTLP endpoints, reverse proxy configuration, authentication, CORS, and CSP, see [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). + +## Install EDOT Browser [install-edot-browser] + +EDOT Browser is distributed as a single bundle that packages the OpenTelemetry Browser SDK with Elastic-specific defaults. + +Install EDOT Browser using your package manager: + +```bash +# example +npm install @elastic/opentelemetry-browser +``` + + + +## Initialize EDOT Browser [initialize-edot-browser] + +Initialize EDOT Browser as early as possible in your application lifecycle so it can capture initial page loads, user interactions, and network requests. + +Initialize it: + +- At the top of your application entry point +- In a framework-specific bootstrap location (for example, a React root component, Angular `main.ts`, or a Vue plugin) + +A minimal example: + +```js +// example +import { initEDOTBrowser } from '@elastic/opentelemetry-browser'; + +initEDOTBrowser({ + serviceName: 'my-web-app', + endpoint: 'https://telemetry.example.com', // reverse proxy URL; do not include /v1/traces or other signal paths +}); +``` + + + +At a minimum, configure: + +- The service name used to identify your frontend application +- The export endpoint, which must point to your reverse proxy (not directly to {{product.observability}}) + +For additional configuration options, refer to [Configure EDOT Browser](configuration.md). + +You have successfully initialized EDOT Browser when the SDK loads without errors in the browser console and telemetry begins flowing to your reverse proxy. To confirm data in {{product.observability}}, open the Observability app and check for your service and traces. + +## How browser telemetry is exported [how-browser-telemetry-is-exported] + +EDOT Browser exports telemetry using the OpenTelemetry Protocol (OTLP) over HTTP. + +Data flows as follows: + +```text +Browser (EDOT Browser) + → Reverse proxy + → {{ecloud}} Managed OTLP endpoint + or EDOT Collector + → {{product.observability}} +``` + +The browser sends OTLP data to the reverse proxy endpoint that you configure. The reverse proxy: + +- Injects authentication headers (for example, Elastic API keys) +- Handles CORS preflight requests +- Optionally applies rate limiting or traffic controls + +## Reverse proxy requirement [reverse-proxy-requirement] + +Do not send telemetry directly from the browser to {{product.observability}} using an API key. + +Any credentials included in browser code are visible to end users and can be misused. EDOT Browser requires a reverse proxy in front of the OTLP endpoint. + +This pattern applies to: + +- {{ecloud}} Managed OTLP endpoints +- An EDOT Collector running in gateway mode + +### Browser constraints: CSP and CORS [browser-constraints] + +If your site uses a Content Security Policy (CSP), add the domain of your reverse proxy or OTLP endpoint to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. + +If your web application and the export endpoint have different origins, the browser may block requests unless CORS is configured. Your reverse proxy must return `Access-Control-Allow-Origin` matching your application origin, respond to `OPTIONS` preflight requests with 204, and include `Authorization` in `Access-Control-Allow-Headers` when using API key auth. The [overview page](index.md#example-reverse-proxy) includes an NGINX example. + +For complete examples and security considerations, see [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). + +## Next steps [next-steps] + +After completing setup: + +- Refer to [Configure EDOT Browser](configuration.md) to customize behavior and defaults. +- Review [Supported technologies](supported-technologies.md) for information about browsers and instrumentations. +- Read [User experience (RUM)](docs-content://solutions/observability/user-experience/index.md) to understand how browser traces appear in Discover and Service Maps. \ No newline at end of file diff --git a/docs/reference/edot-browser/supported-technologies.md b/docs/reference/edot-browser/supported-technologies.md new file mode 100644 index 00000000..8cae0e2f --- /dev/null +++ b/docs/reference/edot-browser/supported-technologies.md @@ -0,0 +1,153 @@ +--- +navigation_title: Supported technologies +description: Supported browsers, instrumentations, and known differences in EDOT Browser. +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Supported technologies + +This page lists: + +- Supported browser versions +- Included instrumentations and their default behavior +- Differences between EDOT Browser and contrib OpenTelemetry JS + +## Supported browsers [supported-browsers] + +EDOT Browser is designed to run in modern evergreen browsers. + +| Browser | Supported versions | +|----------|--------------------| +| Chrome | TODO | +| Edge | TODO | +| Firefox | TODO | +| Safari | TODO | + +:::{note} +Internet Explorer is not supported. +::: + +### Browser requirements + +At a minimum, the runtime environment must support: + +- ES2018 (or later) language features +- `fetch` API +- `Promise` +- `Performance` and `PerformanceObserver` APIs + + + +If your application targets older browsers, you may need to provide polyfills. EDOT Browser does not ship with built-in polyfills. + +## Included instrumentations [included-instrumentations] + +EDOT Browser bundles a curated set of OpenTelemetry JS instrumentations suitable for browser environments. + +The following table lists instrumentations that are currently included: + +| Instrumentation | Included | Enabled by default | Notes | +|-----------------|----------|-------------------|-------| +| Document load | TODO | TODO | TODO | +| Fetch | TODO | TODO | TODO | +| XMLHttpRequest | TODO | TODO | TODO | +| User interaction| TODO | TODO | TODO | +| Long tasks | TODO | TODO | TODO | + + + +### Default behavior + +By default, EDOT Browser: + +- Initializes tracing +- Registers included instrumentations +- Configures an OTLP exporter +- Applies Elastic-specific defaults (for example, resource detection or attribute normalization) + + + +You can disable or override instrumentations during initialization if needed. + + + +## Differences from contrib OpenTelemetry JS [differences-from-upstream] + +EDOT Browser builds on top of contrib OpenTelemetry JS, but introduces several differences to simplify setup and align with {{product.observability}}. + +### Configuration model + +- EDOT Browser doesn't read environment variables at runtime. +- Configuration must be passed explicitly during initialization. +- Elastic-specific configuration options may be available. + +### Export behavior + +- EDOT Browser expects telemetry to be sent to a reverse proxy. +- Direct export to authenticated OTLP endpoints is not supported in the browser. +- Authentication headers must be injected by infrastructure outside the browser. + +### Defaults and opinionated setup + +Compared to contrib OpenTelemetry JS: + +- EDOT Browser provides a simplified initialization API. +- A curated set of instrumentations is preconfigured. +- Sensible defaults are applied for Elastic ingestion. + + + +### Scope limitations + +Some contrib OpenTelemetry JS features are not available or are intentionally unsupported in EDOT Browser due to browser constraints. + +These may include: + +- Environment-based configuration +- Certain resource detectors +- Node.js-specific instrumentation + + + +## Version compatibility [version-compatibility] + +| Component | Version | +|----------|---------| +| OpenTelemetry JS API | TODO | +| OpenTelemetry JS SDK | TODO | + + + +## Known limitations [known-limitations] + +When using EDOT Browser with {{product.observability}}, be aware of the following: + +- API key authentication requires a reverse proxy; credentials cannot be stored in the browser. +- Metrics from browser-based RUM may have more limited utility than backend metrics, depending on your use case. +- Some OpenTelemetry browser instrumentations are still experimental. Behavior may change. +- Monitor the performance impact on the browser when using multiple instrumentations, especially on lower-end devices. + +## Troubleshooting [troubleshooting] + +If telemetry does not appear in {{product.observability}}: + +- Confirm the export endpoint points to your reverse proxy (not directly to {{product.observability}}) and doesn't include signal paths like `/v1/traces`. +- Check the browser console for network errors or OpenTelemetry-related messages. Cross-Origin Resource Sharing (CORS) errors often mean the reverse proxy is not sending the right `Access-Control-Allow-Origin` or preflight response. +- Ensure the reverse proxy can reach your EDOT Collector or {{ecloud}} Managed OTLP endpoint; check proxy logs for connection or auth failures. +- Ensure service name is set and doesn't contain special characters. +- Set the log level to `debug` or `verbose` during initialization to check the detailed export and instrumentation output in the console. + +If you use a Content Security Policy, ensure the proxy or OTLP endpoint domain is in the `connect-src` directive. For bundler or module resolution errors, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md) and the general [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) docs. + +## Next steps [next-steps] + +- Refer to [Set up EDOT Browser](setup.md) to get started. +- Review [Configuration](configuration.md) to customize behavior. +- Refer to [Known limitations](#known-limitations) and [Troubleshooting](#troubleshooting) above for EDOT Browser–specific guidance, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/toc.yml b/docs/reference/edot-browser/toc.yml new file mode 100644 index 00000000..6687406e --- /dev/null +++ b/docs/reference/edot-browser/toc.yml @@ -0,0 +1,5 @@ +toc: + - file: index.md + - file: setup.md + - file: configuration.md + - file: supported-technologies.md \ No newline at end of file diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml index e87cad59..14dc2ffd 100644 --- a/docs/reference/toc.yml +++ b/docs/reference/toc.yml @@ -22,4 +22,5 @@ toc: - file: data-streams.md - file: central-configuration.md - file: edot-sdks/index.md + - toc: edot-browser - toc: edot-cloud-forwarder \ No newline at end of file From 1e63b430fa6ee36237393901d33d3e0ef3fa7386 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Thu, 19 Feb 2026 18:57:38 +0100 Subject: [PATCH 2/6] Fix link --- docs/reference/edot-browser/setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/edot-browser/setup.md b/docs/reference/edot-browser/setup.md index 64326ea2..f1906f1c 100644 --- a/docs/reference/edot-browser/setup.md +++ b/docs/reference/edot-browser/setup.md @@ -124,4 +124,4 @@ After completing setup: - Refer to [Configure EDOT Browser](configuration.md) to customize behavior and defaults. - Review [Supported technologies](supported-technologies.md) for information about browsers and instrumentations. -- Read [User experience (RUM)](docs-content://solutions/observability/user-experience/index.md) to understand how browser traces appear in Discover and Service Maps. \ No newline at end of file +- Read [User experience (RUM)](docs-content://solutions/observability/applications/user-experience.md) to understand how browser traces appear in Discover and Service Maps. \ No newline at end of file From 0a9c89ae13dc6e7a471519f31cba1c8456a03b3b Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Fri, 20 Feb 2026 15:07:34 +0100 Subject: [PATCH 3/6] Added a new section on telemetry, detailing metrics, traces, and logs emitted by EDOT Browser, including known limitations --- docs/reference/edot-browser/configuration.md | 7 +- docs/reference/edot-browser/index.md | 8 +- docs/reference/edot-browser/setup.md | 31 ++++++- .../edot-browser/supported-technologies.md | 15 ++-- docs/reference/edot-browser/telemetry.md | 88 +++++++++++++++++++ docs/reference/edot-browser/toc.yml | 1 + 6 files changed, 134 insertions(+), 16 deletions(-) create mode 100644 docs/reference/edot-browser/telemetry.md diff --git a/docs/reference/edot-browser/configuration.md b/docs/reference/edot-browser/configuration.md index aa219d0a..98d8a25c 100644 --- a/docs/reference/edot-browser/configuration.md +++ b/docs/reference/edot-browser/configuration.md @@ -62,12 +62,12 @@ Commonly used options include: ### Elastic-specific configuration -EDOT Browser may expose Elastic-specific configuration options prefixed with `ELASTIC_OTEL_`. +EDOT Browser might expose Elastic-specific configuration options prefixed with `ELASTIC_OTEL_`. You can use these options to: - Apply Elastic-specific defaults. -- Enable compatibility with {{product.observability}}. +- Ensure compatibility with {{product.observability}}. - Control optional enhancements. :::{note} @@ -132,7 +132,7 @@ Diagnostic logs are written to the browser console. ## Configuration reference [configuration-reference] -The following sections will be expanded as EDOT Browser matures: +The following sections expand as EDOT Browser matures: - Full list of supported OpenTelemetry options - Elastic-specific `ELASTIC_OTEL_*` options @@ -144,5 +144,6 @@ The following sections will be expanded as EDOT Browser matures: ## Next steps [next-steps] - Refer to [Set up EDOT Browser](setup.md) for installation and initialization. +- Refer to [Metrics, traces, and logs](telemetry.md) for what each signal emits and limitations. - Review [Supported technologies](supported-technologies.md) for browser and instrumentation support. - Refer to [Troubleshooting](supported-technologies.md#troubleshooting) on the Supported technologies page for EDOT Browser–specific issues, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/index.md b/docs/reference/edot-browser/index.md index b8e47849..5db1f26f 100644 --- a/docs/reference/edot-browser/index.md +++ b/docs/reference/edot-browser/index.md @@ -32,10 +32,14 @@ EDOT Browser collects the following signals: - **Metrics**: Browser-side performance and runtime metrics - **Logs**: Using the OpenTelemetry Logs API +For what each signal includes, known limitations, and what is not yet supported (such as Web Vitals), refer to [Metrics, traces, and logs](telemetry.md). + ## How it works [how-it-works] EDOT Browser runs in the user's browser as part of your web application. When initialized, it instruments the page and captures telemetry (traces, metrics, logs) from document load, user interactions, and network requests. Data is exported using the OpenTelemetry Protocol (OTLP) over HTTP to an endpoint you configure, typically a reverse proxy that injects authentication and forwards the data to {{product.observability}} or an OpenTelemetry Collector. Because the SDK runs in the browser, it cannot hold credentials; the reverse proxy is responsible for adding API keys or other auth before sending data to {{product.observability}}. +In {{product.observability}}, you see **`external.http`** spans for browser fetch and XHR requests, **user interaction** spans (for example, click, submit) that group related frontend and backend activity, and end-to-end traces from the browser to your backend in Discover and Service Maps. For details, refer to [What to expect in Kibana](setup.md#what-to-expect-in-kibana) in the setup guide. + ## Limitations [limitations] EDOT Browser is currently under active development. While the long-term goal is to provide feature parity with classic Elastic {{product.apm}} browser agents, that parity doesn't yet exist. @@ -123,9 +127,9 @@ server { If your site uses a Content Security Policy (CSP), add the domain of your OTLP endpoint (or reverse proxy) to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. -If your app and the export endpoint have different origins, the browser may block requests unless CORS is correctly configured. The reverse proxy must send `Access-Control-Allow-Origin` matching your application origin, handle `OPTIONS` preflight requests with a 204 response, and include `Authorization` in `Access-Control-Allow-Headers` when using API key authentication. The NGINX example above shows one way to do this. +If your app and the export endpoint have different origins, the browser might block requests unless CORS is correctly configured. The reverse proxy must send `Access-Control-Allow-Origin` matching your application origin, handle `OPTIONS` preflight requests with a 204 response, and include `Authorization` in `Access-Control-Allow-Headers` when using API key authentication. The NGINX example above shows one way to do this. -For more details on reverse proxy setup, CORS, and CSP, see [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). +For more details on reverse proxy setup, CORS, and CSP, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). ## Next steps [next-steps] diff --git a/docs/reference/edot-browser/setup.md b/docs/reference/edot-browser/setup.md index f1906f1c..2ed42758 100644 --- a/docs/reference/edot-browser/setup.md +++ b/docs/reference/edot-browser/setup.md @@ -32,7 +32,7 @@ Before you set up EDOT Browser, you need: - The browser and endpoint often have different origins, so CORS must be handled. - You can apply rate limiting or other controls at the proxy. -For more on OTLP endpoints, reverse proxy configuration, authentication, CORS, and CSP, see [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). +For more on OTLP endpoints, reverse proxy configuration, authentication, CORS, and CSP, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). ## Install EDOT Browser [install-edot-browser] @@ -79,6 +79,27 @@ For additional configuration options, refer to [Configure EDOT Browser](configur You have successfully initialized EDOT Browser when the SDK loads without errors in the browser console and telemetry begins flowing to your reverse proxy. To confirm data in {{product.observability}}, open the Observability app and check for your service and traces. +## What to expect in {{kib}} [what-to-expect-in-kibana] + +After EDOT Browser is sending telemetry to {{product.observability}}, you can inspect traces and spans in the Observability app. The following describes what you see and how to interpret it. + +### Spans from browser fetch and XHR [spans-from-fetch-xhr] + +Outgoing HTTP requests made with the browser `fetch` API or `XMLHttpRequest` are captured as **`external.http`** spans. Each request to your backend APIs or third-party domains appears as an `external.http` span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request (time in the browser) and, when your backend is instrumented with OpenTelemetry, link to the corresponding server-side trace using the trace context (trace ID and span ID) propagated in HTTP headers. In the trace view, you see the browser’s `external.http` span as part of the same trace as the backend service spans when propagation is correctly configured. + +### User interaction spans and grouping [user-interaction-spans] + +EDOT Browser creates user interaction spans for events such as "click" and "submit". These spans represent the user action that triggered subsequent work (for example, a button click that leads to a `fetch` call). In {{kib}}, user interaction spans are used to group related spans: the interaction span is the logical parent or anchor for the cascade of operations that follow (for example, `external.http` requests and any child spans). When you analyze a trace, look for the user interaction span (for example, `userinteraction` or similar) to understand which click or submit caused the associated network and backend activity. This grouping makes it easier to attribute frontend and backend work to specific user actions. + +### Frontend-to-backend traces in Discover and Service Maps [frontend-backend-in-discover-and-service-maps] + +Traces that start in the browser (from a user interaction) and continue to your backend appear as end-to-end traces in {{product.observability}}: + +- **Discover**: When you search or filter by your frontend service name or by trace ID, you see trace documents that include both browser-originated spans (for example, user interaction, `external.http`) and backend service spans, as long as trace context is propagated from the browser to the server. You can inspect the full path of a request from the user action through the frontend to backend services. +- **Service Maps**: Your frontend application appears as a service node. Connections from that node to backend services are derived from the same trace data: when a browser `external.http` span targets a backend that is also instrumented and reported to {{product.observability}}, a dependency link is shown between the frontend and that backend service. This gives you a map of how browser traffic flows to your backend services. + +For more on how RUM and distributed traces appear in the Observability app, refer to [User experience (RUM)](docs-content://solutions/observability/applications/user-experience.md). + ## How browser telemetry is exported [how-browser-telemetry-is-exported] EDOT Browser exports telemetry using the OpenTelemetry Protocol (OTLP) over HTTP. @@ -114,14 +135,16 @@ This pattern applies to: If your site uses a Content Security Policy (CSP), add the domain of your reverse proxy or OTLP endpoint to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. -If your web application and the export endpoint have different origins, the browser may block requests unless CORS is configured. Your reverse proxy must return `Access-Control-Allow-Origin` matching your application origin, respond to `OPTIONS` preflight requests with 204, and include `Authorization` in `Access-Control-Allow-Headers` when using API key auth. The [overview page](index.md#example-reverse-proxy) includes an NGINX example. +If your web application and the export endpoint have different origins, the browser might block requests unless CORS is configured. Your reverse proxy must return `Access-Control-Allow-Origin` matching your application origin, respond to `OPTIONS` preflight requests with 204, and include `Authorization` in `Access-Control-Allow-Headers` when using API key auth. The [overview page](index.md#example-reverse-proxy) includes an NGINX example. -For complete examples and security considerations, see [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). +For complete examples and security considerations, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). ## Next steps [next-steps] After completing setup: +- Refer to [What to expect in {{kib}}](#what-to-expect-in-kibana) above for the span types and views you see (for example, `external.http`, user interaction grouping, Discover and Service Maps). +- Refer to [Metrics, traces, and logs](telemetry.md) for what is emitted for each signal and known limitations. - Refer to [Configure EDOT Browser](configuration.md) to customize behavior and defaults. - Review [Supported technologies](supported-technologies.md) for information about browsers and instrumentations. -- Read [User experience (RUM)](docs-content://solutions/observability/applications/user-experience.md) to understand how browser traces appear in Discover and Service Maps. \ No newline at end of file +- Read [User experience (RUM)](docs-content://solutions/observability/applications/user-experience.md) for more on how browser traces appear in the Observability app. \ No newline at end of file diff --git a/docs/reference/edot-browser/supported-technologies.md b/docs/reference/edot-browser/supported-technologies.md index 8cae0e2f..95e0d5dd 100644 --- a/docs/reference/edot-browser/supported-technologies.md +++ b/docs/reference/edot-browser/supported-technologies.md @@ -45,7 +45,7 @@ At a minimum, the runtime environment must support: -If your application targets older browsers, you may need to provide polyfills. EDOT Browser does not ship with built-in polyfills. +If your application targets older browsers, you might need to provide polyfills. EDOT Browser does not ship with built-in polyfills. ## Included instrumentations [included-instrumentations] @@ -53,7 +53,7 @@ EDOT Browser bundles a curated set of OpenTelemetry JS instrumentations suitable The following table lists instrumentations that are currently included: -| Instrumentation | Included | Enabled by default | Notes | +| Instrumentation | Included | On by default | Notes | |-----------------|----------|-------------------|-------| | Document load | TODO | TODO | TODO | | Fetch | TODO | TODO | TODO | @@ -74,7 +74,7 @@ By default, EDOT Browser: -You can disable or override instrumentations during initialization if needed. +You can turn off or override instrumentations during initialization if needed. @@ -86,7 +86,7 @@ EDOT Browser builds on top of contrib OpenTelemetry JS, but introduces several d - EDOT Browser doesn't read environment variables at runtime. - Configuration must be passed explicitly during initialization. -- Elastic-specific configuration options may be available. +- Elastic-specific configuration options might be available. ### Export behavior @@ -108,7 +108,7 @@ Compared to contrib OpenTelemetry JS: Some contrib OpenTelemetry JS features are not available or are intentionally unsupported in EDOT Browser due to browser constraints. -These may include: +These might include: - Environment-based configuration - Certain resource detectors @@ -130,8 +130,8 @@ These may include: When using EDOT Browser with {{product.observability}}, be aware of the following: - API key authentication requires a reverse proxy; credentials cannot be stored in the browser. -- Metrics from browser-based RUM may have more limited utility than backend metrics, depending on your use case. -- Some OpenTelemetry browser instrumentations are still experimental. Behavior may change. +- Metrics from browser-based RUM might have more limited utility than backend metrics, depending on your use case. +- Some OpenTelemetry browser instrumentations are still experimental. Behavior might change. - Monitor the performance impact on the browser when using multiple instrumentations, especially on lower-end devices. ## Troubleshooting [troubleshooting] @@ -149,5 +149,6 @@ If you use a Content Security Policy, ensure the proxy or OTLP endpoint domain i ## Next steps [next-steps] - Refer to [Set up EDOT Browser](setup.md) to get started. +- Refer to [Metrics, traces, and logs](telemetry.md) for what is emitted per signal and what is not yet supported. - Review [Configuration](configuration.md) to customize behavior. - Refer to [Known limitations](#known-limitations) and [Troubleshooting](#troubleshooting) above for EDOT Browser–specific guidance, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/telemetry.md b/docs/reference/edot-browser/telemetry.md new file mode 100644 index 00000000..3ab491e8 --- /dev/null +++ b/docs/reference/edot-browser/telemetry.md @@ -0,0 +1,88 @@ +--- +navigation_title: Metrics, traces, and logs +description: What EDOT Browser emits for each telemetry signal and known limitations. +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Metrics, traces, and logs + +EDOT Browser can export all three OpenTelemetry signals—metrics, traces, and logs—to {{product.observability}} using OTLP. This page describes what is currently emitted for each signal, known limitations of browser-based telemetry, and what is not yet supported. + +## Metrics [metrics] + +### What EDOT Browser currently emits [metrics-what-is-emitted] + +EDOT Browser configures the OpenTelemetry MeterProvider and exports metrics over OTLP when metrics are turned on. The exact set of built-in metrics is still evolving. Metrics might be produced by: + +- **Long task instrumentation**: When long task instrumentation is included and turned on, it can report observations related to main-thread blocking (for example long tasks exceeding a threshold). The names and attributes of these metrics depend on the instrumentation implementation. +- **Custom metrics**: Your application can create meters and instruments (counters, histograms, and so on) using the OpenTelemetry Metrics API. EDOT Browser exports those metrics along with any SDK-provided ones. + +If you turn on metrics export, ensure your reverse proxy and OTLP endpoint accept the `/v1/metrics` path. + +### Known limitations of browser-side metrics [metrics-limitations] + +- Metrics are collected in the user’s browser and represent a single session or page. There is no server-side aggregation, each export batch reflects one client’s view. +- Browsers have limited resources. High-cardinality or high-frequency metrics can affect performance and export payload size. Use caution with unbounded attributes (for example user IDs, dynamic URLs) on metrics. +- Metrics are only sent when the SDK exports (for example on an interval or when the page is unloaded). Temporary or single-page sessions might produce few data points. +- Browser environments vary (device, network, extensions). Metric values might be noisier or less consistent than server-side metrics. + +:::{note} +Web Vitals (such as Largest Contentful Paint (LCP), First Input Delay (FID), Cumulative Layout Shift (CLS), and related metrics) are not supported in EDOT Browser. There is no built-in Web Vitals instrumentation. If you need Web Vitals or similar Core Web Vitals data, use classic Elastic {{product.apm}} browser agents or a dedicated Web Vitals library. +::: + +## Traces [traces] + +### What EDOT Browser currently emits [traces-what-is-emitted] + +EDOT Browser initializes tracing and registers instrumentations that produce spans: + +- Spans for the initial document load and related navigation timing, when the document load instrumentation is included and turned on. +- Each outgoing request using `fetch` or `XMLHttpRequest` is captured as an **`external.http`** span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request. +- Spans for user actions such as "click" and "submit". These interaction spans group the subsequent work (for example `external.http` requests) so you can attribute frontend and backend activity to a specific user action in {{product.observability}}. + +When your backend is instrumented with OpenTelemetry and trace context (trace ID, span ID) is propagated in HTTP headers, the browser’s `external.http` span and the backend spans appear in the same trace, giving you end-to-end visibility in Discover and Service Maps. Refer to [What to expect in Kibana](setup.md#what-to-expect-in-kibana) for how these traces appear in the Observability app. + +### Known limitations of browser-side traces [traces-limitations] + +- Frontend-to-backend trace continuity depends on your backend and HTTP client propagating the W3C Trace Context headers. If propagation is not configured, browser and backend spans appear as separate traces. +- Only requests that go through the instrumented `fetch` and `XMLHttpRequest` APIs are captured. Requests made by other mechanisms (for example some third-party scripts, WebSockets, or non-instrumented clients) do not produce spans unless you add custom instrumentation. +- Sampling is applied in the browser. High traffic can lead to large trace volume, so configure sampling or export options appropriately. +- Traces are tied to the page and session. Cross-tab or cross-origin flows might not form a single trace unless you implement custom context propagation. + +:::{note} +Full feature parity with classic Elastic {{product.apm}} RUM agents for tracing (for example, certain automatic instrumentations or span types) is not yet available. +::: + +## Logs [logs] + +### What EDOT Browser currently emits [logs-what-is-emitted] + +EDOT Browser supports the OpenTelemetry Logs API. When the LoggerProvider is configured and logs are exported using OTLP: + +- **Application logs**: Your application code can obtain a logger from the OpenTelemetry API and emit log records (severity, body, attributes). EDOT Browser exports these records to your configured endpoint on the `/v1/logs` path. +- **Resource and context**: Log records are associated with the same resource (for example service name) and can optionally be linked to the active trace context, so you can correlate logs with traces in {{product.observability}}. + +There is no requirement to use logs. If you do not create log records or do not configure log export, no log data is sent. + +### Known limitations of browser-side logs [logs-limitations] + +- Logs are buffered in the browser and sent on the export cycle. High log volume can increase memory use and export payload size, and might affect page performance. Prefer sampling or severity filtering for noisy logs. +- As with metrics, logs reflect a single client session. You do not get centralized log aggregation in the browser, that happens in {{product.observability}} after export. +- Logs that are not exported before the user navigates away or closes the tab might be lost unless the SDK supports a reliable flush (for example on `beforeunload`). Be aware that some log data might not reach the backend in edge cases. + +:::{note} +Automatic capture of `console` methods (for example `console.log`, `console.error`) is not provided by EDOT Browser. To send logs to {{product.observability}}, you must use the OpenTelemetry Logs API from your application code. Automatic console instrumentation might be considered in the future. +::: + +## Next steps [next-steps] + +- Refer to [Set up EDOT Browser](setup.md) for installation and export configuration. +- Refer to [What to expect in {{kib}}](setup.md#what-to-expect-in-kibana) for how traces appear in the Observability app. +- Refer to [Supported technologies](supported-technologies.md) for included instrumentations and [Configure EDOT Browser](configuration.md) for turning signals and instrumentations on or off. diff --git a/docs/reference/edot-browser/toc.yml b/docs/reference/edot-browser/toc.yml index 6687406e..e8772e04 100644 --- a/docs/reference/edot-browser/toc.yml +++ b/docs/reference/edot-browser/toc.yml @@ -2,4 +2,5 @@ toc: - file: index.md - file: setup.md - file: configuration.md + - file: telemetry.md - file: supported-technologies.md \ No newline at end of file From 2bfe4188c6c22c007a13cd331b00a96de5567822 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Tue, 3 Mar 2026 19:15:27 +0100 Subject: [PATCH 4/6] Enhance EDOT Browser documentation with detailed configuration and setup instructions, including reverse proxy requirements, initialization steps, and troubleshooting guidance. Update telemetry export details and clarify supported technologies. --- docs/reference/edot-browser/configuration.md | 100 ++++--------- docs/reference/edot-browser/index.md | 99 ++----------- docs/reference/edot-browser/setup.md | 133 ++++++++++-------- .../edot-browser/supported-technologies.md | 94 ++----------- docs/reference/edot-browser/telemetry.md | 12 +- docs/reference/edot-browser/toc.yml | 3 +- .../reference/edot-browser/troubleshooting.md | 30 ++++ 7 files changed, 166 insertions(+), 305 deletions(-) create mode 100644 docs/reference/edot-browser/troubleshooting.md diff --git a/docs/reference/edot-browser/configuration.md b/docs/reference/edot-browser/configuration.md index 98d8a25c..9f42e7c6 100644 --- a/docs/reference/edot-browser/configuration.md +++ b/docs/reference/edot-browser/configuration.md @@ -13,19 +13,18 @@ products: # Configure EDOT Browser -This page explains how configuration works in EDOT Browser, which settings are supported, and what’s required to start exporting browser telemetry. +This page explains how to configure EDOT Browser, which settings are supported, and what’s required to start exporting browser telemetry. -EDOT Browser follows OpenTelemetry configuration conventions where possible, while accounting for the constraints of running in a web browser. +EDOT Browser follows OpenTelemetry configuration conventions where possible. Like the upstream OpenTelemetry Browser SDK, it uses explicit configuration at initialization rather than environment variables, which are not available in the browser. ## Configuration model in the browser [configuration-model-in-the-browser] -Unlike backend OpenTelemetry SDKs, EDOT Browser runs in your users’ browsers. This has important implications: +EDOT Browser runs in your users’ browsers. This has important implications: -- Environment variables are not available at runtime. -- You must provide configuration at build time (for example, using bundler-defined constants) or at runtime by passing options to an initialization function. +- Environment variables exist at build time, when your app is bundled. For example, a bundler replaces `process.env.*` with values. However, the variables are not available at runtime, meaning when the app runs in the browser. You can provide configuration at build time (bundler-defined constants) or at runtime (options passed to the initialization function). - Never embed secrets in browser configuration. -Because environment variables aren’t available at runtime in the browser, EDOT Browser does not read `OTEL_*` variables directly. Instead, it accepts configuration values passed explicitly during initialization. +EDOT Browser does not read `OTEL_*` variables directly. Instead, it accepts configuration values passed explicitly during initialization. ### Common configuration patterns @@ -39,42 +38,19 @@ The best approach depends on your application architecture and build tooling. ## Supported configuration settings [supported-configuration-settings] -EDOT Browser supports a subset of OpenTelemetry configuration options, plus Elastic-specific extensions. +Configuration is passed as an object to `startBrowserSdk`. The following options are supported: -### OpenTelemetry configuration - -EDOT Browser supports a subset of OpenTelemetry SDK configuration options (often associated with `OTEL_*` environment variables in non-browser SDKs). - -:::{note} -Some OpenTelemetry options are not applicable in a browser context. Unsupported options are ignored. -::: - -Commonly used options include: - -| Setting | Description | +| Option | Description | |---|---| -| `service.name` | Logical name of the frontend service. Required. | -| `service.version` | Version of the application (optional). | -| `deployment.environment.name` | Environment name (for example, `prod` or `staging`). | -| `OTEL_LOG_LEVEL` | Log level for OpenTelemetry components (`error`, `warn`, `info`, `debug`, `verbose`). | - - - -### Elastic-specific configuration - -EDOT Browser might expose Elastic-specific configuration options prefixed with `ELASTIC_OTEL_`. - -You can use these options to: - -- Apply Elastic-specific defaults. -- Ensure compatibility with {{product.observability}}. -- Control optional enhancements. - -:::{note} -Elastic-specific configuration options are still evolving. Refer to the configuration reference for the current list of supported settings. -::: - - +| `serviceName` | Logical name of the frontend service. Defaults to `unknown_service:web` if not set. | +| `serviceVersion` | Version of the application. Optional. | +| `logLevel` | Diagnostic log level (`error`, `warn`, `info`, `debug`, `verbose`). Defaults to `info`. | +| `otlpEndpoint` | Base URL of the OTLP export endpoint (reverse proxy). Do not include signal paths such as `/v1/traces`. Defaults to `http://localhost:4318`. | +| `sampleRate` | Trace sampling ratio (0–1). Defaults to `1` (100%). | +| `resourceAttributes` | Optional resource attributes to attach to telemetry. | +| `exportHeaders` | Headers to send with export requests. Defaults to `{}`. The reverse proxy typically injects `Authorization`; do not put API keys here in browser code. | +| `disabled` | If `true`, the SDK does not start. | +| `configInstrumentations` | Per-instrumentation config. Set `enabled: false` for a key to turn off that instrumentation. | ## Minimal required configuration [minimal-required-configuration] @@ -86,64 +62,48 @@ At a minimum, EDOT Browser requires: You can also set a log level, which is recommended during setup. ```js -import { initEDOTBrowser } from '@elastic/opentelemetry-browser'; +import { startBrowserSdk } from '@elastic/opentelemetry-browser'; -initEDOTBrowser({ +startBrowserSdk({ serviceName: 'my-web-app', - endpoint: 'https://telemetry.example.com', + otlpEndpoint: 'https://telemetry.example.com', logLevel: 'info', }); ``` - `serviceName` identifies the browser application in {{product.observability}}. -- `endpoint` points to a reverse proxy, not directly to {{product.observability}}. +- `otlpEndpoint` points to a reverse proxy, not directly to {{product.observability}}. - `logLevel` controls diagnostic output in the browser console. ## Export endpoint configuration [export-endpoint-configuration] -Configure the export endpoint to point to a reverse proxy that forwards OTLP traffic to {{product.observability}}. Use the base URL of the proxy only: do not include signal paths such as `/v1/traces`, `/v1/metrics`, or `/v1/logs` in the endpoint. EDOT Browser adds these paths when exporting each signal. - -Do not configure EDOT Browser to send data directly to: - -- {{ecloud}} Managed OTLP endpoints -- An EDOT Collector that requires authentication +Configure `otlpEndpoint` to point to a reverse proxy that forwards OTLP traffic to {{product.observability}}. Use the base URL of the proxy only: do not include signal paths such as `/v1/traces`, `/v1/metrics`, or `/v1/logs`. The SDK appends these paths when exporting each signal. -In a browser, authentication headers and secrets must be injected by the reverse proxy. +Use a service name that identifies your frontend application and doesn't contain special characters, so that data is correctly categorized in {{product.observability}}. -Use a service name that identifies your frontend application and does not contain special characters, so that data is correctly categorized in {{product.observability}}. - -For details on reverse proxy and auth, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). +For details on reverse proxy and authorization, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). ## Logging and diagnostics [logging-and-diagnostics] EDOT Browser uses the OpenTelemetry diagnostic logger. -To troubleshoot setup issues, increase the log level during initialization: +To troubleshoot setup issues, increase the log level when calling `startBrowserSdk`: ```js -initEDOTBrowser({ +import { startBrowserSdk } from '@elastic/opentelemetry-browser'; + +startBrowserSdk({ serviceName: 'my-web-app', - endpoint: 'https://telemetry.example.com', + otlpEndpoint: 'https://telemetry.example.com', logLevel: 'debug', }); ``` -Diagnostic logs are written to the browser console. - -## Configuration reference [configuration-reference] - -The following sections expand as EDOT Browser matures: - -- Full list of supported OpenTelemetry options -- Elastic-specific `ELASTIC_OTEL_*` options -- Default values and behavior -- Configuration precedence rules - - +Diagnostic logs are written to the browser console. For more information on using debug logging to troubleshoot issues, refer to [Enable debug logging for EDOT SDKs](docs-content://troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md) and [Enable debug logging](docs-content://troubleshoot/ingest/opentelemetry/edot-collector/enable-debug-logging.md) (Collector). ## Next steps [next-steps] - Refer to [Set up EDOT Browser](setup.md) for installation and initialization. - Refer to [Metrics, traces, and logs](telemetry.md) for what each signal emits and limitations. - Review [Supported technologies](supported-technologies.md) for browser and instrumentation support. -- Refer to [Troubleshooting](supported-technologies.md#troubleshooting) on the Supported technologies page for EDOT Browser–specific issues, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file +- Refer to [Troubleshooting](troubleshooting.md) for EDOT Browser–specific issues, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/index.md b/docs/reference/edot-browser/index.md index 5db1f26f..3ee49545 100644 --- a/docs/reference/edot-browser/index.md +++ b/docs/reference/edot-browser/index.md @@ -15,16 +15,7 @@ products: EDOT Browser is Elastic’s distribution of the OpenTelemetry Browser SDK. It provides a bundled, opinionated setup for collecting traces, metrics, and logs from real user interactions in web applications and exporting that data to {{product.observability}} using the OpenTelemetry Protocol (OTLP). -EDOT Browser is intended for Real User Monitoring (RUM) use cases, where telemetry is collected directly from users’ browsers to understand frontend performance, user interactions, and end-to-end request flows between frontend and backend services. - -## What EDOT Browser provides [what-edot-browser-provides] - -EDOT Browser is a wrapper around the contrib OpenTelemetry Browser SDK with Elastic-specific packaging and defaults. Its goals are to: - -- Provide a single bundle that includes commonly used OpenTelemetry browser components and instrumentations. -- Offer opinionated defaults for collecting browser telemetry, optimized for use with {{product.observability}}. -- Ensure compatibility with Elastic ingest pipelines and data models when exporting OpenTelemetry data. -- Minimize Elastic-specific concepts and contribute improvements to the upstream OpenTelemetry project where possible. +EDOT Browser is intended for Real User Monitoring (RUM) use cases, where telemetry is collected directly from users’ browsers to understand frontend performance, user interactions, and end-to-end request flows between frontend and backend services. It is based on OpenTelemetry standards and aims to align with contrib OpenTelemetry behavior. EDOT Browser collects the following signals: @@ -32,109 +23,41 @@ EDOT Browser collects the following signals: - **Metrics**: Browser-side performance and runtime metrics - **Logs**: Using the OpenTelemetry Logs API -For what each signal includes, known limitations, and what is not yet supported (such as Web Vitals), refer to [Metrics, traces, and logs](telemetry.md). +For what each signal includes, known limitations, and what is not yet supported, refer to [Metrics, traces, and logs](telemetry.md). ## How it works [how-it-works] -EDOT Browser runs in the user's browser as part of your web application. When initialized, it instruments the page and captures telemetry (traces, metrics, logs) from document load, user interactions, and network requests. Data is exported using the OpenTelemetry Protocol (OTLP) over HTTP to an endpoint you configure, typically a reverse proxy that injects authentication and forwards the data to {{product.observability}} or an OpenTelemetry Collector. Because the SDK runs in the browser, it cannot hold credentials; the reverse proxy is responsible for adding API keys or other auth before sending data to {{product.observability}}. +EDOT Browser runs in the user's browser as part of your web application. When initialized, it instruments the page and captures telemetry from document load, user interactions, and network requests. Data is exported using the OpenTelemetry Protocol (OTLP) over HTTP to an endpoint you configure, typically a reverse proxy that injects authentication and forwards the data to {{product.observability}} or an OpenTelemetry Collector. Because the SDK runs in the browser, it cannot hold credentials. A reverse proxy is responsible for adding API keys or other auth before sending data to {{product.observability}}. -In {{product.observability}}, you see **`external.http`** spans for browser fetch and XHR requests, **user interaction** spans (for example, click, submit) that group related frontend and backend activity, and end-to-end traces from the browser to your backend in Discover and Service Maps. For details, refer to [What to expect in Kibana](setup.md#what-to-expect-in-kibana) in the setup guide. +In {{product.observability}}, you see `external.http` spans for browser fetch and XHR requests, user interaction spans (such as click, submit) that group related frontend and backend activity, and end-to-end traces from the browser to your backend in Discover and Service Maps. For details, refer to [What to expect in {{kib}}](setup.md#what-to-expect-in-kibana) in the setup guide. ## Limitations [limitations] -EDOT Browser is currently under active development. While the long-term goal is to provide feature parity with classic Elastic {{product.apm}} browser agents, that parity doesn't yet exist. - -In particular: - -- EDOT Browser is not a drop-in replacement for classic Elastic {{product.apm}} RUM agents. -- There is no supported migration path from classic agents at this time. -- Some features available in classic agents are not yet implemented. -- The exact set of provided instrumentations and defaults might change as development continues. - The following capabilities are not currently available in EDOT Browser: - Web Vitals instrumentation - Full feature parity with classic Elastic {{product.apm}} browser agents - Migration tooling from classic agents -Some of these features might be introduced in the future, potentially through contrib OpenTelemetry contributions. - -## EDOT Browser versus classic Elastic {{product.apm}} agents [edot-browser-versus-classic-agents] - -Classic Elastic {{product.apm}} browser agents and EDOT Browser serve similar use cases but are built on different architectures. - -Classic agents: - -- Are Elastic-specific -- Provide mature RUM features out of the box -- Support features not yet available in EDOT Browser - -EDOT Browser: - -- Is based on OpenTelemetry standards -- Aims to align with contrib OpenTelemetry behavior -- Is still evolving toward feature parity - -If you require full feature parity with classic Elastic {{product.apm}} RUM agents today, continue using the classic agents. - ## Browser telemetry and authentication [browser-telemetry-and-authentication] Because EDOT Browser runs in the user’s browser, it cannot safely embed authentication credentials such as API keys. Telemetry must be exported through a reverse proxy that sits between the browser and your OTLP endpoint ({{ecloud}} Managed OTLP or an EDOT Collector). The reverse proxy is required for three reasons: -- **Authentication**: The EDOT Collector or Managed OTLP endpoint expects an `Authorization` header with an API key. Putting that key in browser code would expose it to end users. The reverse proxy injects the header so the key stays on the server. -- **Cross-origin requests**: Your web application and the OTLP endpoint often have different origins. Browsers enforce Cross-Origin Resource Sharing (CORS); without the right headers, export requests are blocked. A reverse proxy on the same origin as your app (or configured to allow it) can add the required CORS headers and handle preflight `OPTIONS` requests. +- **Authentication**: The EDOT Collector or Managed OTLP endpoint expects an `Authorization` header with an API key. The reverse proxy injects the header so the key stays on the server and isn't exposed. +- **Cross-origin requests**: Your web application and the OTLP endpoint often have different origins. Browsers enforce Cross-Origin Resource Sharing (CORS), meaning that without the right headers, export requests are blocked. A reverse proxy on the same origin as your app (or configured to allow it) can add the required CORS headers and handle preflight `OPTIONS` requests. - **Traffic control**: You can apply rate limiting or other controls at the proxy before traffic reaches the Collector or {{product.observability}}. -:::{warning} +For reverse proxy examples and browser constraints (CORS, CSP), refer to [Set up EDOT Browser](setup.md). + +:::{note} Avoid using EDOT Browser alongside any other {{product.apm}} or RUM agent (including classic Elastic {{product.apm}} browser agents). Running multiple agents can cause conflicting instrumentation, duplicate telemetry, or unexpected behavior. ::: -### Example [example-reverse-proxy] - -Example NGINX reverse proxy configuration that forwards telemetry from `webapp.example.com` to an EDOT Collector at `collector.example.com`, injects the required `Authorization` header, and handles CORS preflight: - -```nginx -server { - # Configuration for HTTP/HTTPS goes here - location / { - # Take care of preflight requests - if ($request_method = 'OPTIONS') { - add_header 'Access-Control-Max-Age' 1728000; - add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; - add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; - add_header 'Access-Control-Allow-Credentials' 'true' always; - add_header 'Content-Type' 'text/plain charset=UTF-8'; - add_header 'Content-Length' 0; - return 204; - } - - add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; - add_header 'Access-Control-Allow-Credentials' 'true' always; - add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; - proxy_http_version 1.1; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - # Set the auth header for the Collector here. Follow security best practices - # for adding secrets (for example Docker secrets, Kubernetes Secrets). - proxy_set_header Authorization 'ApiKey ...your Elastic API key...'; - proxy_pass https://collector.example.com:4318; - } -} -``` - -### Browser constraints [browser-constraints] - -If your site uses a Content Security Policy (CSP), add the domain of your OTLP endpoint (or reverse proxy) to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. - -If your app and the export endpoint have different origins, the browser might block requests unless CORS is correctly configured. The reverse proxy must send `Access-Control-Allow-Origin` matching your application origin, handle `OPTIONS` preflight requests with a 204 response, and include `Authorization` in `Access-Control-Allow-Headers` when using API key authentication. The NGINX example above shows one way to do this. - -For more details on reverse proxy setup, CORS, and CSP, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). - ## Next steps [next-steps] To get started with EDOT Browser: - Follow the setup instructions in [Set up EDOT Browser](setup.md) - Review configuration options in [Configure EDOT Browser](configuration.md) -- Refer to [Supported technologies](supported-technologies.md) for details on browsers and instrumentations \ No newline at end of file +- Refer to [Supported technologies](supported-technologies.md) for details on browsers and instrumentations +- If telemetry does not appear, refer to [Troubleshooting](troubleshooting.md) \ No newline at end of file diff --git a/docs/reference/edot-browser/setup.md b/docs/reference/edot-browser/setup.md index 2ed42758..76d5343f 100644 --- a/docs/reference/edot-browser/setup.md +++ b/docs/reference/edot-browser/setup.md @@ -15,9 +15,9 @@ products: This guide shows you how to set up the {{edot}} Browser (EDOT Browser) in a web application and export browser telemetry to {{product.observability}}. -EDOT Browser runs directly in users’ browsers. Because of browser security constraints, setup differs from backend OpenTelemetry SDKs, especially for authentication and data export. Review the reverse proxy requirements before you begin. +EDOT Browser runs directly in users’ browsers. Because of browser security constraints, authentication and data export require reverse proxy configuration. -:::{warning} +:::{note} Do not run EDOT Browser alongside another {{product.apm}} or RUM agent (including classic Elastic {{product.apm}} browser agents). Multiple agents can cause conflicting instrumentation, duplicate telemetry, or unexpected behavior. ::: @@ -27,31 +27,73 @@ Before you set up EDOT Browser, you need: - An {{product.observability}} deployment ({{ecloud}} or self-managed) - An OTLP ingest endpoint ({{ecloud}} Managed OTLP or an EDOT Collector) -- A reverse proxy that accepts telemetry from the browser, injects authentication headers, and forwards data to your OTLP endpoint. You need a reverse proxy because: - - API keys cannot be stored in browser code. - - The browser and endpoint often have different origins, so CORS must be handled. - - You can apply rate limiting or other controls at the proxy. -For more on OTLP endpoints, reverse proxy configuration, authentication, CORS, and CSP, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). +## Set up -## Install EDOT Browser [install-edot-browser] +Follow these steps to set up EDOT Browser. + +::::::{stepper} + +:::::{step} Set up the reverse proxy + +Do not send telemetry directly from the browser to {{product.observability}} using an API key, as any credentials included in browser code are visible to end users and can be misused. EDOT Browser requires a reverse proxy in front of the OTLP endpoint. + +If your site uses a Content Security Policy (CSP), add the domain of your reverse proxy or OTLP endpoint to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. + +If your web application and the export endpoint have different origins, the browser might block requests unless Cross-Origin Resource Sharing (CORS) is configured. Your reverse proxy must return `Access-Control-Allow-Origin` matching your application origin, respond to `OPTIONS` preflight requests with 204, and include `Authorization` in `Access-Control-Allow-Headers` when using API key auth. + +For complete examples and security considerations, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). + +The following example NGINX reverse proxy configuration forwards telemetry from `webapp.example.com` to an EDOT Collector at `collector.example.com`, injects the required `Authorization` header, and handles CORS preflight: + +```nginx +server { + # Configuration for HTTP/HTTPS goes here + location / { + # Take care of preflight requests + if ($request_method = 'OPTIONS') { + add_header 'Access-Control-Max-Age' 1728000; + add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; + add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; + add_header 'Access-Control-Allow-Credentials' 'true' always; + add_header 'Content-Type' 'text/plain charset=UTF-8'; + add_header 'Content-Length' 0; + return 204; + } + + add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; + add_header 'Access-Control-Allow-Credentials' 'true' always; + add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + # Set the auth header for the Collector here. Follow security best practices + # for adding secrets (for example Docker secrets, Kubernetes Secrets). + proxy_set_header Authorization 'ApiKey ...your Elastic API key...'; + proxy_pass https://collector.example.com:4318; + } +} +``` + +::::: + +:::::{step} Install EDOT Browser EDOT Browser is distributed as a single bundle that packages the OpenTelemetry Browser SDK with Elastic-specific defaults. Install EDOT Browser using your package manager: ```bash -# example npm install @elastic/opentelemetry-browser ``` - +::::: -## Initialize EDOT Browser [initialize-edot-browser] +:::::{step} Initialize EDOT Browser -Initialize EDOT Browser as early as possible in your application lifecycle so it can capture initial page loads, user interactions, and network requests. +Initialize EDOT Browser as early as possible in your application lifecycle so it can capture initial page loads, user interactions, and network requests. Call `startBrowserSdk`: -Initialize it: - At the top of your application entry point - In a framework-specific bootstrap location (for example, a React root component, Angular `main.ts`, or a Vue plugin) @@ -59,25 +101,33 @@ Initialize it: A minimal example: ```js -// example -import { initEDOTBrowser } from '@elastic/opentelemetry-browser'; +import { startBrowserSdk } from '@elastic/opentelemetry-browser'; -initEDOTBrowser({ +startBrowserSdk({ serviceName: 'my-web-app', - endpoint: 'https://telemetry.example.com', // reverse proxy URL; do not include /v1/traces or other signal paths + otlpEndpoint: 'https://telemetry.example.com', // reverse proxy URL; do not include /v1/traces or other signal paths }); ``` - - At a minimum, configure: - The service name used to identify your frontend application -- The export endpoint, which must point to your reverse proxy (not directly to {{product.observability}}) +- The `otlpEndpoint`, which must point to your reverse proxy (and not directly to {{product.observability}}) For additional configuration options, refer to [Configure EDOT Browser](configuration.md). -You have successfully initialized EDOT Browser when the SDK loads without errors in the browser console and telemetry begins flowing to your reverse proxy. To confirm data in {{product.observability}}, open the Observability app and check for your service and traces. +::::: +:::::: + +You have successfully set up EDOT Browser when the SDK loads without errors in the browser console and telemetry begins flowing to your reverse proxy. To confirm data in {{product.observability}}, open {{kib}} and check for your service and traces. + +## How browser telemetry is exported [how-browser-telemetry-is-exported] + +EDOT Browser exports telemetry using the OpenTelemetry Protocol (OTLP) over HTTP. Data flows as follows: + +**Browser (EDOT Browser) → Reverse proxy → {{ecloud}} Managed OTLP endpoint or EDOT Collector → {{product.observability}}** + +The browser sends OTLP data to the reverse proxy endpoint that you configured. ## What to expect in {{kib}} [what-to-expect-in-kibana] @@ -85,7 +135,7 @@ After EDOT Browser is sending telemetry to {{product.observability}}, you can in ### Spans from browser fetch and XHR [spans-from-fetch-xhr] -Outgoing HTTP requests made with the browser `fetch` API or `XMLHttpRequest` are captured as **`external.http`** spans. Each request to your backend APIs or third-party domains appears as an `external.http` span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request (time in the browser) and, when your backend is instrumented with OpenTelemetry, link to the corresponding server-side trace using the trace context (trace ID and span ID) propagated in HTTP headers. In the trace view, you see the browser’s `external.http` span as part of the same trace as the backend service spans when propagation is correctly configured. +Outgoing HTTP requests made with the browser `fetch` API or `XMLHttpRequest` are captured as **`external.http`** spans. Each request to your backend APIs or third-party domains appears as an `external.http` span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request (time in the browser) and, when your backend is instrumented with EDOT, link to the corresponding server-side trace using the trace context (trace ID and span ID) propagated in HTTP headers. In the trace view, you see the browser’s `external.http` span as part of the same trace as the backend service spans when propagation is correctly configured. ### User interaction spans and grouping [user-interaction-spans] @@ -100,45 +150,6 @@ Traces that start in the browser (from a user interaction) and continue to your For more on how RUM and distributed traces appear in the Observability app, refer to [User experience (RUM)](docs-content://solutions/observability/applications/user-experience.md). -## How browser telemetry is exported [how-browser-telemetry-is-exported] - -EDOT Browser exports telemetry using the OpenTelemetry Protocol (OTLP) over HTTP. - -Data flows as follows: - -```text -Browser (EDOT Browser) - → Reverse proxy - → {{ecloud}} Managed OTLP endpoint - or EDOT Collector - → {{product.observability}} -``` - -The browser sends OTLP data to the reverse proxy endpoint that you configure. The reverse proxy: - -- Injects authentication headers (for example, Elastic API keys) -- Handles CORS preflight requests -- Optionally applies rate limiting or traffic controls - -## Reverse proxy requirement [reverse-proxy-requirement] - -Do not send telemetry directly from the browser to {{product.observability}} using an API key. - -Any credentials included in browser code are visible to end users and can be misused. EDOT Browser requires a reverse proxy in front of the OTLP endpoint. - -This pattern applies to: - -- {{ecloud}} Managed OTLP endpoints -- An EDOT Collector running in gateway mode - -### Browser constraints: CSP and CORS [browser-constraints] - -If your site uses a Content Security Policy (CSP), add the domain of your reverse proxy or OTLP endpoint to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. - -If your web application and the export endpoint have different origins, the browser might block requests unless CORS is configured. Your reverse proxy must return `Access-Control-Allow-Origin` matching your application origin, respond to `OPTIONS` preflight requests with 204, and include `Authorization` in `Access-Control-Allow-Headers` when using API key auth. The [overview page](index.md#example-reverse-proxy) includes an NGINX example. - -For complete examples and security considerations, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). - ## Next steps [next-steps] After completing setup: diff --git a/docs/reference/edot-browser/supported-technologies.md b/docs/reference/edot-browser/supported-technologies.md index 95e0d5dd..3b9d2df6 100644 --- a/docs/reference/edot-browser/supported-technologies.md +++ b/docs/reference/edot-browser/supported-technologies.md @@ -1,6 +1,6 @@ --- navigation_title: Supported technologies -description: Supported browsers, instrumentations, and known differences in EDOT Browser. +description: Supported browsers and instrumentations in EDOT Browser. applies_to: stack: ga serverless: @@ -13,11 +13,7 @@ products: # Supported technologies -This page lists: - -- Supported browser versions -- Included instrumentations and their default behavior -- Differences between EDOT Browser and contrib OpenTelemetry JS +This page lists supported browser versions, included instrumentations and their default behavior. ## Supported browsers [supported-browsers] @@ -38,30 +34,27 @@ Internet Explorer is not supported. At a minimum, the runtime environment must support: -- ES2018 (or later) language features +- ES2022 (the SDK bundle is built with this target) - `fetch` API - `Promise` - `Performance` and `PerformanceObserver` APIs - - If your application targets older browsers, you might need to provide polyfills. EDOT Browser does not ship with built-in polyfills. ## Included instrumentations [included-instrumentations] EDOT Browser bundles a curated set of OpenTelemetry JS instrumentations suitable for browser environments. -The following table lists instrumentations that are currently included: - -| Instrumentation | Included | On by default | Notes | -|-----------------|----------|-------------------|-------| -| Document load | TODO | TODO | TODO | -| Fetch | TODO | TODO | TODO | -| XMLHttpRequest | TODO | TODO | TODO | -| User interaction| TODO | TODO | TODO | -| Long tasks | TODO | TODO | TODO | +The following instrumentations are included and turned on by default. You can turn off any of them using `configInstrumentations` by setting `enabled: false` for the corresponding key when calling `startBrowserSdk`: - +| Instrumentation | Package | On by default | +|-----------------|---------|----------------| +| Document load | `@opentelemetry/instrumentation-document-load` | Yes | +| Fetch | `@opentelemetry/instrumentation-fetch` | Yes | +| XMLHttpRequest | `@opentelemetry/instrumentation-xml-http-request` | Yes | +| User interaction| `@opentelemetry/instrumentation-user-interaction` | Yes | +| Long tasks | `@opentelemetry/instrumentation-long-task` | Yes | +| Web exception | `@opentelemetry/instrumentation-web-exception` | Yes | ### Default behavior @@ -74,47 +67,7 @@ By default, EDOT Browser: -You can turn off or override instrumentations during initialization if needed. - - - -## Differences from contrib OpenTelemetry JS [differences-from-upstream] - -EDOT Browser builds on top of contrib OpenTelemetry JS, but introduces several differences to simplify setup and align with {{product.observability}}. - -### Configuration model - -- EDOT Browser doesn't read environment variables at runtime. -- Configuration must be passed explicitly during initialization. -- Elastic-specific configuration options might be available. - -### Export behavior - -- EDOT Browser expects telemetry to be sent to a reverse proxy. -- Direct export to authenticated OTLP endpoints is not supported in the browser. -- Authentication headers must be injected by infrastructure outside the browser. - -### Defaults and opinionated setup - -Compared to contrib OpenTelemetry JS: - -- EDOT Browser provides a simplified initialization API. -- A curated set of instrumentations is preconfigured. -- Sensible defaults are applied for Elastic ingestion. - - - -### Scope limitations - -Some contrib OpenTelemetry JS features are not available or are intentionally unsupported in EDOT Browser due to browser constraints. - -These might include: - -- Environment-based configuration -- Certain resource detectors -- Node.js-specific instrumentation - - +To turn off an instrumentation, pass `configInstrumentations` to `startBrowserSdk` with the instrumentation key and `enabled: false` (for example, `configInstrumentations: { '@opentelemetry/instrumentation-long-task': { enabled: false } }`). ## Version compatibility [version-compatibility] @@ -127,28 +80,11 @@ These might include: ## Known limitations [known-limitations] -When using EDOT Browser with {{product.observability}}, be aware of the following: - -- API key authentication requires a reverse proxy; credentials cannot be stored in the browser. -- Metrics from browser-based RUM might have more limited utility than backend metrics, depending on your use case. -- Some OpenTelemetry browser instrumentations are still experimental. Behavior might change. -- Monitor the performance impact on the browser when using multiple instrumentations, especially on lower-end devices. - -## Troubleshooting [troubleshooting] - -If telemetry does not appear in {{product.observability}}: - -- Confirm the export endpoint points to your reverse proxy (not directly to {{product.observability}}) and doesn't include signal paths like `/v1/traces`. -- Check the browser console for network errors or OpenTelemetry-related messages. Cross-Origin Resource Sharing (CORS) errors often mean the reverse proxy is not sending the right `Access-Control-Allow-Origin` or preflight response. -- Ensure the reverse proxy can reach your EDOT Collector or {{ecloud}} Managed OTLP endpoint; check proxy logs for connection or auth failures. -- Ensure service name is set and doesn't contain special characters. -- Set the log level to `debug` or `verbose` during initialization to check the detailed export and instrumentation output in the console. - -If you use a Content Security Policy, ensure the proxy or OTLP endpoint domain is in the `connect-src` directive. For bundler or module resolution errors, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md) and the general [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) docs. +For capabilities that are not yet available and per-signal limitations (metrics, traces, logs), refer to [Limitations](index.md#limitations) on the overview page and [Metrics, traces, and logs](telemetry.md). ## Next steps [next-steps] - Refer to [Set up EDOT Browser](setup.md) to get started. - Refer to [Metrics, traces, and logs](telemetry.md) for what is emitted per signal and what is not yet supported. - Review [Configuration](configuration.md) to customize behavior. -- Refer to [Known limitations](#known-limitations) and [Troubleshooting](#troubleshooting) above for EDOT Browser–specific guidance, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file +- Refer to [Known limitations](#known-limitations) above, [Troubleshooting](troubleshooting.md) for EDOT Browser–specific guidance, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/telemetry.md b/docs/reference/edot-browser/telemetry.md index 3ab491e8..d759dce5 100644 --- a/docs/reference/edot-browser/telemetry.md +++ b/docs/reference/edot-browser/telemetry.md @@ -13,18 +13,18 @@ products: # Metrics, traces, and logs -EDOT Browser can export all three OpenTelemetry signals—metrics, traces, and logs—to {{product.observability}} using OTLP. This page describes what is currently emitted for each signal, known limitations of browser-based telemetry, and what is not yet supported. +EDOT Browser can export all three OpenTelemetry signals (metrics, traces, and logs) to {{product.observability}} using OTLP. ## Metrics [metrics] ### What EDOT Browser currently emits [metrics-what-is-emitted] -EDOT Browser configures the OpenTelemetry MeterProvider and exports metrics over OTLP when metrics are turned on. The exact set of built-in metrics is still evolving. Metrics might be produced by: +EDOT Browser configures the OpenTelemetry MeterProvider and exports metrics over OTLP to the `/v1/metrics` path. Metrics can be produced by: -- **Long task instrumentation**: When long task instrumentation is included and turned on, it can report observations related to main-thread blocking (for example long tasks exceeding a threshold). The names and attributes of these metrics depend on the instrumentation implementation. +- **Long task instrumentation**: When long task instrumentation is turned on (it can be turned off using instrumentation configuration), it can report observations related to main-thread blocking (for example long tasks exceeding a threshold). The names and attributes depend on the instrumentation implementation. - **Custom metrics**: Your application can create meters and instruments (counters, histograms, and so on) using the OpenTelemetry Metrics API. EDOT Browser exports those metrics along with any SDK-provided ones. -If you turn on metrics export, ensure your reverse proxy and OTLP endpoint accept the `/v1/metrics` path. +Ensure your reverse proxy and OTLP endpoint accept the `/v1/metrics` path. ### Known limitations of browser-side metrics [metrics-limitations] @@ -34,7 +34,7 @@ If you turn on metrics export, ensure your reverse proxy and OTLP endpoint accep - Browser environments vary (device, network, extensions). Metric values might be noisier or less consistent than server-side metrics. :::{note} -Web Vitals (such as Largest Contentful Paint (LCP), First Input Delay (FID), Cumulative Layout Shift (CLS), and related metrics) are not supported in EDOT Browser. There is no built-in Web Vitals instrumentation. If you need Web Vitals or similar Core Web Vitals data, use classic Elastic {{product.apm}} browser agents or a dedicated Web Vitals library. +Web Vitals, such as Largest Contentful Paint (LCP), First Input Delay (FID), Cumulative Layout Shift (CLS), and related metrics, are not supported in EDOT Browser. There is no built-in Web Vitals instrumentation. If you need Web Vitals or similar Core Web Vitals data, use classic Elastic {{product.apm}} browser agents or a dedicated Web Vitals library. ::: ## Traces [traces] @@ -43,7 +43,7 @@ Web Vitals (such as Largest Contentful Paint (LCP), First Input Delay (FID), Cum EDOT Browser initializes tracing and registers instrumentations that produce spans: -- Spans for the initial document load and related navigation timing, when the document load instrumentation is included and turned on. +- Spans for the initial document load and related navigation timing (document load instrumentation is turned on by default). - Each outgoing request using `fetch` or `XMLHttpRequest` is captured as an **`external.http`** span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request. - Spans for user actions such as "click" and "submit". These interaction spans group the subsequent work (for example `external.http` requests) so you can attribute frontend and backend activity to a specific user action in {{product.observability}}. diff --git a/docs/reference/edot-browser/toc.yml b/docs/reference/edot-browser/toc.yml index e8772e04..c1932023 100644 --- a/docs/reference/edot-browser/toc.yml +++ b/docs/reference/edot-browser/toc.yml @@ -3,4 +3,5 @@ toc: - file: setup.md - file: configuration.md - file: telemetry.md - - file: supported-technologies.md \ No newline at end of file + - file: supported-technologies.md + - file: troubleshooting.md \ No newline at end of file diff --git a/docs/reference/edot-browser/troubleshooting.md b/docs/reference/edot-browser/troubleshooting.md new file mode 100644 index 00000000..a762fb46 --- /dev/null +++ b/docs/reference/edot-browser/troubleshooting.md @@ -0,0 +1,30 @@ +--- +navigation_title: Troubleshooting +description: Troubleshoot EDOT Browser telemetry export and common issues. +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Troubleshooting EDOT Browser + +If telemetry doesn't appear in {{product.observability}}, try the following: + +- Confirm the `otlpEndpoint` option points to your reverse proxy (not directly to {{product.observability}}) and doesn't include signal paths like `/v1/traces`. +- Check the browser console for network errors or OpenTelemetry-related messages. Cross-Origin Resource Sharing (CORS) errors often mean the reverse proxy is not sending the right `Access-Control-Allow-Origin` or preflight response. +- Ensure the reverse proxy can reach your EDOT Collector or {{ecloud}} Managed OTLP endpoint. To do so, check proxy logs for connection or authorization failures. +- Ensure service name is set and doesn't contain special characters. +- Set `logLevel` to `debug` or `verbose` in the `startBrowserSdk` options to see detailed export and instrumentation output in the console. + +If you use a Content Security Policy, ensure the proxy or OTLP endpoint domain is in the `connect-src` directive. For bundler or module resolution errors, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md) and the general [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) docs. + +## Next steps [next-steps] + +- Refer to [Known limitations](supported-technologies.md#known-limitations) for what is not yet supported. +- Refer to [Set up EDOT Browser](setup.md) for installation and initialization. +- For general OTLP ingest issues, refer to [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md). From e088b7519a9dc0fad8c873c0023379d479c5a262 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Mon, 9 Mar 2026 11:21:33 +0100 Subject: [PATCH 5/6] Apply comments --- docs/reference/edot-browser/configuration.md | 1 - docs/reference/edot-browser/index.md | 1 - docs/reference/edot-browser/setup.md | 10 ++++++++-- docs/reference/edot-browser/supported-technologies.md | 2 +- docs/reference/edot-browser/telemetry.md | 2 +- 5 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/reference/edot-browser/configuration.md b/docs/reference/edot-browser/configuration.md index 9f42e7c6..2285ca76 100644 --- a/docs/reference/edot-browser/configuration.md +++ b/docs/reference/edot-browser/configuration.md @@ -30,7 +30,6 @@ EDOT Browser does not read `OTEL_*` variables directly. Instead, it accepts conf Typical configuration patterns include: -- Injecting values during build (for example, `process.env.*` replaced by a bundler). - Passing configuration from a server-rendered page. - Loading configuration from a global object populated at runtime. diff --git a/docs/reference/edot-browser/index.md b/docs/reference/edot-browser/index.md index 3ee49545..920f0f70 100644 --- a/docs/reference/edot-browser/index.md +++ b/docs/reference/edot-browser/index.md @@ -35,7 +35,6 @@ In {{product.observability}}, you see `external.http` spans for browser fetch an The following capabilities are not currently available in EDOT Browser: -- Web Vitals instrumentation - Full feature parity with classic Elastic {{product.apm}} browser agents - Migration tooling from classic agents diff --git a/docs/reference/edot-browser/setup.md b/docs/reference/edot-browser/setup.md index 76d5343f..3686a0b5 100644 --- a/docs/reference/edot-browser/setup.md +++ b/docs/reference/edot-browser/setup.md @@ -80,14 +80,20 @@ server { :::::{step} Install EDOT Browser -EDOT Browser is distributed as a single bundle that packages the OpenTelemetry Browser SDK with Elastic-specific defaults. +EDOT Browser is distributed in two ways: -Install EDOT Browser using your package manager: +- **Package**: Install using your package manager and import in your application (recommended when using a bundler). +- **Bundle**: A single JS file you can load using a script tag when you are not using a bundler. + +**Using the package (with a bundler):** ```bash npm install @elastic/opentelemetry-browser ``` +**Using the bundle:** A single JS bundle is be available for script-tag usage (for example, from a CDN or your own host). Use it when your application doesn't use a bundler. + + ::::: :::::{step} Initialize EDOT Browser diff --git a/docs/reference/edot-browser/supported-technologies.md b/docs/reference/edot-browser/supported-technologies.md index 3b9d2df6..90dbfb2e 100644 --- a/docs/reference/edot-browser/supported-technologies.md +++ b/docs/reference/edot-browser/supported-technologies.md @@ -43,7 +43,7 @@ If your application targets older browsers, you might need to provide polyfills. ## Included instrumentations [included-instrumentations] -EDOT Browser bundles a curated set of OpenTelemetry JS instrumentations suitable for browser environments. +EDOT Browser bundles a curated set of OpenTelemetry JS instrumentations suitable for browser environments. This list is being reviewed and might change in future releases. The following instrumentations are included and turned on by default. You can turn off any of them using `configInstrumentations` by setting `enabled: false` for the corresponding key when calling `startBrowserSdk`: diff --git a/docs/reference/edot-browser/telemetry.md b/docs/reference/edot-browser/telemetry.md index d759dce5..74286a8b 100644 --- a/docs/reference/edot-browser/telemetry.md +++ b/docs/reference/edot-browser/telemetry.md @@ -34,7 +34,7 @@ Ensure your reverse proxy and OTLP endpoint accept the `/v1/metrics` path. - Browser environments vary (device, network, extensions). Metric values might be noisier or less consistent than server-side metrics. :::{note} -Web Vitals, such as Largest Contentful Paint (LCP), First Input Delay (FID), Cumulative Layout Shift (CLS), and related metrics, are not supported in EDOT Browser. There is no built-in Web Vitals instrumentation. If you need Web Vitals or similar Core Web Vitals data, use classic Elastic {{product.apm}} browser agents or a dedicated Web Vitals library. +Web Vitals instrumentation (LCP, FID, CLS, and related Core Web Vitals metrics) is planned. Until it's available, for Core Web Vitals data you can use classic Elastic {{product.apm}} browser agents or a dedicated Web Vitals library. ::: ## Traces [traces] From 881bee5ecfcd6d54e86d1f79d8564e90ceb4d3cd Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Tue, 10 Mar 2026 18:45:07 +0100 Subject: [PATCH 6/6] Update EDOT Browser documentation to include new sections on agent installation and proxy configuration. --- docs/reference/edot-browser/configuration.md | 2 +- docs/reference/edot-browser/index.md | 4 +- docs/reference/edot-browser/install-agent.md | 80 ++++++++++++ docs/reference/edot-browser/proxy-cors.md | 77 ++++++++++++ docs/reference/edot-browser/setup.md | 116 ++---------------- .../edot-browser/supported-technologies.md | 14 ++- docs/reference/edot-browser/telemetry.md | 6 +- docs/reference/edot-browser/toc.yml | 3 + .../reference/edot-browser/troubleshooting.md | 2 +- 9 files changed, 190 insertions(+), 114 deletions(-) create mode 100644 docs/reference/edot-browser/install-agent.md create mode 100644 docs/reference/edot-browser/proxy-cors.md diff --git a/docs/reference/edot-browser/configuration.md b/docs/reference/edot-browser/configuration.md index 2285ca76..7cdd38d9 100644 --- a/docs/reference/edot-browser/configuration.md +++ b/docs/reference/edot-browser/configuration.md @@ -102,7 +102,7 @@ Diagnostic logs are written to the browser console. For more information on usin ## Next steps [next-steps] -- Refer to [Set up EDOT Browser](setup.md) for installation and initialization. +- Refer to [Install the agent](install-agent.md) and [Proxy and CORS](proxy-cors.md) for installation and proxy configuration. - Refer to [Metrics, traces, and logs](telemetry.md) for what each signal emits and limitations. - Review [Supported technologies](supported-technologies.md) for browser and instrumentation support. - Refer to [Troubleshooting](troubleshooting.md) for EDOT Browser–specific issues, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/index.md b/docs/reference/edot-browser/index.md index 920f0f70..37dd479c 100644 --- a/docs/reference/edot-browser/index.md +++ b/docs/reference/edot-browser/index.md @@ -46,7 +46,7 @@ Because EDOT Browser runs in the user’s browser, it cannot safely embed authen - **Cross-origin requests**: Your web application and the OTLP endpoint often have different origins. Browsers enforce Cross-Origin Resource Sharing (CORS), meaning that without the right headers, export requests are blocked. A reverse proxy on the same origin as your app (or configured to allow it) can add the required CORS headers and handle preflight `OPTIONS` requests. - **Traffic control**: You can apply rate limiting or other controls at the proxy before traffic reaches the Collector or {{product.observability}}. -For reverse proxy examples and browser constraints (CORS, CSP), refer to [Set up EDOT Browser](setup.md). +For reverse proxy and CORS configuration, refer to [Proxy and CORS](proxy-cors.md). For installation and initialization, refer to [Set up EDOT Browser](setup.md) and [Install the agent](install-agent.md). :::{note} Avoid using EDOT Browser alongside any other {{product.apm}} or RUM agent (including classic Elastic {{product.apm}} browser agents). Running multiple agents can cause conflicting instrumentation, duplicate telemetry, or unexpected behavior. @@ -56,7 +56,7 @@ Avoid using EDOT Browser alongside any other {{product.apm}} or RUM agent (inclu To get started with EDOT Browser: -- Follow the setup instructions in [Set up EDOT Browser](setup.md) +- Follow the setup instructions in [Set up EDOT Browser](setup.md): [Install the agent](install-agent.md) and [Configure proxy and CORS](proxy-cors.md) - Review configuration options in [Configure EDOT Browser](configuration.md) - Refer to [Supported technologies](supported-technologies.md) for details on browsers and instrumentations - If telemetry does not appear, refer to [Troubleshooting](troubleshooting.md) \ No newline at end of file diff --git a/docs/reference/edot-browser/install-agent.md b/docs/reference/edot-browser/install-agent.md new file mode 100644 index 00000000..f7d0f8ac --- /dev/null +++ b/docs/reference/edot-browser/install-agent.md @@ -0,0 +1,80 @@ +--- +navigation_title: Install the agent +description: Install and initialize the EDOT Browser agent (package or bundle). +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Install the agent + +EDOT Browser is distributed in two ways. The choice affects how you install it, how much control you have over instrumentations and bundle size, and how updates might affect your application. + +## Package versus bundle [package-vs-bundle] + +| Option | Best for | Trade-offs | +|--------|----------|------------| +| **Bundle** | Applications that don't use a bundler (single JS file loaded using script tag). | Works out of the box with no build step. Updating the bundle can introduce breaking changes when upstream instrumentations or configuration change. You have to absorb those changes when you upgrade. | +| **Package** | Applications that use a bundler (for example: webpack, Vite, Rollup). | You choose which instrumentations to include, so you have more control and can achieve a smaller bundle size by installing only what you need. You control when to upgrade instrumentations and can pin versions to avoid breaking changes until you are ready. | + +Before installing, ensure you have [configured a reverse proxy and CORS](proxy-cors.md) so the browser can export telemetry securely. + +## Install using the package [install-package] + +Install EDOT Browser using your package manager: + +```bash +npm install @elastic/opentelemetry-browser +``` + +When you use the package, your bundler includes only the code you import. You can control which instrumentations are enabled using configuration and, if the SDK supports it in the future, by passing only the instrumentation instances you need. This can reduce the final bundle size compared to the full bundle. + +For supported bundlers and browser requirements, refer to [Supported technologies](supported-technologies.md). + +## Install using the bundle [install-bundle] + +A single JS bundle is available for script-tag usage (for example, from a CDN or your own host). Use it when your application doesn't use a bundler. + +The bundle works out of the box: you add a script tag and initialize the SDK. When you update to a newer bundle version, upstream instrumentation or configuration changes might introduce breaking changes. You must test upgrades in a non-production environment. + + + +## Initialize EDOT Browser [initialize] + +Initialize EDOT Browser as early as possible in your application lifecycle so it can capture initial page loads, user interactions, and network requests. Call `startBrowserSdk`: + +- At the top of your application entry point +- In a framework-specific bootstrap location (for example, a React root component, Angular `main.ts`, or a Vue plugin) + +Minimal example (package): + +```js +import { startBrowserSdk } from '@elastic/opentelemetry-browser'; + +startBrowserSdk({ + serviceName: 'my-web-app', + otlpEndpoint: 'https://telemetry.example.com', // reverse proxy URL; do not include /v1/traces or other signal paths +}); +``` + +At a minimum, configure: + +- `serviceName`: Identifies your frontend application in {{product.observability}}. +- `otlpEndpoint`: Must point to your reverse proxy (not directly to {{product.observability}}). + +For all configuration options, refer to [Configure EDOT Browser](configuration.md). + +## Verify setup [verify] + +You have successfully set up EDOT Browser when the SDK loads without errors in the browser console and telemetry flows to your reverse proxy. To confirm data in {{product.observability}}, open {{kib}} and check for your service and traces. For what you see in the UI, refer to [What to expect in {{kib}}](setup.md#what-to-expect-in-kibana) in the setup guide. + +## Next steps [next-steps] + +- Refer to [Set up EDOT Browser](setup.md) for an overview and what to expect in {{kib}}. +- Refer to [Configure EDOT Browser](configuration.md) to customize behavior and defaults. +- Review [Supported technologies](supported-technologies.md) for browsers and instrumentations. diff --git a/docs/reference/edot-browser/proxy-cors.md b/docs/reference/edot-browser/proxy-cors.md new file mode 100644 index 00000000..9199ae8b --- /dev/null +++ b/docs/reference/edot-browser/proxy-cors.md @@ -0,0 +1,77 @@ +--- +navigation_title: Proxy and CORS +description: Configure a reverse proxy and CORS for EDOT Browser telemetry export. +applies_to: + stack: ga + serverless: + observability: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Proxy and CORS configuration + +EDOT Browser exports telemetry from the user's browser to an OTLP endpoint. You must put a reverse proxy in front of your OTLP endpoint and configure it for authentication and Cross-Origin Resource Sharing (CORS). + +## Why a reverse proxy is required [why-reverse-proxy] + +Do not send telemetry directly from the browser to {{product.observability}} with an API key in client-side code. Any credentials in browser code are visible to end users and can be misused. EDOT Browser requires a reverse proxy in front of the OTLP endpoint for these reasons: + +- **Authentication**: The EDOT Collector or {{ecloud}} Managed OTLP endpoint expects an `Authorization` header with an API key. The reverse proxy injects the header so the key stays on the server and is not exposed to the browser. +- **Cross-origin requests**: Your web application and the OTLP endpoint often have different origins. Browsers enforce CORS, so without the right headers, export requests are blocked. A reverse proxy on the same origin as your app (or configured to allow it) can add the required CORS headers and handle preflight `OPTIONS` requests. +- **Traffic control**: You can apply rate limiting or other controls at the proxy before traffic reaches the Collector or {{product.observability}}. + +For complete examples and security considerations, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). + +## Content Security Policy (CSP) [content-security-policy] + +If your site uses a Content Security Policy (CSP), add the domain of your reverse proxy or OTLP endpoint to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. + +## CORS requirements [cors-requirements] + +When your web application and the export endpoint have different origins, the browser might block requests unless CORS is configured. Your reverse proxy must: + +- Return `Access-Control-Allow-Origin` matching your application origin +- Respond to `OPTIONS` preflight requests with 204 +- Include `Authorization` in `Access-Control-Allow-Headers` when using API key authentication + +## Example: NGINX reverse proxy [example-nginx] + +The following example forwards telemetry from `webapp.example.com` to an EDOT Collector at `collector.example.com`, injects the required `Authorization` header, and handles CORS preflight: + +```nginx +server { + # Configuration for HTTP/HTTPS goes here + location / { + # Take care of preflight requests + if ($request_method = 'OPTIONS') { + add_header 'Access-Control-Max-Age' 1728000; + add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; + add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; + add_header 'Access-Control-Allow-Credentials' 'true' always; + add_header 'Content-Type' 'text/plain charset=UTF-8'; + add_header 'Content-Length' 0; + return 204; + } + + add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; + add_header 'Access-Control-Allow-Credentials' 'true' always; + add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + # Set the auth header for the Collector here. Follow security best practices + # for adding secrets (for example Docker secrets, Kubernetes Secrets). + proxy_set_header Authorization 'ApiKey ...your Elastic API key...'; + proxy_pass https://collector.example.com:4318; + } +} +``` + +## Next steps [next-steps] + +- [Install the agent](install-agent.md) and initialize EDOT Browser in your application. +- Refer to [Configure EDOT Browser](configuration.md) for initialization options. diff --git a/docs/reference/edot-browser/setup.md b/docs/reference/edot-browser/setup.md index 3686a0b5..9e700faa 100644 --- a/docs/reference/edot-browser/setup.md +++ b/docs/reference/edot-browser/setup.md @@ -15,7 +15,10 @@ products: This guide shows you how to set up the {{edot}} Browser (EDOT Browser) in a web application and export browser telemetry to {{product.observability}}. -EDOT Browser runs directly in users’ browsers. Because of browser security constraints, authentication and data export require reverse proxy configuration. +EDOT Browser runs directly in users' browsers. Because of browser security constraints, authentication and data export require a reverse proxy. When your OTLP endpoint is available ({{ecloud}} Managed OTLP or an EDOT Collector), do the following: + +- [Install the agent](install-agent.md): Add EDOT Browser to your application (package or bundle) and initialize it. +- [Configure proxy and CORS](proxy-cors.md): Set up a reverse proxy in front of your OTLP endpoint and configure CORS so the browser can export telemetry securely. :::{note} Do not run EDOT Browser alongside another {{product.apm}} or RUM agent (including classic Elastic {{product.apm}} browser agents). Multiple agents can cause conflicting instrumentation, duplicate telemetry, or unexpected behavior. @@ -28,112 +31,13 @@ Before you set up EDOT Browser, you need: - An {{product.observability}} deployment ({{ecloud}} or self-managed) - An OTLP ingest endpoint ({{ecloud}} Managed OTLP or an EDOT Collector) -## Set up - -Follow these steps to set up EDOT Browser. - -::::::{stepper} - -:::::{step} Set up the reverse proxy - -Do not send telemetry directly from the browser to {{product.observability}} using an API key, as any credentials included in browser code are visible to end users and can be misused. EDOT Browser requires a reverse proxy in front of the OTLP endpoint. - -If your site uses a Content Security Policy (CSP), add the domain of your reverse proxy or OTLP endpoint to the `connect-src` directive so the browser allows export requests. For example: `connect-src 'self' https://telemetry.example.com`. - -If your web application and the export endpoint have different origins, the browser might block requests unless Cross-Origin Resource Sharing (CORS) is configured. Your reverse proxy must return `Access-Control-Allow-Origin` matching your application origin, respond to `OPTIONS` preflight requests with 204, and include `Authorization` in `Access-Control-Allow-Headers` when using API key auth. - -For complete examples and security considerations, refer to [OpenTelemetry for Real User Monitoring (RUM)](docs-content://solutions/observability/applications/otel-rum.md). - -The following example NGINX reverse proxy configuration forwards telemetry from `webapp.example.com` to an EDOT Collector at `collector.example.com`, injects the required `Authorization` header, and handles CORS preflight: - -```nginx -server { - # Configuration for HTTP/HTTPS goes here - location / { - # Take care of preflight requests - if ($request_method = 'OPTIONS') { - add_header 'Access-Control-Max-Age' 1728000; - add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; - add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; - add_header 'Access-Control-Allow-Credentials' 'true' always; - add_header 'Content-Type' 'text/plain charset=UTF-8'; - add_header 'Content-Length' 0; - return 204; - } - - add_header 'Access-Control-Allow-Origin' 'webapp.example.com' always; - add_header 'Access-Control-Allow-Credentials' 'true' always; - add_header 'Access-Control-Allow-Headers' 'Accept,Accept-Language,Authorization,Content-Language,Content-Type' always; - proxy_http_version 1.1; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - # Set the auth header for the Collector here. Follow security best practices - # for adding secrets (for example Docker secrets, Kubernetes Secrets). - proxy_set_header Authorization 'ApiKey ...your Elastic API key...'; - proxy_pass https://collector.example.com:4318; - } -} -``` - -::::: - -:::::{step} Install EDOT Browser - -EDOT Browser is distributed in two ways: - -- **Package**: Install using your package manager and import in your application (recommended when using a bundler). -- **Bundle**: A single JS file you can load using a script tag when you are not using a bundler. - -**Using the package (with a bundler):** - -```bash -npm install @elastic/opentelemetry-browser -``` - -**Using the bundle:** A single JS bundle is be available for script-tag usage (for example, from a CDN or your own host). Use it when your application doesn't use a bundler. - - -::::: - -:::::{step} Initialize EDOT Browser - -Initialize EDOT Browser as early as possible in your application lifecycle so it can capture initial page loads, user interactions, and network requests. Call `startBrowserSdk`: - - -- At the top of your application entry point -- In a framework-specific bootstrap location (for example, a React root component, Angular `main.ts`, or a Vue plugin) - -A minimal example: - -```js -import { startBrowserSdk } from '@elastic/opentelemetry-browser'; - -startBrowserSdk({ - serviceName: 'my-web-app', - otlpEndpoint: 'https://telemetry.example.com', // reverse proxy URL; do not include /v1/traces or other signal paths -}); -``` - -At a minimum, configure: - -- The service name used to identify your frontend application -- The `otlpEndpoint`, which must point to your reverse proxy (and not directly to {{product.observability}}) - -For additional configuration options, refer to [Configure EDOT Browser](configuration.md). - -::::: -:::::: - -You have successfully set up EDOT Browser when the SDK loads without errors in the browser console and telemetry begins flowing to your reverse proxy. To confirm data in {{product.observability}}, open {{kib}} and check for your service and traces. - ## How browser telemetry is exported [how-browser-telemetry-is-exported] EDOT Browser exports telemetry using the OpenTelemetry Protocol (OTLP) over HTTP. Data flows as follows: **Browser (EDOT Browser) → Reverse proxy → {{ecloud}} Managed OTLP endpoint or EDOT Collector → {{product.observability}}** -The browser sends OTLP data to the reverse proxy endpoint that you configured. +The browser sends OTLP data to the reverse proxy endpoint that you configure. ## What to expect in {{kib}} [what-to-expect-in-kibana] @@ -141,7 +45,7 @@ After EDOT Browser is sending telemetry to {{product.observability}}, you can in ### Spans from browser fetch and XHR [spans-from-fetch-xhr] -Outgoing HTTP requests made with the browser `fetch` API or `XMLHttpRequest` are captured as **`external.http`** spans. Each request to your backend APIs or third-party domains appears as an `external.http` span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request (time in the browser) and, when your backend is instrumented with EDOT, link to the corresponding server-side trace using the trace context (trace ID and span ID) propagated in HTTP headers. In the trace view, you see the browser’s `external.http` span as part of the same trace as the backend service spans when propagation is correctly configured. +Outgoing HTTP requests made with the browser `fetch` API or `XMLHttpRequest` are captured as `external.http` spans. Each request to your backend APIs or third-party domains appears as an `external.http` span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request (time in the browser) and, when your backend is instrumented with EDOT, link to the corresponding server-side trace using the trace context (trace ID and span ID) propagated in HTTP headers. In the trace view, you see the browser's `external.http` span as part of the same trace as the backend service spans when propagation is correctly configured. ### User interaction spans and grouping [user-interaction-spans] @@ -160,8 +64,8 @@ For more on how RUM and distributed traces appear in the Observability app, refe After completing setup: -- Refer to [What to expect in {{kib}}](#what-to-expect-in-kibana) above for the span types and views you see (for example, `external.http`, user interaction grouping, Discover and Service Maps). -- Refer to [Metrics, traces, and logs](telemetry.md) for what is emitted for each signal and known limitations. +- Refer to [Install the agent](install-agent.md) and [Proxy and CORS](proxy-cors.md) for installation and proxy configuration. - Refer to [Configure EDOT Browser](configuration.md) to customize behavior and defaults. -- Review [Supported technologies](supported-technologies.md) for information about browsers and instrumentations. -- Read [User experience (RUM)](docs-content://solutions/observability/applications/user-experience.md) for more on how browser traces appear in the Observability app. \ No newline at end of file +- Refer to [Metrics, traces, and logs](telemetry.md) for what is emitted for each signal and known limitations. +- Review [Supported technologies](supported-technologies.md) for information about browsers, bundlers, and instrumentations. +- If telemetry doesn't appear, refer to [Troubleshooting](troubleshooting.md). diff --git a/docs/reference/edot-browser/supported-technologies.md b/docs/reference/edot-browser/supported-technologies.md index 90dbfb2e..f0c353fa 100644 --- a/docs/reference/edot-browser/supported-technologies.md +++ b/docs/reference/edot-browser/supported-technologies.md @@ -41,6 +41,18 @@ At a minimum, the runtime environment must support: If your application targets older browsers, you might need to provide polyfills. EDOT Browser does not ship with built-in polyfills. +## Bundlers [bundlers] + +When you install EDOT Browser as a package (see [Install the agent](install-agent.md)), you use a JavaScript bundler to build your application. The following bundlers are supported for use with the EDOT Browser package: + +| Bundler | Notes | +|---------|-------| +| Example 1 | Supported. Use with your existing webpack configuration. | +| 2 | Supported. | +| 3 | Supported. | + +Your bundler includes only the EDOT Browser code (and instrumentations) that you import, so you can control the final bundle size. If you don't use a bundler, use the [EDOT Browser bundle](install-agent.md#install-bundle) instead (single JS file loaded using a script tag). + ## Included instrumentations [included-instrumentations] EDOT Browser bundles a curated set of OpenTelemetry JS instrumentations suitable for browser environments. This list is being reviewed and might change in future releases. @@ -84,7 +96,7 @@ For capabilities that are not yet available and per-signal limitations (metrics, ## Next steps [next-steps] -- Refer to [Set up EDOT Browser](setup.md) to get started. +- Refer to [Set up EDOT Browser](setup.md) and [Install the agent](install-agent.md) to get started. - Refer to [Metrics, traces, and logs](telemetry.md) for what is emitted per signal and what is not yet supported. - Review [Configuration](configuration.md) to customize behavior. - Refer to [Known limitations](#known-limitations) above, [Troubleshooting](troubleshooting.md) for EDOT Browser–specific guidance, or [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md) for general OTLP ingest issues. \ No newline at end of file diff --git a/docs/reference/edot-browser/telemetry.md b/docs/reference/edot-browser/telemetry.md index 74286a8b..062f12a7 100644 --- a/docs/reference/edot-browser/telemetry.md +++ b/docs/reference/edot-browser/telemetry.md @@ -44,10 +44,10 @@ Web Vitals instrumentation (LCP, FID, CLS, and related Core Web Vitals metrics) EDOT Browser initializes tracing and registers instrumentations that produce spans: - Spans for the initial document load and related navigation timing (document load instrumentation is turned on by default). -- Each outgoing request using `fetch` or `XMLHttpRequest` is captured as an **`external.http`** span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request. +- Each outgoing request using `fetch` or `XMLHttpRequest` is captured as an `external.http` span with attributes such as URL, HTTP method, and status code. These spans represent the client-side portion of the request. - Spans for user actions such as "click" and "submit". These interaction spans group the subsequent work (for example `external.http` requests) so you can attribute frontend and backend activity to a specific user action in {{product.observability}}. -When your backend is instrumented with OpenTelemetry and trace context (trace ID, span ID) is propagated in HTTP headers, the browser’s `external.http` span and the backend spans appear in the same trace, giving you end-to-end visibility in Discover and Service Maps. Refer to [What to expect in Kibana](setup.md#what-to-expect-in-kibana) for how these traces appear in the Observability app. +When your backend is instrumented with OpenTelemetry and trace context (trace ID, span ID) is propagated in HTTP headers, the browser’s `external.http` span and the backend spans appear in the same trace, giving you end-to-end visibility in Discover and Service Maps. Refer to [What to expect in {{kib}}](setup.md#what-to-expect-in-kibana) for how these traces appear in the Observability app. ### Known limitations of browser-side traces [traces-limitations] @@ -83,6 +83,6 @@ Automatic capture of `console` methods (for example `console.log`, `console.erro ## Next steps [next-steps] -- Refer to [Set up EDOT Browser](setup.md) for installation and export configuration. +- Refer to [Set up EDOT Browser](setup.md), [Install the agent](install-agent.md), and [Proxy and CORS](proxy-cors.md) for installation and export configuration. - Refer to [What to expect in {{kib}}](setup.md#what-to-expect-in-kibana) for how traces appear in the Observability app. - Refer to [Supported technologies](supported-technologies.md) for included instrumentations and [Configure EDOT Browser](configuration.md) for turning signals and instrumentations on or off. diff --git a/docs/reference/edot-browser/toc.yml b/docs/reference/edot-browser/toc.yml index c1932023..56e6bfa4 100644 --- a/docs/reference/edot-browser/toc.yml +++ b/docs/reference/edot-browser/toc.yml @@ -1,6 +1,9 @@ toc: - file: index.md - file: setup.md + children: + - file: install-agent.md + - file: proxy-cors.md - file: configuration.md - file: telemetry.md - file: supported-technologies.md diff --git a/docs/reference/edot-browser/troubleshooting.md b/docs/reference/edot-browser/troubleshooting.md index a762fb46..59a61c93 100644 --- a/docs/reference/edot-browser/troubleshooting.md +++ b/docs/reference/edot-browser/troubleshooting.md @@ -26,5 +26,5 @@ If you use a Content Security Policy, ensure the proxy or OTLP endpoint domain i ## Next steps [next-steps] - Refer to [Known limitations](supported-technologies.md#known-limitations) for what is not yet supported. -- Refer to [Set up EDOT Browser](setup.md) for installation and initialization. +- Refer to [Set up EDOT Browser](setup.md), [Install the agent](install-agent.md), and [Proxy and CORS](proxy-cors.md) for installation and proxy configuration. - For general OTLP ingest issues, refer to [OpenTelemetry ingest troubleshooting](docs-content://troubleshoot/ingest/opentelemetry/index.md).