Privacy
Review the fields that built-in telemetry events contain and the checks that keep document content out.
@docx-editor.dev/telemetry is available in version 2.29.0 and later.Built-in diagnostics and metrics contain no document-derived strings. This guarantee covers the payloads the engine builds. It does not cover attributes you add or data your Sentry and OpenTelemetry SDKs collect.
The package sends data only through exporters you configure.
Inspect exported fields
Every event has kind, schemaVersion, editorSessionId, and time. The telemetry package adds engineVersion.
| Event | Fields | Values |
|---|---|---|
document.open, opened | sizeBucket, pagesBucket, durationMs, shape (opt-in) | Size in 15 power-of-two buckets, such as 1-2MiB. Pages: 0, 1, 2-9, 10-99, 100-999, 1000+. |
document.open, rejected | code, sizeBucket, cause, part, errorName, stage | Public code, reason token, part role, exception class, catch stage. |
edit.rejected | code, origin, tracked, command, cause, errorName, stage | origin is command, input, or automation. command is a built-in name such as insertTable; custom command names are never sent. |
review.skipped | code, count, operation, changeKind, formattingKind, part, cause | operation is accept, reject, or reassign. Never the author or the change. |
font.failed | code | Never the font family name. |
history, custom-node | code | Never a custom node's name or data. |
collab.status | status, previous, code, recovering, connectMs | Never the room name. |
collab.participants | count | Never participant names. |
performance | interaction, layout, paint, windowMs, pagesBucket, code | Timing summaries and band counts. No key, character, or position. |
document.save | outcome, sizeBucket, durationMs, code, cause, errorName, stage | outcome is saved or rejected. Never the saved bytes. |
session | phase, durationMs, activeMs, inputEdits, commandEdits, automationEdits | phase is start, active, or end. No key, position, command argument, or text. |
Never sent: document text, file names, part names, relationship targets, author names, comment text, font names, file-defined element names, and exception messages.
Every closed list is public API. Read them with diagnosticCodes() and diagnosticCauses() from @docx-editor.dev/core. For field meanings, see Diagnostics.
Understand validation
- The engine builds events from closed lists. Part names become roles such as
header. Exceptions become classes such asTypeError. Counts become buckets such as10-99. - Internal refusal messages map to public codes. The messages stay in the engine because they can describe content.
- The telemetry package checks every event again before export. It removes string fields outside their allowed lists.
- Events with unknown kinds or codes are dropped and counted in
docx_editor_telemetry_dropped_events_total. This protects mixed engine and telemetry versions. - Tests plant text, part names, and author names in files, then fail if any serialized event contains them.
Review linkable data
| Data | Risk | Control |
|---|---|---|
editorSessionId | Random per editor instance, not persisted. Linkable to a person when you send it with your own user ID. | Leave user IDs out of attributes. |
session events | Show when and how long an editor is used. With a user ID, they show when that person works. | Sample or turn off the sessions area. |
shape | Off by default. documentShape: 'detailed' adds buckets for XML parts, paragraphs, review items, and embedded fonts. Rare combinations can distinguish documents. No option sends exact counts. | Keep documentShape: 'basic'. |
| Metric labels | Values must match [A-Za-z0-9_.:+-]{0,64}, or they become other. Each metricLabels key keeps at most 50 distinct values. | List only low-cardinality keys. See Metrics. |
attributes, resource | Strings you supply. | See Identify rooms and users. |
Limits
- Validation checks structure. It does not prove anonymity or that an event is authentic.
- Your Sentry and OpenTelemetry SDKs collect data outside this contract.
- Collaboration server metrics never carry room names. For room labels and
rooms.list(), see Rooms, people, and memory.