@docx-editor.dev/telemetry/sentry
Sentry: actionable failures become issues grouped by code; everything else becomes a breadcrumb, so it appears beside your own errors without using your event quota.
Functions (3)
dropEditorBreadcrumbsfunctionSource ↗
A beforeBreadcrumb filter that drops Sentry's click and key press breadcrumbs from inside the editor. Sentry describes the element a person clicked with its alt, title, and aria-label values. Inside the editor, those values come from the document: picture descriptions, link tooltips, and content control names. A ui breadcrumb whose element is unknown is dropped too. Other breadcrumbs pass unchanged.
declare function dropEditorBreadcrumbs<B extends SentryBreadcrumbLike>(breadcrumb: B, hint?: SentryBreadcrumbHintLike): B | null;```ts
Sentry.init({ dsn, beforeBreadcrumb: dropEditorBreadcrumbs });
// With a filter of your own:
Sentry.init({
dsn,
beforeBreadcrumb: (crumb, hint) => {
const kept = dropEditorBreadcrumbs(crumb, hint);
return kept && myFilter(kept, hint); // dropped breadcrumbs never reach your filter
},
});
```isSentryIssuefunctionSource ↗
The default issue rule: an open the app caused, an internal error, a shaper that never loaded, and a collaboration error that will not heal become issues. Wrap it to add your own.
declare function isSentryIssue(event: TelemetryEvent): boolean;```ts
sentryExporter(Sentry, {
issue: (event) =>
isSentryIssue(event) || ('code' in event && event.code === 'font.load-failed'),
});
```sentryExporterfunctionSource ↗
Send diagnostics to Sentry.
Sentry Session Replay records the page, and the page shows the document. Block the editor in Replay, so neither its text nor its pictures are recorded, and drop the click breadcrumbs that describe its elements: Sentry.replayIntegration({ block: [...EDITOR_SELECTORS] }) and beforeBreadcrumb: dropEditorBreadcrumbs.
declare function sentryExporter(sentry: SentryLike, options?: SentryExporterOptions): TelemetryExporter;```ts
import * as Sentry from '@sentry/react';
import { createTelemetry } from '@docx-editor.dev/telemetry';
import { sentryExporter } from '@docx-editor.dev/telemetry/sentry';
export const telemetry = createTelemetry({ exporters: [sentryExporter(Sentry)] });
```Classes (1)
DocxEditorDiagnosticErrorclassSource ↗
The error a Sentry issue is made from. The message is the code, so issues group by cause, and the stack trace contains no document data.
declare class DocxEditorDiagnosticError extends Error| Member | Type | Summary |
|---|---|---|
| (constructor) | | Constructs a new instance of the `DocxEditorDiagnosticError` class |
| code | string | |
| name | |
Interfaces (5)
SentryBreadcrumbHintLikeinterfaceSource ↗
The hint Sentry passes with a breadcrumb. For a click or key press, event is the DOM event.
interface SentryBreadcrumbHintLike| Member | Type | Summary |
|---|---|---|
| event? | unknown |
SentryBreadcrumbLikeinterfaceSource ↗
A Sentry breadcrumb, as beforeBreadcrumb receives it.
interface SentryBreadcrumbLike| Member | Type | Summary |
|---|---|---|
| category? | string |
SentryExporterOptionsinterfaceSource ↗
Options for [sentryExporter](sentryExporter).
interface SentryExporterOptions| Member | Type | Summary |
|---|---|---|
| breadcrumbs? | boolean | Record breadcrumbs for the other events. Defaults to `true`. |
| issue? | (event: TelemetryEvent) => boolean | Which events become Sentry issues. The rest become breadcrumbs. The default sends an issue when the app can act: an open refused because the app passed something wrong or for an unknown reason, a collaboration error that will not heal, a text shaper that did not load, and an engine invariant. A corrupt or oversized file and a refused keystroke are breadcrumbs. |
SentryLikeinterfaceSource ↗
The part of a Sentry SDK the exporter uses. @sentry/browser, @sentry/react, @sentry/vue, @sentry/nextjs, and @sentry/node all fit: pass the module itself.
interface SentryLike| Member | Type | Summary |
|---|---|---|
| addBreadcrumb | | |
| captureException | | |
| flush | | Send queued events. Called when the page is hidden. |
TelemetryExporterinterfaceSource ↗
Where telemetry goes. Implement event, metric, or both.
An exporter never throws into the editor or the server: a failure is caught and reported once through onExporterError.
interface TelemetryExporter```ts
const toMyLogger: TelemetryExporter = {
name: 'my-logger',
event: (event) => myLogger.warn(event.kind, { code: 'code' in event ? event.code : undefined }),
};
```| Member | Type | Summary |
|---|---|---|
| attach | | Called once when a telemetry client or room server takes the exporter. An exporter that holds events, such as a batching one, reads `consented()` before it sends, so events queued before consent was withdrawn are discarded, not sent. |
| declare | | Start a series at zero before its first measurement. A scraper that sees a counter first at 1 cannot count that first increase, so the room server declares its known series when it starts. Optional: an exporter without it creates each series at its first measurement. |
| event | | |
| flush | | Send anything buffered. Called by `flush()` and when a page is hidden. |
| forget | | Drop a series that no longer exists, such as a closed room's per-room gauge. Optional: an exporter without it keeps the series until it expires on its own. |
| metric | | |
| name | string | Shown in `onExporterError` reports. |
| shutdown | | Flush and release resources. Called by `shutdown()`. |
Type aliases (2)
SentrySeveritytypeSource ↗
Sentry severity, as the Sentry SDKs spell it.
type SentrySeverity = 'fatal' | 'error' | 'warning' | 'info' | 'debug';TelemetryEventtypeSource ↗
A diagnostic as an exporter receives it. Switch on kind to narrow it.
type TelemetryEvent = EditorDiagnostic & TelemetryEventContext;Variables (1)
EDITOR_SELECTORSconstSource ↗
CSS selectors for everything that shows the document: the editor shell and the painted pages. Pass them to Session Replay's block option, which replaces the editor with a placeholder, so mask is not needed as well.
EDITOR_SELECTORS: readonly string[]