ts/docs/advanced/telemetry.md
Composio SDK includes a telemetry system to help improve the SDK and provide insights into usage patterns. This guide explains how telemetry works, what data is collected, how to customize it, and how to disable it if needed.
The telemetry system in Composio SDK is:
The telemetry system collects the following types of data:
No personal or sensitive information such as:
You can disable telemetry when initializing the SDK:
import { Composio } from '@composio/core';
const composio = new Composio({
apiKey: 'your-api-key',
allowTracking: false, // Disable telemetry
});
Or by setting an environment variable:
# In your .env file or environment
COMPOSIO_DISABLE_TELEMETRY=true
For advanced use cases, you can provide a custom telemetry transport to process the telemetry data according to your needs:
import { Composio, BaseTelemetryTransport, TelemetryEvent } from '@composio/core';
// Create a custom telemetry transport
class CustomTelemetryTransport extends BaseTelemetryTransport {
async send(event: TelemetryEvent): Promise<void> {
// Process the telemetry event
console.log(`Telemetry event: ${event.name}`, event.properties);
// You can send it to your own analytics system
await yourAnalyticsSystem.track(event.name, event.properties);
}
async flush(): Promise<void> {
// Clean up any pending events
await yourAnalyticsSystem.flush();
}
}
// Use the custom transport
const composio = new Composio({
apiKey: 'your-api-key',
telemetryTransport: new CustomTelemetryTransport(),
});
To implement a custom telemetry transport, extend the BaseTelemetryTransport class:
import { BaseTelemetryTransport, TelemetryEvent } from '@composio/core';
export class CustomTelemetryTransport extends BaseTelemetryTransport {
// Optional constructor for configuration
constructor(private config: { endpoint: string; batchSize: number }) {
super();
this.events = [];
}
// Local state for batching events
private events: TelemetryEvent[];
// Required: Implement the send method
async send(event: TelemetryEvent): Promise<void> {
// Add the event to the batch
this.events.push(event);
// If batch is full, flush it
if (this.events.length >= this.config.batchSize) {
await this.flush();
}
}
// Required: Implement the flush method
async flush(): Promise<void> {
if (this.events.length === 0) {
return;
}
try {
// Send the batch to your endpoint
await fetch(this.config.endpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
events: this.events,
timestamp: new Date().toISOString(),
}),
});
// Clear the batch
this.events = [];
} catch (error) {
console.error('Failed to send telemetry:', error);
}
}
}
The telemetry system instruments various parts of the SDK and emits events for different operations:
event: "sdk_initialized"
properties:
framework: string // The provider name
isAgentic: boolean // Whether the provider is agentic
source: string // The runtime environment ("node" or "browser")
version: string // The SDK version
isBrowser: boolean // Whether the SDK is running in a browser
event: "tools_get"
properties:
toolkit_slugs: string[] // The toolkit slugs used in the filter
tool_count: number // The number of tools returned
provider: string // The provider name
event: "tool_execute"
properties:
tool_slug: string // The slug of the executed tool
toolkit_slug: string // The toolkit slug of the executed tool
success: boolean // Whether the execution was successful
duration_ms: number // The execution duration in milliseconds
provider: string // The provider name
event: "connected_account_initiate"
properties:
toolkit_slug: string // The toolkit slug
auth_config_id: string // The auth config ID
event: "connected_account_get"
properties:
success: boolean // Whether the operation was successful
event: "connected_account_list"
properties:
count: number // The number of connected accounts returned
success: boolean // Whether the operation was successful
event: "toolkit_get"
properties:
success: boolean // Whether the operation was successful
toolkit_slug: string // The toolkit slug (if getting a specific toolkit)
toolkits_count: number // The number of toolkits returned (if getting multiple)
The SDK includes a batch processor for telemetry events that:
beforeExit, SIGINT, and SIGTERM signalsThis ensures that telemetry doesn't impact application performance and that all telemetry is sent before the process exits.
Note: On Node.js-compatible environments, the SDK automatically registers exit handlers to ensure all pending telemetry is sent.
In environments like Cloudflare Workers that don't support process.on('beforeExit'), you should manually flush telemetry using ctx.waitUntil():
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });
// Do your work...
const result = await composio.tools.execute(...);
// Ensure telemetry flushes before worker terminates
ctx.waitUntil(composio.flush());
return new Response(JSON.stringify(result));
}
};
The telemetry system automatically includes environment context with each event:
interface TelemetryMetadata {
apiKey: string; // The Composio API key (first 8 chars only, for identification)
baseUrl: string; // The Composio API base URL
framework: string; // The provider name
isAgentic: boolean; // Whether the provider is agentic
source: string; // The runtime environment
version: string; // The SDK version
isBrowser: boolean; // Whether the SDK is running in a browser
}
The SDK automatically detects whether it's running in a browser or Node.js environment and uses the appropriate transport mechanism:
allowTracking: false option