浏览器

学习如何将 OpenTelemetry 添加到您的浏览器应用程序中

警告

Client instrumentation for the browser is experimental and mostly unspecified. If you are interested in helping out, get in touch with the Client Instrumentation SIG.

尽管本指南使用了下面介绍的示例应用程序，但您自己应用程序的操作步骤应该是类似的。

先决条件

请确保本地已安装以下内容：

Node.js
TypeScript，如果您将使用 TypeScript。

示例应用程序

这是一个非常简单的指南，如果您想查看更复杂的示例，请转到 examples/opentelemetry-web。

将以下文件复制到一个空目录中，并将其命名为 index.html。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>文档加载仪表化示例</title>
    <base href="/" />
    <!--
      https://www.w3.org/TR/trace-context/
      在服务器的 HTML 模板代码中设置 `traceparent`。它应该是动态生成的，以具有服务器请求的跟踪 ID、在服务器请求跨度上设置的父跨度 ID 和用于指示服务器的采样决策的跟踪标志
      (01 = 采样，00 = 不采样)。
      '{版本}-{跟踪 ID}-{跨度 ID}-{采样决策}'
    -->
    <meta
      name="traceparent"
      content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01"
    />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    通过控制台导出器和集合器导出器示例，使用 Web Tracer 和文档加载仪表进行示例
  </body>
</html>

安装

要在浏览器中创建跟踪，您需要使用 @opentelemetry/sdk-trace-web 和 @opentelemetry/instrumentation-document-load：

npm init -y
npm install @opentelemetry/api \
  @opentelemetry/sdk-trace-web \
  @opentelemetry/instrumentation-document-load \
  @opentelemetry/context-zone

初始化和配置

如果您使用 TypeScript 编写代码，则运行以下命令：

tsc --init

然后获取 parcel，它将（除其他外）让您在 TypeScript 中工作。

npm install --save-dev parcel

创建一个名为 document-load 的空代码文件，具有适合您选择的语言的 .ts 或 .js 扩展名。在 </body> 结束标记之前，将以下代码添加到您的 HTML 中：

<script type="module" src="document-load.ts"></script>

<script type="module" src="document-load.js"></script>

我们将添加一些代码，用于跟踪文档加载时间并将其作为 OpenTelemetry 跨度输出。

创建跟踪器提供程序

在 document-load.ts|js 中添加以下代码以创建跟踪器提供程序，该提供程序将文档加载仪表带到跟踪文档加载：

/* document-load.ts|js 文件 - 两种语言都使用相同的代码片段 */
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { registerInstrumentations } from '@opentelemetry/instrumentation';

const provider = new WebTracerProvider();

provider.register({
  // 将默认上下文管理器更改为使用 ZoneContextManager - 支持异步操作 - 可选
  contextManager: new ZoneContextManager(),
});

// 注册仪表
registerInstrumentations({
  instrumentations: [new DocumentLoadInstrumentation()],
});

现在使用 parcel 构建应用程序：

npx parcel index.html

并打开开发 Web 服务器（例如在 http://localhost:1234）以查看您的代码是否正常工作。

目前还没有导出跟踪的输出，我们需要添加一个导出器。

创建导出器

在下面的示例中，我们将使用 ConsoleSpanExporter 将所有跨度打印到控制台。

为了可视化和分析您的跟踪，您需要将它们导出到跟踪后端。请按照这些说明设置后端和导出器。

为了更有效地使用资源，您可能还想使用 BatchSpanProcessor 批量导出跨度。

要将跟踪导出到控制台，请修改 document-load.ts|js，使其与以下代码片段匹配：

/* document-load.ts|js 文件 - 两种语言都使用相同的代码 */
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-base';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { registerInstrumentations } from '@opentelemetry/instrumentation';

const provider = new WebTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));

provider.register({
  // 将默认上下文管理器更改为使用 ZoneContextManager - 支持异步操作 - 可选
  contextManager: new ZoneContextManager(),
});

// 注册仪表
registerInstrumentations({
  instrumentations: [new DocumentLoadInstrumentation()],
});

现在，重新构建您的应用程序，并再次打开浏览器。在开发者工具栏的控制台中，您应该看到一些跟踪正在被导出：

{
  "traceId": "ab42124a3c573678d4d8b21ba52df3bf",
  "parentId": "cfb565047957cb0d",
  "name": "documentFetch",
  "id": "5123fc802ffb5255",
  "kind": 0,
  "timestamp": 1606814247811266,
  "duration": 9390,
  "attributes": {
    "component": "document-load",
    "http.response_content_length": 905
  },
  "status": {
    "code": 0
  },
  "events": [
    {
      "name": "fetchStart",
      "time": [1606814247, 811266158]
    },
    {
      "name": "domainLookupStart",
      "time": [1606814247, 811266158]
    },
    {
      "name": "domainLookupEnd",
      "time": [1606814247, 811266158]
    },
    {
      "name": "connectStart",
      "time": [1606814247, 811266158]
    },
    {
      "name": "connectEnd",
      "time": [1606814247, 811266158]
    },
    {
      "name": "requestStart",
      "time": [1606814247, 819101158]
    },
    {
      "name": "responseStart",
      "time": [1606814247, 819791158]
    },
    {
      "name": "responseEnd",
      "time": [1606814247, 820656158]
    }
  ]
}

添加仪表

如果您想要仪表化 Ajax 请求、用户交互和其他操作，可以为这些操作注册其他仪表：

registerInstrumentations({
  instrumentations: [
    new UserInteractionInstrumentation(),
    new XMLHttpRequestInstrumentation(),
  ],
});

Web 的元软件包

要在一个简单的方式中利用最常见的仪表化，请直接使用 OpenTelemetry Web 的元软件包

最后修改 December 13, 2023: improve glossary translation (46f8201b)