Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

12.4 KB
Raw Blame
// Extend the Error interface to include errorId
declare global {
  interface Error {
    errorId?: string;
  }
}

import { ComposioError as ComposioClientError } from '@composio/client';
import { TELEMETRY_EVENTS, TelemetryMetadata } from '../types/telemetry.types';
import { getEnvVariable } from '../utils/env';
import { BatchProcessor } from './BatchProcessor';
import { ComposioError } from '../errors/ComposioError';
import { getRandomUUID } from '../utils/uuid';
import {
  TelemetryMetricPayloadBody,
  TelemetryMetricSource,
  TelemetryPayload,
} from '../services/telemetry/TelemetryService.types';
import { TelemetryService } from '../services/telemetry/TelemetryService';
import logger from '../utils/logger';
import { redactSensitiveText } from './redact';
/**
 * The Telemetry class is used to log the telemetry for any given instance which extends InstrumentedInstance.
 *
 * This class is used to instrument the telemetry for the given instance and send the telemetry to the server.
 * This class is also used to create a global error handler for the given instance.
 *
 * @example
 *
 * const telemetry = new Telemetry({...});
 * const composio = new Composio({...})
 *
 * telemetry.instrument(composio);
 * telemetry.instrument(composio.tools);
 * telemetry.instrument(composio.toolkits);
 * telemetry.instrument(composio.triggers);
 *
 */
export class TelemetryTransport {
  private telemetryMetadata!: TelemetryMetadata;
  private isTelemetryDisabled: boolean = true;
  private telemetrySource!: TelemetryMetricSource;
  private readonly telemetrySourceName = 'typescript-sdk';
  private readonly telemetryServiceName = 'sdk';
  private readonly telemetryLanguage = 'typescript';
  private exitHandlersRegistered = false;
  private pendingImmediateTelemetry: Set<Promise<void>> = new Set();

  private batchProcessor = new BatchProcessor(200, 10, async (data: TelemetryMetricPayloadBody) => {
    logger.debug('Sending batch of telemetry metrics', data);
    await TelemetryService.sendMetric(data as TelemetryPayload[]);
  });

  setup(metadata: TelemetryMetadata) {
    this.telemetryMetadata = metadata;
    this.isTelemetryDisabled = false;
    this.telemetrySource = {
      host: this.telemetryMetadata?.host ?? this.telemetrySourceName,
      service: this.telemetryServiceName,
      language: this.telemetryLanguage,
      version: this.telemetryMetadata?.version,
      platform: this.telemetryMetadata?.isBrowser ? 'browser' : 'node',
      environment: getEnvVariable('NODE_ENV', 'production') as TelemetryMetricSource['environment'],
    };
    // Register exit handlers to automatically flush telemetry before process exit
    this.registerExitHandlers();

    // send telemetry event for SDK initialization without blocking setup
    this.deferTelemetry(() =>
      this.sendMetric([
        {
          functionName: TELEMETRY_EVENTS.SDK_INITIALIZED,
          durationMs: 0,
          timestamp: Date.now() / 1000,
          props: {},
          source: this.telemetrySource,
          metadata: {
            provider: this.telemetryMetadata?.provider ?? 'openai',
          },
          error: undefined,
        },
      ])
    );
  }

  /**
   * Instrument the telemetry for the given instance.
   *
   * You can pass the instance and the file name of the instance to instrument the telemetry.
   * This will instrument all the methods of the instance and log the telemetry for each method call.
   * @param instance - any instance that extends InstrumentedInstance
   * @param fileName - the file name of the instance
   * @returns
   */
  instrument<T extends object>(instance: T, fileName?: string) {
    const proto = Object.getPrototypeOf(instance);
    const methodNames = Object.getOwnPropertyNames(proto).filter(key => {
      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
      return (
        key !== 'constructor' &&
        descriptor &&
        typeof descriptor.value === 'function' &&
        descriptor.value.constructor.name === 'AsyncFunction'
      );
    });
    // prioritize the explicitly passed class name, then fall back to constructor name, then 'unknown'
    const instrumentedClassName = fileName ?? instance.constructor?.name ?? 'unknown';

    for (const name of methodNames) {
      const originalMethod = (instance as unknown as Record<string, Function>)[name] as (
        ...args: unknown[]
      ) => Promise<unknown>;

      (instance as unknown as Record<string, Function>)[name] = async (...args: unknown[]) => {
        // Check telemetry status once at the start to ensure consistent behavior
        const telemetryEnabled = this.shouldSendTelemetry();
        const startTime = telemetryEnabled ? Date.now() : undefined;

        try {
          const result = await originalMethod.apply(instance, args);

          // Only collect telemetry if setup() has been called (telemetry is enabled)
          if (telemetryEnabled && startTime !== undefined) {
            const durationMs = Date.now() - startTime;
            const telemetryPayload: TelemetryPayload = {
              functionName: `${instrumentedClassName}.${name}`,
              durationMs,
              timestamp: startTime / 1000,
              props: {
                fileName: instrumentedClassName,
                method: name,
              },
              metadata: {
                provider: this.telemetryMetadata?.provider ?? 'openai',
              },
              error: undefined,
              source: this.telemetrySource,
            };

            this.batchProcessor.pushItem(telemetryPayload);
          }

          return result;
        } catch (error) {
          if (error instanceof Error) {
            if (!error.errorId) {
              error.errorId = getRandomUUID();
              // Only send error telemetry if telemetry is enabled
              if (telemetryEnabled && startTime !== undefined) {
                const durationMs = Date.now() - startTime;
                this.prepareAndSendErrorTelemetry(
                  error,
                  instrumentedClassName,
                  name,
                  startTime,
                  durationMs
                );
              }
            }
          }
          throw error;
        }
      };
    }

    return instance;
  }

  /**
   * Check if the telemetry should be sent.
   * @returns true if the telemetry should be sent, false otherwise
   */
  private shouldSendTelemetry() {
    const telemetryDisabledEnvironments = ['test', 'ci'];
    const nodeEnv = (getEnvVariable('NODE_ENV', 'development') || '').toLowerCase();
    const isDisabledEnvironment = telemetryDisabledEnvironments.includes(nodeEnv);
    const isTelemetryDisabledByEnv = getEnvVariable('TELEMETRY_DISABLED', 'false') === 'true';

    return !this.isTelemetryDisabled && !isTelemetryDisabledByEnv && !isDisabledEnvironment;
  }

  /**
   * Prepare and send the error telemetry.
   *
   * @param {unknown} error - The error to send.
   * @param {string} instrumentedClassName - The class name of the instrumented class.
   * @param {string} name - The name of the method that threw the error.
   * @param {number} startTime - The start time of the method invocation in milliseconds.
   * @param {number} durationMs - The duration of the method invocation in milliseconds.
   */
  private prepareAndSendErrorTelemetry(
    error: unknown,
    instrumentedClassName: string,
    name: string,
    startTime: number,
    durationMs: number
  ) {
    const telemetryPayload: TelemetryPayload = {
      functionName: `${instrumentedClassName}.${name}`,
      durationMs,
      timestamp: startTime / 1000,
      props: {
        fileName: instrumentedClassName,
        method: name,
      },
      metadata: {
        provider: this.telemetryMetadata?.provider ?? 'openai',
      },
      source: this.telemetrySource,
    };
    // Redact secrets (URLs with tokens, Authorization headers, API keys, etc.)
    // from free-form error text before it is transported off-process.
    // client error, this is likely handled by the API itseld
    if (error instanceof ComposioClientError) {
      telemetryPayload.error = {
        errorId: error.errorId,
        name: error.name,
        message: redactSensitiveText(error.message),
        stack: redactSensitiveText(error.stack),
      };
    } else if (error instanceof ComposioError) {
      telemetryPayload.error = {
        errorId: error.errorId,
        name: error.name,
        code: error.code,
        message: redactSensitiveText(error.message),
        stack: redactSensitiveText(error.stack),
      };
    } else if (error instanceof Error) {
      telemetryPayload.error = {
        errorId: error.errorId,
        name: error.name ?? 'Unknown error',
        message: redactSensitiveText(error.message),
        stack: redactSensitiveText(error.stack),
      };
    }

    this.deferTelemetry(() => this.sendErrorTelemetry(telemetryPayload));
  }

  private deferTelemetry(callback: () => Promise<void>): void {
    const pending = new Promise<void>(resolve => {
      const run = () => {
        Promise.resolve()
          .then(callback)
          .catch(error => {
            logger.debug('Error sending deferred telemetry', error);
          })
          .finally(resolve);
      };

      if (typeof queueMicrotask === 'function') {
        queueMicrotask(run);
      } else {
        setTimeout(run, 0);
      }
    });

    this.pendingImmediateTelemetry.add(pending);
    pending.finally(() => {
      this.pendingImmediateTelemetry.delete(pending);
    });
  }

  private async flushImmediateTelemetry(): Promise<void> {
    while (this.pendingImmediateTelemetry.size > 0) {
      await Promise.all(Array.from(this.pendingImmediateTelemetry));
    }
  }

  /**
   * Send the telemetry payload to the server.
   * @param payload - the telemetry payload to send
   * @returns
   */
  async sendMetric(payload: TelemetryMetricPayloadBody) {
    if (!this.shouldSendTelemetry()) {
      logger.debug('Telemetry is disabled, skipping metric telemetry', payload);
      return;
    }
    try {
      logger.debug('SDK Metric', payload);
      await TelemetryService.sendMetric(payload);
    } catch (error) {
      logger.error('Error sending metric telemetry', error);
    }
  }
  // @TODO: check if this will send the error telemetry to the server
  async sendErrorTelemetry(payload: TelemetryPayload) {
    if (!this.shouldSendTelemetry()) {
      logger.debug('Telemetry is disabled, skipping metric telemetry', payload);
      return;
    }
    try {
      logger.debug('SDK Error Telemetry', payload);
      await TelemetryService.sendErrorLog(payload);
    } catch (error) {
      logger.error('Error sending error telemetry', error);
    }
  }

  /**
   * Flush any pending telemetry and wait for it to complete.
   * This is automatically called on process exit in Node.js environments.
   */
  async flush(): Promise<void> {
    await this.batchProcessor.flush();
    await this.flushImmediateTelemetry();
  }

  /**
   * Register process exit handlers to automatically flush telemetry.
   * Only registers handlers in Node.js environments (not in browsers).
   */
  private registerExitHandlers(): void {
    // Only register once and only in Node.js environments
    if (this.exitHandlersRegistered || typeof process === 'undefined' || !process.on) {
      return;
    }

    this.exitHandlersRegistered = true;

    const flushSync = () => {
      // Use a flag to track if we're already flushing to prevent double-flush
      this.flush().catch(error => {
        logger.debug('Error flushing telemetry on exit', error);
      });
    };

    // beforeExit is emitted when Node.js empties its event loop and has nothing else to schedule
    // This is the best place to flush async operations
    process.on('beforeExit', () => {
      flushSync();
    });

    // Handle SIGINT (Ctrl+C) and SIGTERM (kill command)
    // Store handler references so they can be properly removed
    const createSignalHandler = (signal: NodeJS.Signals) => {
      const handler = () => {
        logger.debug(`Received ${signal}, flushing telemetry...`);
        this.flush()
          .catch(error => {
            logger.debug('Error flushing telemetry on signal', error);
          })
          .finally(() => {
            // Remove the handler before re-emitting to prevent infinite loop
            process.removeListener(signal, handler);
            process.kill(process.pid, signal);
          });
      };
      return handler;
    };

    process.on('SIGINT', createSignalHandler('SIGINT'));
    process.on('SIGTERM', createSignalHandler('SIGTERM'));
  }
}

export const telemetry = new TelemetryTransport();