作者：来自 ElasticDavid 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 的官方支持。

本指南将介绍一种实tgcode用方法：如何将 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 的参考tgcode文档。

步骤 2：尽早初始化 EDOT Browser

应尽可能在应用启动的早期初始化 EDOT Browser，以便捕获以下遥测数据：

• document 和页面加载行为
• 用户交互
• 浏览器网络请求
• Core Web Vitals
• 浏览器侧运行时与tgcode性能指标

假设你将 bundle 放在 Web 应用的 /assets 路径下，一个简化示例如下：

  startBrowserSdk({
    serviceName: 'frontend-web-app',
    otlpEndpoint: '/otlp',
  });