How Telemetry Tracking Works in the Composio SDK: Architecture and Implementation

The Composio SDK implements telemetry tracking through a singleton TelemetryTransport class that automatically instruments async methods, batches metric payloads (200 items or every 10 seconds), and transmits data to the Composio backend while respecting environment-based opt-out flags.

The Composio SDK provides built-in telemetry tracking that monitors SDK usage patterns and error conditions without requiring manual instrumentation. This transparent, opt-out system captures method execution times, argument metadata, and error traces through the TelemetryTransport class implemented in src/telemetry/Telemetry.ts. Understanding how telemetry tracking works in the Composio SDK helps developers control data privacy, debug integration issues, and optimize application performance.

Core Architecture of the TelemetryTransport Class

The telemetry system centers on the TelemetryTransport class, exposed as the singleton telemetry instance. This class orchestrates data collection, batching, and transmission while providing hooks for graceful shutdown handling.

Singleton Pattern and Metadata Management

The transport maintains SDK-level metadata including host environment, version, and provider information. When initialized via telemetry.setup(metadata), the system stores this contextual data to enrich every subsequent telemetry payload sent to the Composio backend.

Initialization and the BatchProcessor

The setup() method initializes the telemetry pipeline through several coordinated steps:

1. Metadata Configuration: Sets host, version, provider, and browser flags【L52-L60】
2. Batch Processing: Instantiates a BatchProcessor configured to flush either every 200 items or every 10 seconds【L47-L50】
3. Process Lifecycle Management: Registers Node.js exit handlers (beforeExit, SIGINT, SIGTERM) to ensure pending telemetry flushes before process termination【L85-L104】【L108-L126】
4. Initialization Event: Transmits a one-time "SDK_INITIALIZED" event to signal client startup【L66-L79】

The BatchProcessor aggregates metric payloads and invokes the provided callback, which forwards batches to TelemetryService.sendMetric while logging debug information【L48-L49】.

Automatic Method Instrumentation

The instrument() method enables transparent monitoring of SDK objects by wrapping their async methods:

telemetry.instrument(composioInstance, 'Composio');
telemetry.instrument(composioInstance.tools, 'Tools');

Prototype Scanning and Method Wrapping

The instrumentation process scans the prototype of the supplied instance to identify async methods【L92-L100】. Each discovered method is wrapped to:

• Check shouldSendTelemetry() before execution to respect global enable/disable flags【L111-L112】
• Capture start time, execute the original method, and construct a TelemetryPayload containing method name, duration, timestamp, arguments, and provider metadata【L119-L135】
• Push the payload into the batch processor queue for later transmission【L137-L138】

Error Telemetry and Immediate Reporting

When instrumented methods throw errors, the system bypasses batching to send error details immediately:

• Generates an errorId using getRandomUUID() if missing【L140-L158】
• Assembles an error-telemetry payload including stack trace, error name, and contextual metadata
• Invokes prepareAndSendErrorTelemetry followed by sendErrorTelemetry, which ultimately calls TelemetryService.sendErrorLog【L65-L68】【L190-L213】

This immediate transmission ensures critical failure data reaches the backend even if the process terminates abruptly before the next batch flush.

Controlling Telemetry with Environment Variables

The shouldSendTelemetry() method implements a hierarchical opt-out system:

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;
}

Telemetry tracking is automatically disabled when:

• NODE_ENV is set to test or ci
• TELEMETRY_DISABLED environment variable equals true
• The SDK has not been initialized via setup() (internal isTelemetryDisabled flag remains true)

Implementation Example

The following example demonstrates complete telemetry initialization and instrumentation according to the Composio SDK source code:

import { Composio } from '@composio/core';
import { telemetry } from '@composio/core/src/telemetry/Telemetry';

// Initialize the SDK and telemetry
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
telemetry.setup({
  host: 'my-app',
  version: '1.2.3',
  provider: 'openai',
  isBrowser: false,
});

// Instrument SDK components
telemetry.instrument(composio);
telemetry.instrument(composio.tools);
telemetry.instrument(composio.toolkits);
telemetry.instrument(composio.triggers);

// Execute operations - telemetry is captured automatically
await composio.tools.execute('GITHUB_CREATE_REPO', {
  userId: '123',
  arguments: { name: 'example-repo', private: true },
});

// Manual flush (optional - automatic on process exit)
await telemetry.flush();

// Disable for testing
process.env.TELEMETRY_DISABLED = 'true';

Key Source Files

The telemetry implementation spans several modules in the Composio repository:

• src/telemetry/Telemetry.ts: Core TelemetryTransport class implementing instrumentation, batching, and exit handlers
• src/services/telemetry/TelemetryService.ts: HTTP client for transmitting metrics and errors to the backend
• src/telemetry/BatchProcessor.ts: Utility for aggregating payloads and managing flush intervals
• src/types/telemetry.types.ts: TypeScript definitions for TelemetryMetadata, TelemetryPayload, and related interfaces
• src/utils/env.ts: Environment variable helpers for enable/disable logic

Summary

• TelemetryTransport operates as a singleton that instruments async methods transparently without requiring code changes
• BatchProcessor optimizes network usage by aggregating 200 metrics or flushing every 10 seconds, whichever comes first
• Environment-based opt-out automatically disables tracking in CI/test environments or when TELEMETRY_DISABLED=true
• Immediate error reporting bypasses batching to ensure critical failure data is captured without delay
• Process exit handlers guarantee telemetry delivery even during abrupt shutdowns via SIGINT and SIGTERM handlers

Frequently Asked Questions

How do I completely disable telemetry tracking in the Composio SDK?

Set the environment variable TELEMETRY_DISABLED=true before initializing the SDK. Alternatively, set NODE_ENV=test or NODE_ENV=ci, as these environments automatically suppress telemetry according to the shouldSendTelemetry() implementation in src/telemetry/Telemetry.ts.

What data does the Composio SDK collect through telemetry?

The SDK collects method execution duration, timestamps, argument metadata, provider information, and error stack traces. Specifically, the TelemetryPayload interface in src/types/telemetry.types.ts structures this data to include method names, host environment details, and version information without capturing sensitive API keys or user credentials.

Why are my telemetry events not appearing in the dashboard?

Ensure you have called telemetry.setup() with valid metadata before instrumenting objects. The internal isTelemetryDisabled flag remains true until initialization completes, preventing any data transmission. Additionally, verify that shouldSendTelemetry() returns true by checking that TELEMETRY_DISABLED is not set and NODE_ENV is not test or ci.

Does telemetry impact SDK performance?

The batching mechanism minimizes performance impact by aggregating up to 200 payloads or waiting 10 seconds between transmissions. Method wrapping adds minimal overhead—only checking shouldSendTelemetry() and capturing timestamps when enabled. Error telemetry sends immediately but only triggers during exception conditions, ensuring normal operations remain unaffected.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}