# @docx-editor\.dev/telemetry 中文文档

规范地址：https://npmcn.com/package/%40docx-editor.dev/telemetry/

版本：2\.38\.0
npm 元数据更新时间：2026-11-16T13:49:22.690Z
中文译文更新时间：2026-11-16T13:57:23.130Z
软件包许可：LicenseRef-EigenPal-Pro-Evaluation-1\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40docx-editor.dev/telemetry
原文对照：https://npmcn.com/package/%40docx-editor.dev/telemetry/?lang=original
项目主页：https://docx-editor.dev/
源码仓库：https://github.com/eigenpal/docx-editor

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：238 kB，48 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：yjs ^13\.6\.32，@hocuspocus/server ^4\.6\.0，@opentelemetry/api ^1\.9\.0，@docx-editor\.dev/pro ~2\.38\.0，@docx-editor\.dev/core ~2\.38\.0
- 首次发布：2026-10-13T11:34:52.374Z
- 最新版本发布：2026-11-16T13:49:22.124Z
- 近 30 天下载量：3457（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

@docx-editor的匿名诊断、衡量和错误报告。 dev编辑和协作服务器,与OpenTeleometter,Prometheus,和哨兵出口商合作.

## 安装

```sh
npm install @docx-editor.dev/telemetry
```

也可以使用：`pnpm add @docx-editor.dev/telemetry`、`yarn add @docx-editor.dev/telemetry`、`bun add @docx-editor.dev/telemetry`

## README

# @docx-editor.dev/遥测

匿名诊断、计量和错误报告 `@docx-editor.dev` 编辑和协作服务器。 把他们送到OpenTeleometry,普罗米修斯,哨兵,或者你自己的日志机.

内置诊断包含代码,布尔克,桶大小和计数,以及计时. 它们不包括文件文本、文件名称、作者姓名、字体名称和房间名称。 您控制您添加的任何属性以及您所收集的SDK监控数据。 软件包只通过您配置的导出者发送数据 .

## 安装软件包

该套装版本为2.29.0及后.

```sh
npm install @docx-editor.dev/telemetry @docx-editor.dev/core
```

添加 `@opentelemetry/api` 或者说 `@hocuspocus/server` 只针对您使用的导出者和服务器集成。 哨兵出口商拿走了哨兵SDK 你的应用程序已经装入了.

## 编辑器

```ts
import { createTelemetry } from '@docx-editor.dev/telemetry';
import { otelExporter } from '@docx-editor.dev/telemetry/otel';
import { sentryExporter } from '@docx-editor.dev/telemetry/sentry';
import * as Sentry from '@sentry/react';

export const telemetry = createTelemetry({
  // Sentry for failures, OpenTelemetry for metrics such as typing delay.
  exporters: [sentryExporter(Sentry), otelExporter()],
  include: {
    documentOpen: true,
    documentSave: true,
    trackedChanges: true,
    editing: true,
    performance: true,
    sessions: true,
  },
  consent: () => consentManager.analytics === true, // your consent manager
});

// Outside your component, so the array is stable across renders:
export const MODULES = [telemetry.module];
// <DocxEditor document={bytes} modules={MODULES} />
```

使用 `consoleExporter()` 在开发过程中查看诊断。 例如,以下诊断解释了编辑API为何拒绝履带图片删除:

```text
[docx-editor] edit refused: edit.tracked-operation-unsupported (automation, tracked)
  This editing API operation cannot be recorded as a tracked change, so nothing was applied. Use text edits such as range.insertText or range.delete, which tracking records. Never switch tracking off to make the edit succeed.
  https://docx-editor.dev/docs/2.x/guides/diagnostics#edit-tracked-operation-unsupported
```

这个 `performance` 区域测量键入延迟、引擎布局和油漆时间。 发送给记录度量衡的出口商,例如: `otelExporter()`。哨兵出口商只将性能记录为面包屑.

这个 `sessions` 区域计数编辑器会话,活动编辑时间,并按来源进行编辑,因此可以计算编辑失败率。 这个 `documentSave` 各报告 `save()` 与结果和期限一致。 查询和仪表板,见 [测量会话、编辑和保存](https://docx-editor.dev/docs/2.x/telemetry/sessions)。 。 。 .

## 协作服务器

```ts
import { Server } from '@hocuspocus/server';
import { withCollaborationTelemetry } from '@docx-editor.dev/telemetry/hocuspocus';
import { metricsHandler, prometheusRegistry } from '@docx-editor.dev/telemetry/prometheus';

const metrics = prometheusRegistry();
const { config, rooms } = withCollaborationTelemetry(
  { port: 1234, onAuthenticate, onLoadDocument, onStoreDocument },
  { exporters: [metrics] }
);
new Server(config);

app.get('/metrics', metricsHandler(metrics));
app.get('/admin/rooms', requireAdmin, (_request, response) => response.json(rooms.list()));
```

用于其他 Yjs 服务器 `roomTelemetry` 从 `@docx-editor.dev/telemetry/server`。 。 。 .

## 盘子

Grafana仪表板显示编辑器输入延迟,引擎计时,文档打开,并拒绝编辑. 他们还展示合作室,人,记忆,以及拒绝.

![The Editor experience dashboard: input delay median and 95th percentile, presses over 1 second, opens succeeding, open time, metric sources reporting, unexpected refusals, and charts of input delay over time, by delay band, and by document size.](https://raw.githubusercontent.com/eigenpal/docx-editor/main/docs/site/content/telemetry/images/editor-experience.png)

下载 [`editor-experience.json`](https://raw.githubusercontent.com/eigenpal/docx-editor/main/assets/observability/grafana/editor-experience.json) 财务报告和审定财务报表 [`collaboration.json`](https://raw.githubusercontent.com/eigenpal/docx-editor/main/assets/observability/grafana/collaboration.json),然后将它们导入Grafana。 关于每个人的设置,见 [盘子](https://docx-editor.dev/docs/2.x/telemetry/dashboards)。 。 。 .

## 入境点

| 条目 | 目录 |
| --- | --- |
| `@docx-editor.dev/telemetry` | `createTelemetry`, (中文(简体) ), `consoleExporter`, (中文(简体) ), `callbackExporter`, (中文(简体) ), `memoryExporter`, (中文(简体) ), `isFailure`, (中文(简体) ), `failureCount`, (中文(简体) ), `explainDiagnostic`,参数目录 |
| `@docx-editor.dev/telemetry/otel` | `otelExporter`,通过您的 OpenTeleometry SDK |
| `@docx-editor.dev/telemetry/sentry` | `sentryExporter`, (中文(简体) ), `dropEditorBreadcrumbs`, (中文(简体) ), `EDITOR_SELECTORS` |
| `@docx-editor.dev/telemetry/prometheus` | `prometheusRegistry`, (中文(简体) ), `metricsHandler`, (中文(简体) ), `fetchMetricsHandler`,用于服务器进程。 浏览器参数通过 `otelExporter()` 和一个开放的远程采集器. |
| `@docx-editor.dev/telemetry/server` | `roomTelemetry`, (中文(简体) ), `hmacRoomLabel` |
| `@docx-editor.dev/telemetry/hocuspocus` | `withCollaborationTelemetry`, (中文(简体) ), `serveMetrics`, (中文(简体) ), `requireBearerToken`, (中文(简体) ), `hmacRoomLabel` |

关于完整的指南,见: [遥测](https://docx-editor.dev/docs/2.x/telemetry)。 。 。 .

## 许可证

EigenPal Pro 许可证。 见 [利比里亚](https://npmcn.com/package/%40docx-editor.dev/telemetry/LICENSE.md)。 。 。 .

## 常见问题

### @docx-editor\.dev/telemetry 是什么？

@docx-editor的匿名诊断、衡量和错误报告。 dev编辑和协作服务器,与OpenTeleometter,Prometheus,和哨兵出口商合作\.

### 如何安装 @docx-editor\.dev/telemetry？

在项目目录运行 npm install @docx-editor\.dev/telemetry，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@docx-editor\.dev/core（~2\.38\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @docx-editor\.dev/telemetry 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @docx-editor\.dev/telemetry 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @docx-editor\.dev/telemetry 可以商用吗？

@docx-editor\.dev/telemetry 使用 LicenseRef-EigenPal-Pro-Evaluation-1\.0 许可。声明的许可为 LicenseRef-EigenPal-Pro-Evaluation-1\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @docx-editor\.dev/telemetry 的下载量有多少？

根据 npm 官方下载统计，@docx-editor\.dev/telemetry 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,457 次，日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @docx-editor\.dev/telemetry 还在维护吗？

最新版本 2\.38\.0 发布于 2026/11/16（今天）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

