@docx-editor.dev/telemetry

中文文档
2.38.0发布于 2026/11/16LicenseRef-EigenPal-Pro-Evaluation-1.0TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 3457

Anonymous diagnostics, metrics, and error reporting for @docx-editor.dev editors and collaboration servers, with OpenTelemetry, Prometheus, and Sentry exporters.

原始使用文档
文档目录6 节
  1. Install the package
  2. Editors
  3. Collaboration servers
  4. Dashboards
  5. Entry points
  6. License

@docx-editor.dev/telemetry

Anonymous diagnostics, metrics, and error reporting for @docx-editor.dev editors and collaboration servers. Send them to OpenTelemetry, Prometheus, Sentry, or your own logger.

Built-in diagnostics contain codes, booleans, bucketed sizes and counts, and timings. They exclude document text, file names, author names, font names, and room names. You control any attributes you add and any data your monitoring SDKs collect. The package sends data only through exporters you configure.

Install the package

The package is available in version 2.29.0 and later.

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

Add @opentelemetry/api or @hocuspocus/server only for the exporters and server integrations that you use. The Sentry exporter takes the Sentry SDK your app already loads.

Editors

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} />

Use consoleExporter() to view diagnostics during development. For example, the following diagnostic explains why the editing API refused a tracked picture deletion:

[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

The performance area measures typing delay and engine layout and paint times. Send it to an exporter that records metrics, such as otelExporter(). The Sentry exporter records performance only as breadcrumbs.

The sessions area counts editor sessions, active editing time, and edits by origin, so you can compute edit failure rates. The documentSave area reports each save() call with its outcome and duration. For queries and dashboards, see Measure sessions, edits, and saves.

Collaboration servers

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()));

For other Yjs servers, use roomTelemetry from @docx-editor.dev/telemetry/server.

Dashboards

Grafana dashboards show editor input delay, engine timings, document opens, and refused edits. They also show collaboration rooms, people, memory, and refusals.

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.

Download editor-experience.json and collaboration.json, then import them into Grafana. For the setup each one needs, see Dashboards.

Entry points

EntryContents
@docx-editor.dev/telemetrycreateTelemetry, consoleExporter, callbackExporter, memoryExporter, isFailure, failureCount, explainDiagnostic, the metric catalog
@docx-editor.dev/telemetry/otelotelExporter, through your OpenTelemetry SDK
@docx-editor.dev/telemetry/sentrysentryExporter, dropEditorBreadcrumbs, EDITOR_SELECTORS
@docx-editor.dev/telemetry/prometheusprometheusRegistry, metricsHandler, fetchMetricsHandler, for server processes. Browser metrics go through otelExporter() and an OpenTelemetry collector.
@docx-editor.dev/telemetry/serverroomTelemetry, hmacRoomLabel
@docx-editor.dev/telemetry/hocuspocuswithCollaborationTelemetry, serveMetrics, requireBearerToken, hmacRoomLabel

For the full guide, see Telemetry.

License

EigenPal Pro License. See LICENSE.md.

版本与发布记录

@docx-editor.dev/telemetry 共发布 24 个版本,首次发布于 2026/10/13;过去 12 个月发布了 24 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.38.0latest2026/11/16今天
2.38.0-canary.20261116033356.sha-2662bd1canary2026/11/16今天
2.38.0-canary.20261115032819.sha-05856f62026/11/151 天前
2.38.0-canary.20261114032659.sha-cdc64af2026/11/142 天前
2.38.0-canary.20261113032851.sha-e2cbc552026/11/133 天前
2.37.02026/11/115 天前

关于 @docx-editor.dev/telemetry 的常见问题

@docx-editor.dev/telemetry 是什么?

Anonymous diagnostics, metrics, and error reporting for @docx-editor.dev editors and collaboration servers, with OpenTelemetry, Prometheus, and Sentry exporters.

如何安装 @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 和提交记录判断。