Telemetry

@docx-editor.dev/telemetry sends anonymous diagnostics and metrics to your monitoring tools. It covers single-user editors, collaboration clients, and collaboration servers.

Configure exporters to send data, and choose which areas to record. Built-in diagnostics contain codes, booleans, bucketed sizes and counts, and timings. They exclude document text, file names, part names, author names, font names, and room names. You control any attributes you add and any data your monitoring SDKs collect.

flowchart LR
  E[Editor] -- diagnostics --> T[createTelemetry]
  S[Collaboration server] --> R[withCollaborationTelemetry or roomTelemetry]
  T --> X[Exporters]
  R --> X
  X --> O[OpenTelemetry SDK]
  X --> P[Prometheus /metrics]
  X --> Y[Sentry]
  X --> C[Your callback]

Choose an exporter

Metrics use the OpenTelemetry model. Prometheus metric names replace dots with underscores and include units: docx_editor.collab.room.load.duration in seconds becomes docx_editor_collab_room_load_duration_seconds.

Install

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

Install the peer dependencies for the integrations you use:

• OpenTelemetry: @opentelemetry/api.
• Room telemetry: yjs and @docx-editor.dev/pro.
• Hocuspocus: @hocuspocus/server 4.6 or later.

The Sentry exporter uses your app's Sentry SDK. The Prometheus exporter has no dependencies. Editor apps also need @docx-editor.dev/react or @docx-editor.dev/vue. Add @docx-editor.dev/pro for review and collaboration.

Privacy

• The package never sends data by itself. It sends only to the exporters you configure.
• Diagnostics use fixed sets of codes, booleans, bucketed sizes and counts, and timings. Document text, file and part names, author names, font names, and exception messages are never included.
• The engine builds each event this way, and the package checks each event again before an exporter receives it.
• You control identifiers in attributes, resource, and metricLabels. You also control what your Sentry and OpenTelemetry SDKs collect.

For fields and validation rules, see Privacy. To review your settings, see Privacy review checklist.

Where to start

Review data collection, set up your editor, then choose a destination. Use the other guides for specific tasks.

1. Privacy: what is sent and what is never sent. Start here for a privacy review, then complete the Privacy review checklist.
2. Set up an editor: create the client, register its module, and choose what to record.
3. Send the data to your backend:
   • Send to Sentry for grouped issues.
   • Send to OpenTelemetry for metrics and traces in Grafana, Datadog, or Honeycomb.
   • Send to a log service for Better Stack or any HTTP log intake. For Axiom and Datadog Logs, see Other log services.
   • Send to your own code for Datadog RUM, PostHog, or your own logger.
4. Optional:
   • Measure performance: how fast typing and layout feel.
   • Identify rooms and users: your own identifiers, and thousands of open editors.
   • Server agents: agents that use the editing API.
   • Collaboration servers: set up metrics on your server. Then read Rooms, people, and memory for what the room metrics mean.
5. Monitor your app with Dashboards. For metric names and labels, see Metrics.

For every diagnostic code and its hint, see Diagnostics. For complete setups, see the single-user example, the collaboration example, and the dashboards stack.