feat: telemetry [WIP] #1932

andrii-harbour · 2026-02-04T00:20:29Z

Added telemetry support to track document opens for usage-based billing.
Introduced initTelemetry method in the Editor class to initialize telemetry based on configuration.
Created tests for telemetry functionality, ensuring correct behavior when enabled/disabled and with various configurations.
Updated Editor and SuperDoc configurations to include telemetry options and license key handling.
Enhanced SuperConverter to manage document creation timestamps for unique identification.

- Added telemetry support to track document opens for usage-based billing. - Introduced `initTelemetry` method in the Editor class to initialize telemetry based on configuration. - Created tests for telemetry functionality, ensuring correct behavior when enabled/disabled and with various configurations. - Updated Editor and SuperDoc configurations to include telemetry options and license key handling. - Enhanced SuperConverter to manage document creation timestamps for unique identification.

linear · 2026-02-04T00:20:32Z

SD-1638 Telemetry: create telemetry set-up in SuperDoc core lib

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64ce62e12f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-02-04T00:23:35Z

packages/super-editor/src/core/super-converter/SuperConverter.js

+  #generateIdentifierHash() {
+    const docId = this.documentGuid || uuidv4();
+    const created = this.getDocumentCreatedTimestamp() || new Date().toISOString();



Keep identifier stable when docId/created missing

When a document lacks a stored docId or a dcterms:created timestamp (common in some legacy or generated DOCX files), #generateIdentifierHash() falls back to uuidv4() and new Date().toISOString(). That means the identifier changes every time the same file is opened, so telemetry will over-count “document opens” and break the “same document across sessions” guarantee. Before this change, the hash was derived from file contents, which was stable across opens. Consider deriving the fallback from the file bytes (or persisting a generated ID into the document) to keep identifiers stable across sessions.

Useful? React with 👍 / 👎.

@andrii-harbour this is really important - we can't overwrite createdTimestamp everytime doc is opened

- Simplified telemetry logging in the Editor class by removing unnecessary comments and enhancing debug output for document information. - Removed redundant isNewFile tracking in SuperDoc, allowing automatic handling based on context.

- Introduced default community license key in the Editor class for telemetry initialization. - Updated `initTelemetry` function to use the default license key when none is provided. - Added tests to verify behavior with default and custom license keys. - Improved documentation for the community license key usage.

caio-pizzol

nice work! just a few comments

caio-pizzol · 2026-02-04T18:22:36Z

packages/super-editor/src/core/super-converter/SuperConverter.js

    this.documentModified = false; // Track if document has been edited

+    // Track if this is a new file created from template
+    this.isNewFile = params?.isNewFile || false;


NewFile means never opened in SuperDoc previously?

caio-pizzol · 2026-02-04T18:23:07Z

packages/super-editor/src/core/Editor.ts

+      console.debug('[super-editor] Document info:', telemetryPayload);
+      this.#telemetry.trackDocumentOpen(documentId || null, documentCreatedAt);
+    } catch {
+      // Fail silently - telemetry should never break the app


caio-pizzol · 2026-02-04T18:35:31Z

packages/super-editor/src/core/super-converter/SuperConverter.js

+  #generateIdentifierHash() {
+    const docId = this.documentGuid || uuidv4();
+    const created = this.getDocumentCreatedTimestamp() || new Date().toISOString();



@andrii-harbour this is really important - we can't overwrite createdTimestamp everytime doc is opened

caio-pizzol · 2026-02-04T18:36:35Z

shared/common/Telemetry.ts

-   * @returns Promise that resolves when data is sent
-   */
-  async sendDataToTelemetry(data: TelemetryPayload): Promise<void> {
+    console.log('[Telemetry] Sending payload:', payload);


should be removed - they'll log every payload to the console in production

caio-pizzol · 2026-02-04T18:38:17Z

packages/super-editor/src/core/Editor.ts

    setTimeout(() => {
      if (this.isDestroyed) return;
      this.emit('create', { editor: this });
+      this.#trackDocumentOpen();


#trackDocumentOpen() is called from both #emitCreateAsync() and mount()

if an editor gets created and then mounted later, this could double-count. might want a guard flag.

caio-pizzol · 2026-02-04T19:15:22Z

packages/super-editor/src/core/super-converter/SuperConverter.js

+    // Generate and cache the hash if not already done
+    if (!this.documentHash) {
+      this.documentHash = this.#generateIdentifierHash();
+      console.debug('[super-converter] Generated document identifier:', {


caio-pizzol · 2026-02-04T19:16:13Z

shared/common/Telemetry.ts

-      } else {
-        this.resetStatistics();
-      }
+      console.log('[Telemetry] Response status:', response.status);


these logs should be removed or wrapped in a dev check - especially the payload log which includes all telemetry data (final user would see them when inspecting)

caio-pizzol · 2026-02-04T19:17:44Z

packages/super-editor/src/core/super-converter/SuperConverter.js

+   * Get the dcterms:created timestamp from the already-parsed core.xml
+   * @returns {string|null} The created timestamp in ISO format, or null if not found
+   */
+  getDocumentCreatedTimestamp() {


getDocumentCreatedTimestamp() and setDocumentCreatedTimestamp() don't have dedicated tests - might be worth adding since they're key to document identity

caio-pizzol · 2026-02-04T19:26:07Z

packages/super-editor/src/core/super-converter/SuperConverter.js

+   * Set the dcterms:created timestamp in the already-parsed core.xml
+   * @param {string} timestamp - The timestamp to set (ISO format)
+   */
+  setDocumentCreatedTimestamp(timestamp) {


the dcterms:created element requires xsi:type="dcterms:W3CDTF" attribute per ECMA-376 Part 2 §11.4 [M4.5] -> verify this

current code only sets text content but doesn't verify the required attribute exists in document and/or create the element if missing

this might cause issues with strict OOXML validators

caio-pizzol · 2026-02-04T19:29:16Z

shared/common/Telemetry.ts

+      superdocVersion: this.superdocVersion,
+      browserInfo: this.getBrowserInfo(),
+      ...(this.metadata && { metadata: this.metadata }),
+      events: [event],


are we batching those events?

andrii-harbour requested a review from harbournick February 4, 2026 00:20

andrii-harbour self-assigned this Feb 4, 2026

andrii-harbour changed the title ~~feat: telemetry~~ feat: telemetry [WIP] Feb 4, 2026

chatgpt-codex-connector bot reviewed Feb 4, 2026

View reviewed changes

andrii-harbour added 2 commits February 4, 2026 02:06

andrii-harbour requested a review from caio-pizzol February 4, 2026 01:29

test: update telemetry test endpoint URL

372512b

caio-pizzol reviewed Feb 4, 2026

View reviewed changes

feat: telemetry [WIP] #1932

Are you sure you want to change the base?

feat: telemetry [WIP] #1932

Uh oh!

Conversation

andrii-harbour commented Feb 4, 2026

Uh oh!

linear bot commented Feb 4, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants