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

> Understand how Composio SDK telemetry tracking works. Discover its architecture, auto-instrumentation, and data transmission for insightful monitoring. Learn how to implement it.

- Repository: [Composio/composio](https://github.com/composiohq/composio)
- Tags: architecture
- Published: 2026-02-19

---

**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`](https://github.com/ComposioHQ/composio/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/ComposioHQ/composio/blob/main/src/telemetry/Telemetry.ts)**: Core `TelemetryTransport` class implementing instrumentation, batching, and exit handlers
- **[`src/services/telemetry/TelemetryService.ts`](https://github.com/ComposioHQ/composio/blob/main/src/services/telemetry/TelemetryService.ts)**: HTTP client for transmitting metrics and errors to the backend
- **[`src/telemetry/BatchProcessor.ts`](https://github.com/ComposioHQ/composio/blob/main/src/telemetry/BatchProcessor.ts)**: Utility for aggregating payloads and managing flush intervals
- **[`src/types/telemetry.types.ts`](https://github.com/ComposioHQ/composio/blob/main/src/types/telemetry.types.ts)**: TypeScript definitions for `TelemetryMetadata`, `TelemetryPayload`, and related interfaces
- **[`src/utils/env.ts`](https://github.com/ComposioHQ/composio/blob/main/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`](https://github.com/ComposioHQ/composio/blob/main/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`](https://github.com/ComposioHQ/composio/blob/main/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.