chore: improve telemetry collecting using generated SDK (#2424)

* feat: add improved telemetry using generated SDK

* chore: replace BatchSpanProcessor with the SimpleSpanProcessor

* chore: remove unused method

* chore: replace send proper method

* refactor: remove file and add logic to the telemerty file

* refactor: naming in SDK

* chore: add missing properties

* chore: remove additional logic to get user id, install ulid package and change user_id to anonymous_id

* chore: rename user_id to anonymous_id in otel and fix typing

* chore: rename functions and add name of cached file

* chore: replace generating id with crypto with ulid

* chore: change comment

* docs: add points what data we collected

* chore: remove import and check for undefined manually

* fix: cleanObject function types and logic

* feat: add proper package with types and add missing properties for new SDK

* chore: update lock file, fix test and add new to reach the threshold

* chore: add changeset

* chore: improve tests for new functions

* feat: add missing properties

* feat: add tests to pass the unit tests threshlod

* fix: unit tests

* Update docs/@v2/usage-data.md

* chore: remove anonymous id if it is in CI

* chore: add proper files and changes

* chore: add empty data for project and organization to match general SDK structure

* feat: add functionality to have ann id in all cases, update version of SDK, change origin constant to cli

* fix: cleaning file in command if it is not exists

* chore: revert changes

---------

Co-authored-by: Jacek Łękawa <164185257+JLekawa@users.noreply.github.com>

Author: AlbinaBlazhko17

.changeset/new-mammals-accept.md

@@ -0,0 +1,5 @@
+---
+"@redocly/cli": patch
+---
+
+Updated telemetry implementation to use standardized OpenTelemetry format.

docs/@v2/usage-data.md

@@ -19,6 +19,8 @@ When a command is run, the following data is collected:
 - whether the `redocly.yaml` configuration file exists
 - API specification version
 - Platform (Linux, macOS, Windows)
+- Anonymous ID (a randomly generated identifier that doesn't contain personal information)
+- Command execution time
 
 Values such as file names, organization IDs, and URLs are removed, replaced by just "URL" or "file", etc.
 

package-lock.json

@@ -62,10 +62,12 @@
     "set-cookie-parser": "^2.3.5",
     "simple-websocket": "^9.0.0",
     "styled-components": "^6.0.7",
+    "ulid": "^3.0.1",
     "undici": "^6.21.3",
     "yargs": "17.0.1"
   },
   "devDependencies": {
+    "@redocly/cli-otel": "^0.0.4",
     "@types/configstore": "^5.0.1",
     "@types/cookie": "0.6.0",
     "@types/har-format": "^1.2.16",

packages/cli/package.json

@@ -1,4 +1,12 @@
-import { collectXSecurityAuthTypes } from '../../utils/telemetry.js';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, unlinkSync } from 'node:fs';
+import {
+  collectXSecurityAuthTypes,
+  cacheAnonymousId,
+  getCachedAnonymousId,
+} from '../../utils/telemetry.js';
+import { ANONYMOUS_ID_CACHE_FILE } from '../../utils/constants.js';
 
 import type { ArazzoDefinition } from '@redocly/openapi-core';
 
@@ -86,4 +94,86 @@ describe('collectXSecurityAuthTypes', () => {
       'SomeSchemeName',
     ]);
   });
+
+  it('should handle documents with no workflows', () => {
+    const respectXSecurityAuthTypesAndSchemeName: string[] = [];
+    const arazzoDocument = {} as Partial<ArazzoDefinition>;
+    collectXSecurityAuthTypes(arazzoDocument, respectXSecurityAuthTypesAndSchemeName);
+    expect(respectXSecurityAuthTypesAndSchemeName).toEqual([]);
+  });
+
+  it('should handle workflows with no x-security', () => {
+    const respectXSecurityAuthTypesAndSchemeName: string[] = [];
+    const arazzoDocument = {
+      workflows: [
+        {
+          workflowId: 'workflow1',
+          steps: [],
+        },
+      ],
+    } as Partial<ArazzoDefinition>;
+    collectXSecurityAuthTypes(arazzoDocument, respectXSecurityAuthTypesAndSchemeName);
+    expect(respectXSecurityAuthTypesAndSchemeName).toEqual([]);
+  });
+});
+
+describe('cacheAnonymousId and getCachedAnonymousId', () => {
+  const anonymousIdFile = join(tmpdir(), ANONYMOUS_ID_CACHE_FILE);
+
+  beforeEach(() => {
+    if (existsSync(anonymousIdFile)) {
+      unlinkSync(anonymousIdFile);
+    }
+    vi.unstubAllEnvs();
+  });
+
+  afterEach(() => {
+    if (existsSync(anonymousIdFile)) {
+      unlinkSync(anonymousIdFile);
+    }
+    vi.unstubAllEnvs();
+  });
+
+  it('should cache and retrieve anonymous ID if it is not in CI', () => {
+    process.env.CI = '';
+
+    const testId = 'ann_test123';
+
+    cacheAnonymousId(testId);
+    const retrievedId = getCachedAnonymousId();
+
+    expect(retrievedId).toBe(testId);
+    expect(existsSync(anonymousIdFile)).toBe(true);
+  });
+
+  it('should not cache anonymous ID in CI environment', () => {
+    process.env.CI = 'true';
+    const testId = 'ann_test123';
+
+    cacheAnonymousId(testId);
+
+    expect(existsSync(anonymousIdFile)).toBe(false);
+  });
+
+  it('should not retrieve anonymous ID in CI environment', () => {
+    const testId = 'ann_test123';
+    cacheAnonymousId(testId);
+
+    process.env.CI = 'true';
+    const retrievedId = getCachedAnonymousId();
+
+    expect(retrievedId).toBeUndefined();
+  });
+
+  it('should return undefined if no cached ID exists', () => {
+    const retrievedId = getCachedAnonymousId();
+
+    expect(retrievedId).toBeUndefined();
+  });
+
+  it('should not cache if anonymousId is empty', () => {
+    cacheAnonymousId('');
+
+    expect(existsSync(anonymousIdFile)).toBe(false);
+  });
 });

packages/cli/src/__tests__/utils/telemetry.test.ts

@@ -42,19 +42,22 @@ describe('commandWrapper', () => {
     await wrappedHandler({} as any);
     expect(handleLint).toHaveBeenCalledTimes(1);
     expect(sendTelemetry).toHaveBeenCalledTimes(1);
-    expect(sendTelemetry).toHaveBeenCalledWith({
-      config: {
-        resolvedConfig: {
-          telemetry: 'on',
+    expect(sendTelemetry).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: {
+          resolvedConfig: {
+            telemetry: 'on',
+          },
         },
-      },
-      argv: {},
-      exit_code: 0,
-      spec_version: 'oas3_1',
-      spec_keyword: 'openapi',
-      spec_full_version: '3.1.0',
-      respect_x_security_auth_types: [],
-    });
+        argv: {},
+        execution_time: expect.any(Number),
+        exit_code: 0,
+        spec_version: 'oas3_1',
+        spec_keyword: 'openapi',
+        spec_full_version: '3.1.0',
+        respect_x_security_auth_types: [],
+      })
+    );
   });
 
   it('should not collect spec version if the file is not parsed to json', async () => {
@@ -70,19 +73,22 @@ describe('commandWrapper', () => {
     await wrappedHandler({} as any);
     expect(handleLint).toHaveBeenCalledTimes(1);
     expect(sendTelemetry).toHaveBeenCalledTimes(1);
-    expect(sendTelemetry).toHaveBeenCalledWith({
-      config: {
-        resolvedConfig: {
-          telemetry: 'on',
+    expect(sendTelemetry).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: {
+          resolvedConfig: {
+            telemetry: 'on',
+          },
         },
-      },
-      argv: {},
-      exit_code: 0,
-      spec_version: undefined,
-      spec_keyword: undefined,
-      spec_full_version: undefined,
-      respect_x_security_auth_types: [],
-    });
+        argv: {},
+        execution_time: expect.any(Number),
+        exit_code: 0,
+        spec_version: undefined,
+        spec_keyword: undefined,
+        spec_full_version: undefined,
+        respect_x_security_auth_types: [],
+      })
+    );
   });
 
   it('should NOT send telemetry if there is "telemetry: off" in the config', async () => {

packages/cli/src/__tests__/wrapper.test.ts

@@ -1,3 +1,4 @@
 export const OTEL_URL = 'https://otel.cloud.redocly.com';
 export const OTEL_TRACES_URL = process.env.OTEL_TRACES_URL || `${OTEL_URL}/v1/traces`;
 export const DEFAULT_FETCH_TIMEOUT = 3000;
+export const ANONYMOUS_ID_CACHE_FILE = 'redocly-cli-anonymous-id';

packages/cli/src/utils/constants.ts

@@ -4,19 +4,19 @@ import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
 import { version } from './package.js';
 import { OTEL_TRACES_URL, DEFAULT_FETCH_TIMEOUT } from './constants.js';
+import { ulid } from 'ulid';
 
-import type { Analytics } from './telemetry.js';
-
-type Events = {
-  [key: string]: Analytics;
-};
+import type { CloudEvents } from '@redocly/cli-otel';
 
 export class OtelServerTelemetry {
-  send<K extends keyof Events>(event: K, data: Events[K]): void {
-    const nodeTracerProvider = new NodeTracerProvider({
+  private nodeTracerProvider: NodeTracerProvider;
+
+  constructor() {
+    this.nodeTracerProvider = new NodeTracerProvider({
       resource: resourceFromAttributes({
         [ATTR_SERVICE_NAME]: `redocly-cli`,
         [ATTR_SERVICE_VERSION]: `@redocly/cli@${version}`,
+        session_id: `ses_${ulid()}`,
       }),
       spanProcessors: [
         new SimpleSpanProcessor(
@@ -28,23 +28,48 @@ export class OtelServerTelemetry {
         ),
       ],
     });
+  }
 
-    const time = new Date();
-    const eventId = crypto.randomUUID();
-    const tracer = nodeTracerProvider.getTracer('CliTelemetry');
-    const span = tracer.startSpan(`event.${event}`, {
-      attributes: {
-        'cloudevents.event_client.id': eventId,
-        'cloudevents.event_client.type': event,
-      },
-      startTime: time,
-    });
-    for (const [key, value] of Object.entries(data)) {
+  send(cloudEvent: CloudEvents.Messages): void {
+    const time = cloudEvent.time ? new Date(cloudEvent.time) : new Date();
+    const tracer = this.nodeTracerProvider.getTracer('CliTelemetry');
+    const spanName = `event.${cloudEvent.data.command}`;
+
+    const attributes: Record<string, string | number | boolean | undefined> = {
+      'cloudevents.event_id': cloudEvent.id,
+      'cloudevents.event_type': cloudEvent.type,
+      'cloudevents.event_source': cloudEvent.source,
+      'cloudevents.event_spec_version': cloudEvent.specversion,
+      'cloudevents.productType': cloudEvent.productType,
+      'cloudevents.event_data_content_type':
+        cloudEvent.datacontenttype || 'application/json; charset=utf-8',
+      'cloudevents.event_time': time.toISOString(),
+      'cloudevents.event_version': '1.0.0',
+      'cloudevents.origin': cloudEvent.origin,
+      'cloudevents.project.id': '',
+      'cloudevents.project.slug': '',
+      'cloudevents.organization.id': '',
+      'cloudevents.organization.slug': '',
+      'cloudevents.event_origin': cloudEvent.productType,
+      'cloudevents.event_source_details.id': cloudEvent.sourceDetails?.id ?? `ann_${ulid()}`,
+      'cloudevents.event_source_details.object': cloudEvent.sourceDetails?.object ?? 'anonymous',
+      'cloudevents.event_source_details.uri': cloudEvent.sourceDetails?.uri ?? '',
+      'cloudevents.event_data.os_platform': cloudEvent.os_platform,
+      'cloudevents.event_data.environment': cloudEvent.environment,
+    };
+
+    for (const [key, value] of Object.entries(cloudEvent.data)) {
       const keySnakeCase = key.replace(/([A-Z])/g, '_$1').toLowerCase();
       if (value !== undefined) {
-        span.setAttribute(`cloudevents.event_data.${keySnakeCase}`, value);
+        attributes[`cloudevents.event_data.${keySnakeCase}`] = value;
       }
     }
+
+    const span = tracer.startSpan(spanName, {
+      attributes,
+      startTime: time,
+    });
+
     span.end(time);
   }
 }