初始化 OpenTelemetry SDK

欢迎回到第 10 章的学习。在上一节，我们安装了 OpenTelemetry Web SDK 依赖。现在我们要初始化 OpenTelemetry SDK，这是前端可观察性的核心配置。

本节将学习：SDK 配置、Resource 配置、Exporter 配置、以及自动插桩配置。

SDK 配置

SDK 配置的作用是什么？ 初始化 OpenTelemetry SDK，配置追踪和指标收集，设置服务名称和版本，准备数据导出。

如何配置 SDK？ 创建 SDK 实例，配置 Resource（服务名称、版本、环境），配置 Exporter（导出端点、协议），配置自动插桩（文档加载、用户交互、网络请求）。

配置步骤：

第一步：创建 SDK 实例。 使用

WebSDK

第二步：配置 Resource。 设置服务名称、服务版本、部署环境等属性。

第三步：配置 Exporter。 设置 OTLP HTTP Exporter，配置 Collector 端点。

第四步：配置自动插桩。 启用文档加载、用户交互、网络请求等自动插桩。

Resource 配置

Resource 配置的作用是什么？ 描述应用程序的元数据，包括服务名称、版本、环境等信息，这些信息会附加到所有的追踪和指标数据中。

Resource 属性包括哪些呢？

第一个：服务名称（service.name）。 应用程序的名称，比如 "shoehub-frontend"，用于识别服务。

第二个：服务版本（service.version）。 应用程序的版本号，比如 "1.0.0"，用于追踪版本变化。

第三个：部署环境（deployment.environment）。 应用程序运行的环境，比如 "production"、"staging"、"development"。

第四个：其他属性。 可以添加自定义属性，比如 "team"、"region" 等。

配置代码：

文件路径：

src/telemetry.js

import { WebSDK } from '@opentelemetry/sdk-web';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
import { OTLPTraceExporter } from '@opentelemetry/exporter-otlp-http';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';
import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
import { registerInstrumentations } from '@opentelemetry/instrumentation';

// Resource provisioning
const resource = Resource.default().merge(
  new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'shoehub-frontend',
    [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'development',
  })
);

// Exporter provisioning
const traceExporter = new OTLPTraceExporter({
  url: 'http://localhost:4318/v1/traces',
  headers: {},
});

// SDK provisioning
const sdk = new WebSDK({
  resource,
  traceExporter,
});

// Automatic staging configuration
registerInstrumentations({
  instrumentations: [
    new DocumentLoadInstrumentation(),
    new UserInteractionInstrumentation(),
    new FetchInstrumentation(),
    new XMLHttpRequestInstrumentation(),
  ],
});

// startup SDK
sdk.start();

export default sdk;

Exporter 配置

Exporter 配置的作用是什么？ 配置数据导出方式，设置 Collector 端点，选择导出协议（HTTP 或 gRPC）。

Exporter 配置包括哪些呢？

第一个：端点配置（endpoint）。 Collector 的 OTLP HTTP 端点，比如 "http://localhost:4318/v1/traces"。

第二个：协议配置（protocol）。 导出协议，HTTP 或 gRPC，前端通常使用 HTTP。

第三个：认证配置（headers）。 如果需要认证，可以配置请求头。

第四个：批处理配置（batchSpanProcessor）。 配置批处理参数，优化导出性能。

自动插桩配置

自动插桩配置的作用是什么？ 自动追踪页面加载、用户交互、网络请求等事件，无需手动添加代码。

自动插桩包括哪些呢？

第一个：文档加载插桩（DocumentLoadInstrumentation）。 追踪页面加载性能，包括 DOMContentLoaded、load 事件。

第二个：用户交互插桩（UserInteractionInstrumentation）。 追踪用户点击、表单提交等交互事件。

第三个：网络请求插桩（FetchInstrumentation、XMLHttpRequestInstrumentation）。 追踪 Fetch API 和 XMLHttpRequest 调用。

第四个：错误捕获插桩（ErrorsInstrumentation）。 自动捕获 JavaScript 错误和 Promise 拒绝。

配置步骤：

第一步：导入插桩包。 导入所需的插桩包。

第二步：创建插桩实例。 使用默认配置或自定义配置创建插桩实例。

第三步：注册插桩。 将插桩实例添加到 SDK 配置中。

第四步：启动 SDK。 调用

start()

在应用入口文件中初始化：

文件路径：

src/index.js

import React from 'react';
import ReactDOM from 'react-dom/client';
import './telemetry'; // import and initialize OpenTelemetry
import App from './App';
import './index.css';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

本节小结

在本节中，我们学习了初始化 OpenTelemetry SDK：

第一个是 SDK 配置。 创建 SDK 实例，配置基本参数，准备数据收集和导出。

第二个是 Resource 配置。 设置服务名称、版本、环境等元数据，附加到所有追踪和指标数据。

第三个是 Exporter 配置。 配置数据导出方式，设置 Collector 端点，选择导出协议。

第四个是自动插桩配置。 启用文档加载、用户交互、网络请求等自动插桩，自动追踪前端事件。

SDK 初始化流程： 创建 SDK 实例 → 配置 Resource → 配置 Exporter → 配置自动插桩 → 启动 SDK → 开始收集数据。

这就是初始化 OpenTelemetry SDK。初始化 SDK 后，我们就可以开始追踪前端应用的性能了。

在下一节，我们将学习自动插桩：页面加载追踪。学习如何追踪页面加载性能。