@docx-editor.dev/telemetry 0.0.1 → 2.29.0

package/dist/sentry/index.js

@@ -0,0 +1 @@
+import {b as b$1}from'../chunk-NUN46EXH.js';var i=class extends Error{name="DocxEditorDiagnosticError";code;constructor(r,t){super(t?`${r}: ${t}`:r),this.code=r;}},u=new Set(["collab.authentication-failed","collab.room-generation-changed"]),l=new Set(["open.failed","open.unsupported-source","open.invalid-limits"]),f=Object.freeze([".docx-editor",".docx-pages"]);function x(e,r){return e.category?.startsWith("ui.")&&g(r?.event?.target)?null:e}function g(e){try{let r=e;return r&&typeof r.closest!="function"&&(r=r.parentElement),!r||typeof r.closest!="function"?!0:r.closest(f.join(", "))!=null}catch{return  true}}function p(e){switch(e.kind){case "document.open":return e.outcome==="rejected"&&l.has(e.code);case "edit.rejected":return e.code==="edit.internal-invariant";case "review.skipped":return e.code==="review.revision-unsupported"||e.code==="review.retained-structure";case "font.failed":return e.code==="font.shaper-unavailable";case "collab.status":return e.status==="error"&&!e.recovering&&!u.has(e.code??"");default:return  false}}function m(e){return e.kind==="document.open"?e.outcome==="opened":e.kind==="performance"&&e.code===void 0}function c(e){return "code"in e&&e.code?e.code:e.kind}function y(e){let r=e,t={"docx_editor.kind":e.kind,"docx_editor.code":c(e),"docx_editor.version":e.engineVersion,"docx_editor.editor_session":e.editorSessionId};for(let[o,n]of [["origin","origin"],["tracked","tracked"],["status","status"],["outcome","outcome"],["command","command"],["cause","cause"],["part","part"],["errorName","error_name"],["stage","stage"],["operation","operation"],["changeKind","change_kind"],["formattingKind","formatting_kind"]])r[o]!==void 0&&(t[`docx_editor.${n}`]=String(r[o]));for(let[o,n]of Object.entries(e.attributes??{}))t[o]=String(n);return t}function k(e,r){let t=e,o=["cause","errorName","stage","changeKind","formattingKind"].map(n=>t[n]).filter(n=>typeof n=="string");return ["docx-editor",e.kind,r,...o]}function d(e){let{resource:r,...t}=e;return {...t,...Object.keys(r).length?{resource:r}:{}}}function b(e,r={}){let t=r.issue??p,o=r.breadcrumbs??true;return {name:"sentry",event(n){let s=c(n);if(n.repeated===void 0&&t(n)){e.captureException(new i(s,n.hint),{fingerprint:k(n,s),level:n.kind==="font.failed"||n.kind==="review.skipped"?"warning":"error",tags:y(n),contexts:{docx_editor:d(n)}});return}o&&e.addBreadcrumb({category:"docx-editor",message:b$1(n),level:m(n)?"info":"warning",data:d(n)});},async flush(){await e.flush?.(2e3);}}}export{i as DocxEditorDiagnosticError,f as EDITOR_SELECTORS,x as dropEditorBreadcrumbs,p as isSentryIssue,b as sentryExporter};

package/dist/server/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunk7ZXJ6HP2_cjs=require('../chunk-7ZXJ6HP2.cjs');require('../chunk-U6ERFNUM.cjs'),require('../chunk-LGNT4I5W.cjs'),require('../chunk-LFQSY2TD.cjs'),require('../chunk-WGWKNKUT.cjs');Object.defineProperty(exports,"hmacRoomLabel",{enumerable:true,get:function(){return chunk7ZXJ6HP2_cjs.a}});Object.defineProperty(exports,"roomTelemetry",{enumerable:true,get:function(){return chunk7ZXJ6HP2_cjs.b}});

package/dist/server/index.d.cts

@@ -0,0 +1,156 @@
+/**
+ * Room telemetry for any Yjs collaboration server: rooms, connections, the people in each
+ * room, the memory each room holds, and why connections and messages were refused.
+ *
+ * No metric carries a room name. Per-room detail is in {@link RoomTelemetry.list}, for an
+ * admin endpoint you protect.
+ *
+ * @packageDocumentation
+ */
+import * as Y from 'yjs';
+import { T as TelemetryPipelineOptions } from '../pipeline-DbVW7S-K.cjs';
+export { b as TelemetryExporter } from '../pipeline-DbVW7S-K.cjs';
+import '@docx-editor.dev/core';
+
+/** The part of a `y-protocols` `Awareness` the telemetry reads. @public */
+interface AwarenessLike {
+    getStates(): Map<number, unknown>;
+    on(event: 'change', listener: (...args: unknown[]) => void): void;
+    off(event: 'change', listener: (...args: unknown[]) => void): void;
+}
+/** Options for {@link roomTelemetry}. @public */
+interface RoomTelemetryOptions extends TelemetryPipelineOptions {
+    /**
+     * How often to sample people, memory, and room size, in milliseconds. Defaults to 60 000.
+     * `false` turns the timer off; call `sample()` yourself, for example before each scrape.
+     */
+    readonly sampleInterval?: number | false;
+    /**
+     * Measure each room's encoded Yjs state. This encodes the room once per sample, and only when
+     * it changed since the last one. Defaults to `true`.
+     */
+    readonly measureState?: boolean;
+    /**
+     * How a room appears in {@link RoomTelemetry.list}. Defaults to an index that is valid only
+     * inside this process, such as `room-3`. Use `(name) => name` to see real names, or
+     * {@link hmacRoomLabel} for a stable label that does not reveal the name.
+     */
+    readonly roomLabel?: (name: string) => string;
+    /**
+     * Also record each room's people and memory as gauges labeled `room`. Off by default: a label
+     * per room makes one series per room, and a large server has many rooms. A closed room's
+     * series is dropped. Only the default label or `hmacRoomLabel` is accepted, so no room name
+     * can become a label; any other `roomLabel` throws.
+     */
+    readonly perRoomSeries?: boolean;
+    /**
+     * Your own reading of a refusal, for errors whose `reason` or `code` is free text. Return a
+     * common reason such as `unauthorized`, a collaboration failure code, or one of `reasons`;
+     * anything else is counted as `other`. Return undefined to use the default reading.
+     */
+    readonly reasonOf?: (error: unknown) => string | undefined;
+    /**
+     * Refusal reasons to keep as metric labels. Compared without case and recorded in lowercase. Collaboration failure codes are always kept.
+     * Any other reason is counted as `other`, so a free-text error never becomes a time series.
+     */
+    readonly reasons?: readonly string[];
+}
+/** One room in {@link RoomTelemetry.list}. @public */
+interface RoomStats {
+    readonly room: string;
+    /** People present, from awareness states. A person with two tabs counts twice. */
+    readonly participants: number;
+    readonly connections: number;
+    /** Encoded Yjs state at the last sample, or `null` before the first one. */
+    readonly stateBytes: number | null;
+    readonly blobBytes: number | null;
+    /** Bytes of updates applied since the room was last stored. */
+    readonly pendingBytes: number;
+    readonly nodes: number | null;
+    /** The largest share of any room limit in use, from 0 to 1. */
+    readonly limitRatio: number | null;
+    readonly ageSeconds: number;
+    readonly idleSeconds: number;
+}
+/** What a timed room operation is. @public */
+type RoomOperation = 'load' | 'store';
+/** Records a started operation's duration with its outcome. Later calls do nothing. @public */
+type SettleOperation = (outcome: 'success' | 'failure') => void;
+/** One open room. Returned by {@link RoomTelemetry.open}. @public */
+interface RoomHandle {
+    /** The room's label, as {@link RoomTelemetryOptions.roomLabel} made it. */
+    readonly label: string;
+    /** Run `operation` and record its duration and outcome. Rethrows its error. */
+    time<T>(operation: RoomOperation, run: () => T | Promise<T>): Promise<T>;
+    /** Start timing `operation` where `time` cannot wrap it; call the result once it settles. */
+    begin(operation: RoomOperation): SettleOperation;
+    connected(): void;
+    disconnected(): void;
+    /** Stop tracking the room, for example when the server unloads it. */
+    close(): void;
+}
+/** Room telemetry for one server process. @public */
+interface RoomTelemetry {
+    /**
+     * Start tracking a loaded room. Pass the room's awareness to count people; without it the
+     * number of connections stands in.
+     */
+    open(doc: Y.Doc, options?: {
+        readonly name?: string;
+        readonly awareness?: AwarenessLike;
+    }): RoomHandle;
+    /** A connection refused at admission. `reason` can be a string or an error with `reason`. */
+    rejected(reason: unknown): void;
+    /** A message refused before it applied, such as `room-generation-changed`. */
+    refused(reason: unknown): void;
+    /** A room migration finished. */
+    migrated(outcome: 'migrated' | 'unchanged' | 'failed'): void;
+    /** Time an operation that happens before the room is open, such as a load that fails. */
+    time<T>(operation: RoomOperation, run: () => T | Promise<T>): Promise<T>;
+    /** Start timing an operation that has no room yet; call the result once it settles. */
+    begin(operation: RoomOperation): SettleOperation;
+    /** Every open room, for an admin endpoint you protect. */
+    list(): readonly RoomStats[];
+    /** Sample people, memory, and size now. */
+    sample(): void;
+    flush(): Promise<void>;
+    /** Stop the timer, close every room, and shut the exporters down. */
+    shutdown(): Promise<void>;
+}
+/**
+ * A stable room label that does not reveal the name: an HMAC of the name with your secret.
+ * The same name gives the same label across processes and restarts.
+ *
+ * @example
+ * ```ts
+ * const rooms = roomTelemetry({
+ *   exporters: [metrics],
+ *   roomLabel: hmacRoomLabel(process.env.ROOM_LABEL_SECRET),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function hmacRoomLabel(secret: string | undefined): (name: string) => string;
+/**
+ * Track rooms on a Yjs server.
+ *
+ * @example
+ * ```ts
+ * import { roomTelemetry } from '@docx-editor.dev/telemetry/server';
+ * import { prometheusRegistry, metricsHandler } from '@docx-editor.dev/telemetry/prometheus';
+ *
+ * const metrics = prometheusRegistry();
+ * const rooms = roomTelemetry({ exporters: [metrics] });
+ *
+ * const room = rooms.open(ydoc, { name, awareness });
+ * await room.time('load', () => loadRoom(ydoc)); // the loaded state is not counted as edits
+ * room.connected();
+ * ```
+ *
+ * @public
+ */
+declare function roomTelemetry(options: RoomTelemetryOptions): RoomTelemetry;
+
+export { TelemetryPipelineOptions, hmacRoomLabel, roomTelemetry };
+export type { AwarenessLike, RoomHandle, RoomOperation, RoomStats, RoomTelemetry, RoomTelemetryOptions, SettleOperation };

package/dist/server/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Room telemetry for any Yjs collaboration server: rooms, connections, the people in each
+ * room, the memory each room holds, and why connections and messages were refused.
+ *
+ * No metric carries a room name. Per-room detail is in {@link RoomTelemetry.list}, for an
+ * admin endpoint you protect.
+ *
+ * @packageDocumentation
+ */
+import * as Y from 'yjs';
+import { T as TelemetryPipelineOptions } from '../pipeline-DbVW7S-K.js';
+export { b as TelemetryExporter } from '../pipeline-DbVW7S-K.js';
+import '@docx-editor.dev/core';
+
+/** The part of a `y-protocols` `Awareness` the telemetry reads. @public */
+interface AwarenessLike {
+    getStates(): Map<number, unknown>;
+    on(event: 'change', listener: (...args: unknown[]) => void): void;
+    off(event: 'change', listener: (...args: unknown[]) => void): void;
+}
+/** Options for {@link roomTelemetry}. @public */
+interface RoomTelemetryOptions extends TelemetryPipelineOptions {
+    /**
+     * How often to sample people, memory, and room size, in milliseconds. Defaults to 60 000.
+     * `false` turns the timer off; call `sample()` yourself, for example before each scrape.
+     */
+    readonly sampleInterval?: number | false;
+    /**
+     * Measure each room's encoded Yjs state. This encodes the room once per sample, and only when
+     * it changed since the last one. Defaults to `true`.
+     */
+    readonly measureState?: boolean;
+    /**
+     * How a room appears in {@link RoomTelemetry.list}. Defaults to an index that is valid only
+     * inside this process, such as `room-3`. Use `(name) => name` to see real names, or
+     * {@link hmacRoomLabel} for a stable label that does not reveal the name.
+     */
+    readonly roomLabel?: (name: string) => string;
+    /**
+     * Also record each room's people and memory as gauges labeled `room`. Off by default: a label
+     * per room makes one series per room, and a large server has many rooms. A closed room's
+     * series is dropped. Only the default label or `hmacRoomLabel` is accepted, so no room name
+     * can become a label; any other `roomLabel` throws.
+     */
+    readonly perRoomSeries?: boolean;
+    /**
+     * Your own reading of a refusal, for errors whose `reason` or `code` is free text. Return a
+     * common reason such as `unauthorized`, a collaboration failure code, or one of `reasons`;
+     * anything else is counted as `other`. Return undefined to use the default reading.
+     */
+    readonly reasonOf?: (error: unknown) => string | undefined;
+    /**
+     * Refusal reasons to keep as metric labels. Compared without case and recorded in lowercase. Collaboration failure codes are always kept.
+     * Any other reason is counted as `other`, so a free-text error never becomes a time series.
+     */
+    readonly reasons?: readonly string[];
+}
+/** One room in {@link RoomTelemetry.list}. @public */
+interface RoomStats {
+    readonly room: string;
+    /** People present, from awareness states. A person with two tabs counts twice. */
+    readonly participants: number;
+    readonly connections: number;
+    /** Encoded Yjs state at the last sample, or `null` before the first one. */
+    readonly stateBytes: number | null;
+    readonly blobBytes: number | null;
+    /** Bytes of updates applied since the room was last stored. */
+    readonly pendingBytes: number;
+    readonly nodes: number | null;
+    /** The largest share of any room limit in use, from 0 to 1. */
+    readonly limitRatio: number | null;
+    readonly ageSeconds: number;
+    readonly idleSeconds: number;
+}
+/** What a timed room operation is. @public */
+type RoomOperation = 'load' | 'store';
+/** Records a started operation's duration with its outcome. Later calls do nothing. @public */
+type SettleOperation = (outcome: 'success' | 'failure') => void;
+/** One open room. Returned by {@link RoomTelemetry.open}. @public */
+interface RoomHandle {
+    /** The room's label, as {@link RoomTelemetryOptions.roomLabel} made it. */
+    readonly label: string;
+    /** Run `operation` and record its duration and outcome. Rethrows its error. */
+    time<T>(operation: RoomOperation, run: () => T | Promise<T>): Promise<T>;
+    /** Start timing `operation` where `time` cannot wrap it; call the result once it settles. */
+    begin(operation: RoomOperation): SettleOperation;
+    connected(): void;
+    disconnected(): void;
+    /** Stop tracking the room, for example when the server unloads it. */
+    close(): void;
+}
+/** Room telemetry for one server process. @public */
+interface RoomTelemetry {
+    /**
+     * Start tracking a loaded room. Pass the room's awareness to count people; without it the
+     * number of connections stands in.
+     */
+    open(doc: Y.Doc, options?: {
+        readonly name?: string;
+        readonly awareness?: AwarenessLike;
+    }): RoomHandle;
+    /** A connection refused at admission. `reason` can be a string or an error with `reason`. */
+    rejected(reason: unknown): void;
+    /** A message refused before it applied, such as `room-generation-changed`. */
+    refused(reason: unknown): void;
+    /** A room migration finished. */
+    migrated(outcome: 'migrated' | 'unchanged' | 'failed'): void;
+    /** Time an operation that happens before the room is open, such as a load that fails. */
+    time<T>(operation: RoomOperation, run: () => T | Promise<T>): Promise<T>;
+    /** Start timing an operation that has no room yet; call the result once it settles. */
+    begin(operation: RoomOperation): SettleOperation;
+    /** Every open room, for an admin endpoint you protect. */
+    list(): readonly RoomStats[];
+    /** Sample people, memory, and size now. */
+    sample(): void;
+    flush(): Promise<void>;
+    /** Stop the timer, close every room, and shut the exporters down. */
+    shutdown(): Promise<void>;
+}
+/**
+ * A stable room label that does not reveal the name: an HMAC of the name with your secret.
+ * The same name gives the same label across processes and restarts.
+ *
+ * @example
+ * ```ts
+ * const rooms = roomTelemetry({
+ *   exporters: [metrics],
+ *   roomLabel: hmacRoomLabel(process.env.ROOM_LABEL_SECRET),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function hmacRoomLabel(secret: string | undefined): (name: string) => string;
+/**
+ * Track rooms on a Yjs server.
+ *
+ * @example
+ * ```ts
+ * import { roomTelemetry } from '@docx-editor.dev/telemetry/server';
+ * import { prometheusRegistry, metricsHandler } from '@docx-editor.dev/telemetry/prometheus';
+ *
+ * const metrics = prometheusRegistry();
+ * const rooms = roomTelemetry({ exporters: [metrics] });
+ *
+ * const room = rooms.open(ydoc, { name, awareness });
+ * await room.time('load', () => loadRoom(ydoc)); // the loaded state is not counted as edits
+ * room.connected();
+ * ```
+ *
+ * @public
+ */
+declare function roomTelemetry(options: RoomTelemetryOptions): RoomTelemetry;
+
+export { TelemetryPipelineOptions, hmacRoomLabel, roomTelemetry };
+export type { AwarenessLike, RoomHandle, RoomOperation, RoomStats, RoomTelemetry, RoomTelemetryOptions, SettleOperation };

package/dist/server/index.js

@@ -0,0 +1 @@
+export{a as hmacRoomLabel,b as roomTelemetry}from'../chunk-RRYW7EAV.js';import'../chunk-S7KBMROA.js';import'../chunk-73YEPWY5.js';import'../chunk-DTEVX2XS.js';import'../chunk-DT2KMPUJ.js';

package/package.json

@@ -1,31 +1,115 @@
 {
   "name": "@docx-editor.dev/telemetry",
-  "version": "0.0.1",
-  "description": "Placeholder that reserves the name. The first release is 2.29.0: anonymous diagnostics, metrics, and error reporting for @docx-editor.dev editors and collaboration servers.",
-  "license": "LicenseRef-EigenPal-Pro-Evaluation-1.0",
+  "version": "2.29.0",
+  "description": "Anonymous diagnostics, metrics, and error reporting for @docx-editor.dev editors and collaboration servers, with OpenTelemetry, Prometheus, and Sentry exporters.",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./otel": {
+      "types": "./dist/otel/index.d.ts",
+      "import": "./dist/otel/index.js",
+      "require": "./dist/otel/index.cjs"
+    },
+    "./sentry": {
+      "types": "./dist/sentry/index.d.ts",
+      "import": "./dist/sentry/index.js",
+      "require": "./dist/sentry/index.cjs"
+    },
+    "./prometheus": {
+      "types": "./dist/prometheus/index.d.ts",
+      "import": "./dist/prometheus/index.js",
+      "require": "./dist/prometheus/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.cjs"
+    },
+    "./hocuspocus": {
+      "types": "./dist/hocuspocus/index.d.ts",
+      "import": "./dist/hocuspocus/index.js",
+      "require": "./dist/hocuspocus/index.cjs"
+    },
+    "./ingest": {
+      "types": "./dist/ingest/index.d.ts",
+      "import": "./dist/ingest/index.js",
+      "require": "./dist/ingest/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/metafile-*.json",
+    "LICENSE.md",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/check-built-siblings.mjs && node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "typecheck": "bun check",
+    "license:check": "license-check-and-add check -f license-check.json",
+    "license:add": "license-check-and-add add -f license-check.json"
+  },
+  "peerDependencies": {
+    "@docx-editor.dev/core": "~2.29.0",
+    "@docx-editor.dev/pro": "~2.29.0",
+    "@opentelemetry/api": "^1.9.0",
+    "yjs": "^13.6.32",
+    "@hocuspocus/server": "^4.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@docx-editor.dev/pro": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "yjs": {
+      "optional": true
+    },
+    "@hocuspocus/server": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@docx-editor.dev/core": "workspace:*",
+    "@docx-editor.dev/pro": "workspace:*",
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@hocuspocus/server": "^4.6.0",
+    "@opentelemetry/api": "1.9.0",
+    "@sentry/core": "9.47.2",
+    "fflate": "^0.8.2",
+    "license-check-and-add": "^4.0.5",
+    "typescript7": "npm:typescript@^7.0.2",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.32"
+  },
+  "keywords": [
+    "docx",
+    "telemetry",
+    "opentelemetry",
+    "prometheus",
+    "sentry",
+    "observability",
+    "collaboration"
+  ],
   "author": {
     "name": "EigenPal, Inc.",
     "email": "licensing@eigenpal.com",
     "url": "https://eigenpal.com"
   },
-  "homepage": "https://docx-editor.dev/docs/2.x/telemetry",
+  "license": "LicenseRef-EigenPal-Pro-Evaluation-1.0",
+  "homepage": "https://docx-editor.dev/",
   "repository": {
     "type": "git",
     "url": "https://github.com/eigenpal/docx-editor.git",
     "directory": "packages/telemetry"
   },
-  "keywords": [
-    "docx",
-    "telemetry",
-    "opentelemetry",
-    "prometheus",
-    "sentry",
-    "observability"
-  ],
-  "files": [
-    "README.md",
-    "LICENSE.md"
-  ],
   "publishConfig": {
     "access": "public"
   }