Set up an editor

Create one telemetry client, register its module in the editor, and choose what it records. To install the package, see Telemetry. For data collection details, see Privacy.

Register the module

Create the telemetry client once, outside your components, and register its module. Registration lets the module receive diagnostics from the first document the editor opens.

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

export const telemetry = createTelemetry({
  exporters: [sentryExporter(Sentry)],
  include: { documentOpen: true, trackedChanges: true, editing: true },
  consent: () => consentManager.analytics === true, // your consent manager
  resource: { 'service.name': 'contracts-app' },
});

// Editor.tsx
import { DocxEditor } from '@docx-editor.dev/react';
import { reviewModule } from '@docx-editor.dev/pro';
import { telemetry } from './telemetry';

const MODULES = [reviewModule(), telemetry.module];

export function Editor({ bytes }: { bytes: Uint8Array }) {
  return <DocxEditor document={bytes} modules={MODULES} />;
}

In Vue, register the same module:

<script setup lang="ts">
import { DocxEditor } from '@docx-editor.dev/vue';
import { reviewModule } from '@docx-editor.dev/pro';
import { telemetry } from './telemetry';

defineProps<{ bytes: Uint8Array }>();
const MODULES = [reviewModule(), telemetry.module];
</script>

<template>
  <DocxEditor :document="bytes" :modules="MODULES" />
</template>

Control consent

When consent returns false, the editor drops new events without buffering them. Your OpenTelemetry SDK can still export metrics it recorded earlier. Apply the same consent choice to your Sentry and OpenTelemetry SDKs through their own settings. If you omit consent, the client sends events.

The client checks consent when it records an event. With performance enabled, it also checks each timed key press, layout, and paint. Keep the function fast: read a value that your consent manager stores in memory. The function never runs during server rendering, so you can create the client there.

The check applies to every exporter, including the console exporter. To allow all exporters in local builds, use consent: () => import.meta.env.DEV || consentManager.analytics === true.

Choose what to record

Register telemetry.module or call telemetry.record(event) yourself. Using both records each event twice.

Use include to choose telemetry areas. If you omit it, all areas are enabled. If you set it, list every area you want to enable, including areas that use default options.

Each area accepts { sampleRate }, from 0 to 1. Sampling applies to events only; metrics count every event. The one exception is performance: a rate of 0 turns it off, metrics included.

The areas whose failures can become Sentry issues are documentOpen, editing, trackedChanges, fonts, and collaborationClient. For the rule, see Send to Sentry.

By default, document-open events include size and page buckets. Set documentShape: 'detailed' to include part, paragraph, review item, and embedded font buckets. Combined counts reveal more about a document, so enable this option only when you need it.

The client sends identical refusals once within each 10-second window. When the window closes, it sends a summary with repeated set to the number of extra events. Use repeated to count extra events; do not treat the summary as a new failure.

The client sends only the latest participant count and each repeated collaboration status once per window. To change the window, set dedupeWindowMs.

See why an edit failed during development

Add consoleExporter() to print each event with its hint and documentation link:

import { createTelemetry, consoleExporter } from '@docx-editor.dev/telemetry';

export const telemetry = createTelemetry({ exporters: [consoleExporter()] });

If an agent deletes a picture through the editing API while changes are tracked, the console prints the following output:

[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

Next steps

• To send events to a backend, see Send to Sentry, Send to OpenTelemetry, Send to a log service, or Send to your own code.
• To add your own room or user identifiers, see Identify rooms and users.
• To measure how fast editing feels, see Measure performance.