作者： 来自 Elastic David Luna
OpenTelemetry 浏览器端埋点分步指南。学习如何在 Web 应用中添加 EDOT Browser，通过 OTLP 导出浏览器遥测数据，并在 Kibana 中验证 traces、spans 和 service maps。
对浏览器进行埋点对于理解用户如何真实体验你的 Web 应用至关重要。它可以让你追踪前端活动，例如页面加载和用户交互，从而实时了解用户遇到的性能问题和异常情况。浏览器埋点将客户端发生的行为与后端服务关联起来，使你能够看到完整的链路，并进行端到端的问题排查。
在浏览器中开始使用 OpenTelemetry 传统上意味着要
你将构建什么？
在本指南中，你将把 EDOT Browser 添加到你的 Web 应用中，并确保它在应用生命周期的早期阶段完成初始化。你还将配置 OTLP 数据的导出路径，并设置一个反向代理来处理身份验证和 CORS。
当你产生浏览器行为时，对应的遥测数据将可以在 Kibana 中查看。你应该能够看到 external.http spans（用于浏览器 fetch 和 XHR 请求）、用户交互 spans（例如 click 和 submit），以及将浏览器活动与后端服务关联起来的完整 traces。所有这些数据都可以在 Kibana 的 Discover 和 Service Maps 中访问。
处理多个依赖项以及复杂的配置。我们构建 EDOT Browser 的目的就是简化这一过程，让你能够以更流畅的方式快速为 Web 应用添加埋点。
虽然 EDOT Browser 目前仍处于技术预览阶段，但在正式发布（GA）之后，它将成为 Elastic 支持的、面向生产环境的 OpenTelemetry Browser SDK 发行版。借助 EDOT Browser，你今天就可以获得更简单的接入方式，并在项目达到 GA 后获得 Elastic 的官方支持。
本指南将介绍一种实用方法：如何将 EDOT Browser 添加到 Web 应用中，将浏览器遥测数据发送到 Elastic，并在 Kibana 中验证结果。
前提条件
在开始之前，请确保你具备以下条件：
- 一个你可以修改的 Web 应用
- 对 Elastic Observability 的访问权限
- 一个 OTLP 目标端点：
- Elastic Managed OTLP，或
- EDOT / OpenTelemetry Collector
- 一个可以配置的反向代理或 Web 服务器层
- 用于 OTLP 目标的 API key 或其他认证机制
重要说明：
- 不要将 API key 直接嵌入浏览器代码中。
- 不要将 EDOT Browser 与其他浏览器 APM 或 RUM agent 一起运行。运行多个浏览器 agent 可能会导致遥测数据重复、埋点冲突或出现不可预期的行为。
架构概览
推荐的生产级流程如下所示：
使用反向代理在该架构中有多个优势。它会在服务端注入 Authorization 头，从而避免在前端代码中暴露凭证。同时，反向代理可以简化跨域资源共享（CORS）的配置，并自动处理预检（preflight）OPTIONS 请求。此外，它还提供了一个天然的位置来实现限流或其他流量控制策略。
分步指南
步骤 1：将 EDOT Browser 添加到你的 Web 应用
在前端项目中安装 EDOT Browser 包。EDOT Browser 是一个单一包，封装了多个 OpenTelemetry 依赖，并为常见的浏览器遥测场景提供了默认配置。
将该 bundle 添加到你的应用中，方式与添加其他前端资源类似。你可以从 GitHub releases 页面下载它。需要的文件包括：
-
elastic-otel-browser.min.js：bundle 文件 -
elastic-otel-browser.min.js.map：source map 文件（用于调试）
注意：EDOT Browser 也以 NPM 包形式发布。具体如何集成取决于你使用的前端框架。更多细节请参考 EDOT Browser 的参考文档。
步骤 2：尽早初始化 EDOT Browser
应尽可能在应用启动的早期初始化 EDOT Browser，以便捕获以下遥测数据：
- document 和页面加载行为
- 用户交互
- 浏览器网络请求
- Core Web Vitals
- 浏览器侧运行时与性能指标
假设你将 bundle 放在 Web 应用的 /assets 路径下，一个简化示例如下：
`
1. <script src="/assets/elastic-otel-browser.min.js"></script>
2. <script>
3. startBrowserSdk({
4. serviceName: 'frontend-web-app',
5. otlpEndpoint: '/otlp',
6. });
7. </script>
8. </html>
`AI写代码
EDOT Browser 的具体初始化 API 和配置项名称应遵循你所使用版本的 EDOT Browser 配置文档，但从概念上讲，你需要提供以下内容：
- 一个 service name
- 一个 OTLP HTTP endpoint
- 你团队希望启用的其他可选配置
尽可能在应用启动流程的最早阶段初始化 EDOT Browser 非常重要。这样可以确保捕获关键的遥测数据，例如初始页面加载、早期用户交互，以及应用加载后立即发生的网络活动。如果初始化延迟，可能会导致这些重要信号丢失。
步骤 3：将浏览器指向代理端点
不要让浏览器直接将遥测数据发送到 Elastic，而是将浏览器 SDK 配置为把 OTLP 流量发送到你自己应用源站上的一个路径，例如 /otlp。这样可以为浏览器提供一个同源（same-origin）端点，并简化 CORS 的处理。
`
1. startBrowserSdk({
2. serviceName: 'frontend-web-app',
3. otlpEndpoint: '/otlp',
4. });
`AI写代码
你的反向代理随后会将 /otlp 转发到 Elastic Managed OTLP 或你的 EDOT / OpenTelemetry Collector。
步骤 4：配置反向代理
你的反向代理需要完成三件事：
- 将 OTLP 请求转发到真实的后端端点（例如 Elastic Managed OTLP 端点）
- 注入 Authorization 头
- 处理 CORS 和预检（preflight）请求（如有需要）
下面是一个 NGINX 风格的配置示例（示意）：
`
1. location /otlp/ {
2. add_header Access-Control-Allow-Origin https://your-app.example.com;
3. add_header Access-Control-Allow-Headers Content-Type,Authorization;
4. add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
5. add_header Access-Control-Allow-Credentials true;
6. if ($request_method = OPTIONS) {
7. return 204;
8. }
9. proxy_pass https://your-otlp-endpoint/;
10. proxy_set_header Authorization "ApiKey YOUR_SERVER_SIDE_KEY";
11. proxy_set_header Host your-otlp-endpoint;
12. proxy_set_header Host $host;
13. proxy_set_header X-Real-IP $remote_addr;
14. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
15. }
`AI写代码
根据你的环境进行调整。
重要安全提示：API key 必须仅保留在服务端。不要将其暴露在 JavaScript bundle、HTML 源码、浏览器开发者工具或任何公开配置文件中。
步骤 5：确保正确处理 CORS
如果你的浏览器应用和 OTLP 目标端点不在同一 origin 下，浏览器可能会因为 CORS 配置不正确而阻止导出请求。
为了确保你的应用与 OTLP 端点之间能够正常通信，你的代理或后端应配置为允许来自应用 origin 的请求。同时需要允许必要的 HTTP headers 和 methods，并正确处理 CORS 所需的预检 OPTIONS 请求。通常情况下，使用同源代理是最简单的方式。
步骤 6：添加一个简单测试页面
为了验证埋点是否正常工作，可以打开或创建一个页面，该页面在浏览器中加载后允许你点击一个按钮，并触发对后端端点的 fetch 请求。下面是一个最小示例：
`
1. <!DOCTYPE html>
2. <html>
3. <head>
4. <title>EDOT Browser Demo</title>
5. <script src="/assets/elastic-otel-browser.min.js"></script>
6. <script>
7. startBrowserSdk({
8. serviceName: 'frontend-web-app',
9. otlpEndpoint: '/otlp',
10. });
11. </script>
12. </head>
13. <body>
14. <h1>EDOT Browser Demo</h1>
15. <button id="loadData">Load data</button>
16. <script type="module">
17. document.getElementById('loadData').addEventListener('click', async () => {
18. const response = await fetch('/api/demo');
19. const data = await response.json();
20. console.log(data);
21. });
22. </script>
23. </body>
24. </html>
`AI写代码
步骤 7：启动应用并生成流量
为了开始生成遥测数据，请启动你的应用并在浏览器中打开它。当应用运行后，加载页面，多次点击按钮，如果你的应用包含多个页面，则在页面之间进行导航。同时执行一些会触发 XHR 或 fetch 请求的操作，以确保埋点能够捕获典型的用户交互。
此时，EDOT Browser 应该已经开始收集并导出遥测数据。
步骤 8：验证浏览器是否正在发送遥测数据
在检查 Kibana 之前，先确认浏览器是否真的在发出 OTLP 请求。打开浏览器开发者工具，并查看 Network（网络）标签。
查找发送到你配置端点的请求，例如：
`
1. /otlp/v1/traces
2. /otlp/v1/metrics
3. /otlp/v1/logs
`AI写代码
在验证浏览器是否正在发送遥测数据时，请确保请求确实发送到了预期的 endpoint。检查响应是否成功，并确认没有 CORS 问题。同时注意是否出现 401 或 403 认证错误，并确保你的代理正确转发 OTLP 流量。如果出现请求失败，通常原因包括 OTLP endpoint 配置错误、代理缺少认证 headers 或 CORS 策略配置不正确。其他常见问题还包括代理路径不匹配，或者 SDK 在应用中初始化过晚或配置不正确。
Kibana 中的浏览器遥测
EDOT Browser 会捕获浏览器端的遥测数据，包括 document 加载事件、用户交互、网络请求以及 Core Web Vitals。在 Kibana 中，这些数据通常会以以下形式呈现：浏览器发起的 spans、分组的交互 spans、关联的前端与后端 traces，以及与浏览器性能相关的指标。
这些信息对于理解前端慢交互、识别 UI 触发的慢后端调用、发现用户可感知的性能问题，以及分析端到端请求行为都非常有帮助。
一旦浏览器遥测数据开始流动，你可以使用 Kibana 中的预置 UI 和 dashboards，或者使用 ES|QL、Dashboard、Alerting 以及其他 Elastic Observability 功能来分析这些数据。
在这个示例中，我们使用了一个非常简单的 Web 应用（play-app）以及一个 Node.js 后端（play-backend）。
Service map 展示了浏览器应用与后端服务之间的依赖关系。
Service overview 页面提供了该服务的高层视图，包括典型的 RED 指标（即 rate、errors、duration），以及应用事件 / transactions 的概览（例如 document load 和 click 事件）。
在 trace waterfall 视图中，你可以看到浏览器请求和后端响应的完整 trace。
除了 APM 视图之外，用户还可以安装 RUM OpenTelemetry 内容包，其中包含一个可直接使用的 dashboard，用于展示浏览器遥测数据和 Web Vitals。
常见排查建议
如果你在 Kibana 中没有看到数据，请检查以下内容：
- SDK 是否已初始化？确认 EDOT Browser 已在页面中正确加载并初始化
- 是否初始化过晚？延迟初始化可能会丢失关键的启动阶段遥测数据
- OTLP endpoint 是否正确？确认浏览器是否发送到了预期的路径
- 代理是否正确转发？确认 proxy 的目标 URL 配置无误
- 是否正确注入认证信息？Managed OTLP 或 Collector 可能需要 Authorization 头
- 是否被 CORS 阻止？检查浏览器控制台或 Network 中是否有跨域错误
- 是否同时运行了其他浏览器 agent？不要将 EDOT Browser 与其他 APM 或 RUM 浏览器 agent 一起使用
需要注意的限制
EDOT Browser 当前不支持以下能力：
- 与传统 Elastic APM 浏览器 agent 的完整功能对等
- 从传统 agent 的迁移工具
如果你正在从传统 Elastic RUM agent 迁移，请做好测试和手动验证的准备。
总结
本文介绍了如何使用 EDOT Browser 对 Web 应用进行埋点，并在 Kibana 中查看相关数据的基础流程。更详细的内容请参考 EDOT Browser 的官方参考文档。
