Server agents

Record anonymous diagnostics from agents that edit documents through the editing API, on a server or in the browser.

@docx-editor.dev/telemetry is available in version 2.29.0 and later.

Register agent telemetry

Create one telemetry client per process and pass its module to every DocxEditor.createServer runtime:

import { DocxEditor } from '@docx-editor.dev/editor-api';
import { createTelemetry } from '@docx-editor.dev/telemetry';
import { otelExporter } from '@docx-editor.dev/telemetry/otel';

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

const runtime = await DocxEditor.createServer(bytes, {
  author: 'Review agent',
  modules: [telemetry.module],
});
try {
  // Run the agent here.
} finally {
  runtime.dispose();
}

The runtime reports document-open diagnostics and a code for each refused batch.

Flush or shut down

DeploymentCall
Long-running workerawait telemetry.shutdown() once, at process exit
Serverless function or single-run jobawait telemetry.flush() before returning

Do not flush per job in a worker. Each flush closes the deduplication windows for all jobs.

Interpret runtime diagnostics

  • A refusal counts as tracked when the batch enables tracking first.
  • editorSessionId identifies one runtime, not necessarily one agent job.
  • A DocxEditor.createBrowser runtime reports through its host editor with origin: 'automation'.
  • Read refusal details from error.debugInfo.innerError. See Batching, loading, and errors.

Limits

  • The Sentry Node SDK can attach request bodies with instructions or document bytes. Remove event.request.data in beforeSend, as shown in Sentry.

See also