Measure sessions, edits, and saves
Count editor sessions, active editing time, edits, edit failure rates, and saves.
@docx-editor.dev/telemetry is available in version 2.29.0 and later.The sessions and documentSave areas send counts and milliseconds only. They never send keys, positions, command arguments, or document text.
Enable session and save telemetry
If you omit include, every area is on. If you set it, list sessions and documentSave:
import { createTelemetry } from '@docx-editor.dev/telemetry';
import { otelExporter } from '@docx-editor.dev/telemetry/otel';
export const telemetry = createTelemetry({
exporters: [otelExporter()],
include: {
documentOpen: true,
documentSave: true,
editing: true,
sessions: { sampleRate: 0.2 },
},
});sampleRate for sessions selects editors, not events. A sampled editor sends its whole session; other editors send none of it. Metrics count every session at any rate.
Interpret session events
A session is one editor instance, from creation to end. It is not a unique person: a reload creates a new editor and a new session. Every event of one session has the same editorSessionId.
phase | When | Fields |
|---|---|---|
start | The editor was created. | Common fields only. |
active | A window of use ended: a minute after its first activity, when the page became hidden, or before end. An idle editor sends none. | durationMs, activeMs, inputEdits, commandEdits, automationEdits for the window. |
end | The editor was destroyed, or its page closed. | The same fields as session totals. durationMs runs from creation to end, idle time included. |
The end totals include every active summary. Never add active summaries to end totals.
Count edits and active time
An edit is a change that this editor committed to the document.
| Field | Counts |
|---|---|
activeMs | Time between key presses, pointer presses, and edits at most 30 seconds apart. A longer gap counts as idle. |
inputEdits | Typing, clipboard, drag and drop, keyboard undo and redo. Characters typed faster than the editor paints count once. |
commandEdits | Commands from exec(...) or the toolbar, including undo and redo. One count per command. |
automationEdits | Editing API batches. One count per batch. |
- Refused edits are not edits. The editor reports them as
edit.rejected. - Remote edits do not count as local edits. Each collaborator's editor counts its own.
- An action that changes nothing, such as redo with nothing to redo, does not count.
Edit failure rate is refused edits divided by edits plus refused edits. Compute it from metrics, not events, because events are deduplicated and sampled. For metric names, see Metrics.
Interpret save results
Each save() call sends one document.save event:
outcome | code | Fields |
|---|---|---|
saved | None | sizeBucket, durationMs from the call to the bytes, pending edits included. |
rejected | save.no-document: no document was loaded. | durationMs |
rejected | save.document-changed: another document loaded while the save waited. | durationMs |
rejected | save.failed: the save threw. | durationMs, cause, errorName, stage. Never the error message. |
With OpenTelemetry, a save is a span named docx_editor.document.save. With Sentry, save.failed becomes an issue.
Limits
- Save timing excludes your application's upload. Measure the upload in your app.
- Edit and active-time metrics arrive with each
activesummary, up to a minute after the edit. - Crashed tabs can omit
end. Theiractivesummaries still count. - On page close, the editor sends its last
activesummary andendbefore otherpagehidelisteners run. Your SDK's ownpagehideflush still works.