Skip to content

Commit b08bd78

Browse files
chluknight1224chluknight1224
committed
PR20251113 Add zh-lang-js-*.md
1 parent 0ed8382 commit b08bd78

File tree

1 file changed

+247
-0
lines changed
  • content/zh/docs/languages/js/getting-started

1 file changed

+247
-0
lines changed

‎content/zh/docs/languages/js/getting-started/browser.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
title: 浏览器
3+
aliases: [/docs/js/getting_started/browser]
4+
description: 了解如何为您的浏览器应用添加 OpenTelemetry
5+
default_lang_commit: 4c9af5912f276b79a489a10b44c53f720c7927d7
6+
weight: 20
7+
---
8+
9+
{{% include browser-instrumentation-warning.md %}}
10+
11+
尽管本指南使用下述示例应用，您也可以将这些步骤应用于您自己的应用。
12+
13+
## 前置条件 {#prerequisites}
14+
15+
请确保您已在本地安装以下内容：
16+
17+
- [Node.js](https://nodejs.org/en/download/)
18+
- [TypeScript](https://www.typescriptlang.org/download)，如果您将使用 TypeScript。
19+
20+
## 示例应用 {#example-application}
21+
22+
这是一个非常简单的指南，如果您想查看更复杂的示例，请访问
23+
[examples/opentelemetry-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/opentelemetry-web)。
24+
25+
将以下文件复制到空目录中，并将其命名为 `index.html`。
26+
27+
```html
28+
<!doctype html>
29+
<html lang="en">
30+
<head>
31+
<meta charset="utf-8" />
32+
<title>Document Load Instrumentation Example</title>
33+
<base href="/" />
34+
<!--
35+
https://www.w3.org/TR/trace-context/
36+
在服务器的 HTML 模板代码中设置 `traceparent`。
37+
它应在服务器端动态生成，包含服务器的请求跟踪 ID、在服务器请求 Span 上设置的父 Span ID，
38+
以及用于指示服务器采样决策的跟踪标志（01 表示已采样，00 表示未采样）。
39+
格式为：{version}-{traceId}-{spanId}-{sampleDecision}
40+
-->
41+
<meta
42+
name="traceparent"
43+
content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01"
44+
/>
45+
<meta name="viewport" content="width=device-width, initial-scale=1" />
46+
</head>
47+
<body>
48+
使用 Web Tracer 进行文档加载插桩的示例，包含控制台导出器和收集器导出器。
49+
</body>
50+
</html>
51+
```
52+
53+
### 安装 {#installation}
54+
55+
要在浏览器中创建链路，您需要 `@opentelemetry/sdk-trace-web` 和 `@opentelemetry/instrumentation-document-load` 插桩库：
56+
57+
```shell
58+
npm init -y
59+
npm install @opentelemetry/api \
60+
@opentelemetry/sdk-trace-web \
61+
@opentelemetry/instrumentation-document-load \
62+
@opentelemetry/context-zone
63+
```
64+
65+
### 初始化与配置 {#initialization-and-configuration}
66+
67+
如果您使用 TypeScript 编写应用，您需要运行以下命令：
68+
69+
```shell
70+
tsc --init
71+
```
72+
73+
然后获取 [parcel](https://parceljs.org/)，它（除其他功能外）可让你使用 TypeScript 进行开发。
74+
75+
```shell
76+
npm install --save-dev parcel
77+
```
78+
79+
根据你选择的应用开发语言，创建一个名为 `document-load` 的空代码文件，扩展名为 `.ts` 或 `.js`。
80+
在 HTML 中 `</body>` 结束标签前添加以下代码：
81+
82+
{{< tabpane text=true >}} {{% tab TypeScript %}}
83+
84+
```html
85+
<script type="module" src="document-load.ts"></script>
86+
```
87+
88+
{{% /tab %}} {{% tab JavaScript %}}
89+
90+
```html
91+
<script type="module" src="document-load.js"></script>
92+
```
93+
94+
{{% /tab %}} {{< /tabpane >}}
95+
96+
我们将添加一些代码来追踪文档加载时间，并将其作为 OpenTelemetry Span 输出。
97+
98+
### 创建一个 Tracer 提供器 {#creating-a-tracer-provider}
99+
100+
在 `document-load.ts|js` 中添加以下代码以创建一个 tracer 提供器，该提供器会引入用于追踪文档加载的插桩功能：
101+
102+
```js
103+
/* document-load.ts|js 文件（此代码片段在两种语言中是相同的）*/
104+
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
105+
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
106+
import { ZoneContextManager } from '@opentelemetry/context-zone';
107+
import { registerInstrumentations } from '@opentelemetry/instrumentation';
108+
109+
const provider = new WebTracerProvider();
110+
111+
provider.register({
112+
// 将默认的 contextManager 更改为使用 ZoneContextManager（支持异步操作，可选）
113+
contextManager: new ZoneContextManager(),
114+
});
115+
116+
// 注册插桩
117+
registerInstrumentations({
118+
instrumentations: [new DocumentLoadInstrumentation()],
119+
});
120+
```
121+
122+
现在使用 parcel 构建应用：
123+
124+
```shell
125+
npx parcel index.html
126+
```
127+
128+
然后打开开发 Web 服务器（例如在 `http://localhost:1234`）以查看代码是否工作。
129+
130+
如果一切正常，你应该在浏览器的开发者工具控制台中看到一些链路数据。
131+
132+
### 创建一个导出器 {#creating-an-exporter}
133+
134+
在以下示例中，我们将使用 `ConsoleSpanExporter`，它会将所有 Span 打印到控制台。
135+
136+
为了可视化和分析您的链路，您需要将它们导出到链路后端。请按照[这些说明](../../exporters)设置后端和导出器。
137+
138+
您可能还想使用 `BatchSpanProcessor` 批量导出 Span，以更有效地利用资源。
139+
140+
要将链路导出到控制台，请修改 `document-load.ts|js` 使其与以下代码片段匹配：
141+
142+
```js
143+
/* document-load.ts|js 文件（此代码片段在两种语言中是相同的）*/
144+
import {
145+
ConsoleSpanExporter,
146+
SimpleSpanProcessor,
147+
} from '@opentelemetry/sdk-trace-base';
148+
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
149+
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
150+
import { ZoneContextManager } from '@opentelemetry/context-zone';
151+
import { registerInstrumentations } from '@opentelemetry/instrumentation';
152+
153+
const provider = new WebTracerProvider({
154+
spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
155+
});
156+
157+
provider.register({
158+
// 将默认的 contextManager 更改为使用 ZoneContextManager（支持异步操作，可选）
159+
contextManager: new ZoneContextManager(),
160+
});
161+
162+
// 注册插桩
163+
registerInstrumentations({
164+
instrumentations: [new DocumentLoadInstrumentation()],
165+
});
166+
```
167+
168+
现在，重新构建您的应用程序并再次打开浏览器。在开发者工具的控制台中，您应该会看到一些被导出的链路：
169+
170+
```json
171+
{
172+
"traceId": "ab42124a3c573678d4d8b21ba52df3bf",
173+
"parentId": "cfb565047957cb0d",
174+
"name": "documentFetch",
175+
"id": "5123fc802ffb5255",
176+
"kind": 0,
177+
"timestamp": 1606814247811266,
178+
"duration": 9390,
179+
"attributes": {
180+
"component": "document-load",
181+
"http.response_content_length": 905
182+
},
183+
"status": {
184+
"code": 0
185+
},
186+
"events": [
187+
{
188+
"name": "fetchStart",
189+
"time": [1606814247, 811266158]
190+
},
191+
{
192+
"name": "domainLookupStart",
193+
"time": [1606814247, 811266158]
194+
},
195+
{
196+
"name": "domainLookupEnd",
197+
"time": [1606814247, 811266158]
198+
},
199+
{
200+
"name": "connectStart",
201+
"time": [1606814247, 811266158]
202+
},
203+
{
204+
"name": "connectEnd",
205+
"time": [1606814247, 811266158]
206+
},
207+
{
208+
"name": "requestStart",
209+
"time": [1606814247, 819101158]
210+
},
211+
{
212+
"name": "responseStart",
213+
"time": [1606814247, 819791158]
214+
},
215+
{
216+
"name": "responseEnd",
217+
"time": [1606814247, 820656158]
218+
}
219+
]
220+
}
221+
```
222+
223+
### 添加插桩 {#add-instrumentations}
224+
225+
如果您想要对 Ajax 请求、用户交互等进行插桩，您可以添加额外的插桩库并注册它们：
226+
227+
```sh
228+
npm install @opentelemetry/instrumentation-user-interaction \
229+
@opentelemetry/instrumentation-xml-http-request \
230+
```
231+
232+
```javascript
233+
import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';
234+
import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';
235+
236+
registerInstrumentations({
237+
instrumentations: [
238+
new DocumentLoadInstrumentation(),
239+
new UserInteractionInstrumentation(),
240+
new XMLHttpRequestInstrumentation(),
241+
],
242+
});
243+
```
244+
245+
## Web 基础包 {#meta-packages-for-web}
246+
247+
若要一次性利用最常见的插桩功能，您只需使用 [OpenTelemetry Web 基础包](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-web)。

0 commit comments

Comments
 (0)