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.

EventFieldsValues
document.open, openedsizeBucket, 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, rejectedcode, sizeBucket, cause, part, errorName, stagePublic code, reason token, part role, exception class, catch stage.
edit.rejectedcode, origin, tracked, command, cause, errorName, stageorigin is command, input, or automation. command is a built-in name such as insertTable; custom command names are never sent.
review.skippedcode, count, operation, changeKind, formattingKind, part, causeoperation is accept, reject, or reassign. Never the author or the change.
font.failedcodeNever the font family name.
history, custom-nodecodeNever a custom node's name or data.
collab.statusstatus, previous, code, recovering, connectMsNever the room name.
collab.participantscountNever participant names.
performanceinteraction, layout, paint, windowMs, pagesBucket, codeTiming summaries and band counts. No key, character, or position.
document.saveoutcome, sizeBucket, durationMs, code, cause, errorName, stageoutcome is saved or rejected. Never the saved bytes.
sessionphase, durationMs, activeMs, inputEdits, commandEdits, automationEditsphase 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 as TypeError. Counts become buckets such as 10-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

DataRiskControl
editorSessionIdRandom 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 eventsShow 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.
shapeOff 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 labelsValues 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, resourceStrings 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.

See also