@devries-cameron20 / composio Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
md 261 lines 7.75 KB
Rendered Raw
1 # Telemetry in Composio SDK
2
3 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.
4
5 ## Overview
6
7 The telemetry system in Composio SDK is:
8
9 - **Opt-out**: Enabled by default but can be disabled
10 - **Privacy-focused**: Does not collect personal or sensitive information
11 - **Transparent**: Clear about what data is collected
12 - **Configurable**: Custom transports can be provided
13
14 ## Telemetry Data
15
16 The telemetry system collects the following types of data:
17
18 - **SDK Usage**: API calls, method invocations, error counts
19 - **Performance Metrics**: Response times, success/failure rates
20 - **Environment Information**: SDK version, provider used, runtime context
21
22 No personal or sensitive information such as:
23
24 - API keys
25 - Tool arguments
26 - Tool responses
27 - User IDs
28 - Connected account details
29
30 ## Disabling Telemetry
31
32 You can disable telemetry when initializing the SDK:
33
34 ```typescript
35 import { Composio } from '@composio/core';
36
37 const composio = new Composio({
38 apiKey: 'your-api-key',
39 allowTracking: false, // Disable telemetry
40 });
41 ```
42
43 Or by setting an environment variable:
44
45 ```bash
46 # In your .env file or environment
47 COMPOSIO_DISABLE_TELEMETRY=true
48 ```
49
50 ## Custom Telemetry Transport
51
52 For advanced use cases, you can provide a custom telemetry transport to process the telemetry data according to your needs:
53
54 ```typescript
55 import { Composio, BaseTelemetryTransport, TelemetryEvent } from '@composio/core';
56
57 // Create a custom telemetry transport
58 class CustomTelemetryTransport extends BaseTelemetryTransport {
59 async send(event: TelemetryEvent): Promise<void> {
60 // Process the telemetry event
61 console.log(`Telemetry event: ${event.name}`, event.properties);
62
63 // You can send it to your own analytics system
64 await yourAnalyticsSystem.track(event.name, event.properties);
65 }
66
67 async flush(): Promise<void> {
68 // Clean up any pending events
69 await yourAnalyticsSystem.flush();
70 }
71 }
72
73 // Use the custom transport
74 const composio = new Composio({
75 apiKey: 'your-api-key',
76 telemetryTransport: new CustomTelemetryTransport(),
77 });
78 ```
79
80 ## Implementing a Custom Transport
81
82 To implement a custom telemetry transport, extend the `BaseTelemetryTransport` class:
83
84 ```typescript
85 import { BaseTelemetryTransport, TelemetryEvent } from '@composio/core';
86
87 export class CustomTelemetryTransport extends BaseTelemetryTransport {
88 // Optional constructor for configuration
89 constructor(private config: { endpoint: string; batchSize: number }) {
90 super();
91 this.events = [];
92 }
93
94 // Local state for batching events
95 private events: TelemetryEvent[];
96
97 // Required: Implement the send method
98 async send(event: TelemetryEvent): Promise<void> {
99 // Add the event to the batch
100 this.events.push(event);
101
102 // If batch is full, flush it
103 if (this.events.length >= this.config.batchSize) {
104 await this.flush();
105 }
106 }
107
108 // Required: Implement the flush method
109 async flush(): Promise<void> {
110 if (this.events.length === 0) {
111 return;
112 }
113
114 try {
115 // Send the batch to your endpoint
116 await fetch(this.config.endpoint, {
117 method: 'POST',
118 headers: {
119 'Content-Type': 'application/json',
120 },
121 body: JSON.stringify({
122 events: this.events,
123 timestamp: new Date().toISOString(),
124 }),
125 });
126
127 // Clear the batch
128 this.events = [];
129 } catch (error) {
130 console.error('Failed to send telemetry:', error);
131 }
132 }
133 }
134 ```
135
136 ## Telemetry Events
137
138 The telemetry system instruments various parts of the SDK and emits events for different operations:
139
140 ### SDK Initialization
141
142 ```
143 event: "sdk_initialized"
144 properties:
145 framework: string // The provider name
146 isAgentic: boolean // Whether the provider is agentic
147 source: string // The runtime environment ("node" or "browser")
148 version: string // The SDK version
149 isBrowser: boolean // Whether the SDK is running in a browser
150 ```
151
152 ### Tool Operations
153
154 ```
155 event: "tools_get"
156 properties:
157 toolkit_slugs: string[] // The toolkit slugs used in the filter
158 tool_count: number // The number of tools returned
159 provider: string // The provider name
160
161 event: "tool_execute"
162 properties:
163 tool_slug: string // The slug of the executed tool
164 toolkit_slug: string // The toolkit slug of the executed tool
165 success: boolean // Whether the execution was successful
166 duration_ms: number // The execution duration in milliseconds
167 provider: string // The provider name
168 ```
169
170 ### Connected Account Operations
171
172 ```
173 event: "connected_account_initiate"
174 properties:
175 toolkit_slug: string // The toolkit slug
176 auth_config_id: string // The auth config ID
177
178 event: "connected_account_get"
179 properties:
180 success: boolean // Whether the operation was successful
181
182 event: "connected_account_list"
183 properties:
184 count: number // The number of connected accounts returned
185 success: boolean // Whether the operation was successful
186 ```
187
188 ### Toolkit Operations
189
190 ```
191 event: "toolkit_get"
192 properties:
193 success: boolean // Whether the operation was successful
194 toolkit_slug: string // The toolkit slug (if getting a specific toolkit)
195 toolkits_count: number // The number of toolkits returned (if getting multiple)
196 ```
197
198 ## Telemetry Processor
199
200 The SDK includes a batch processor for telemetry events that:
201
202 1. Buffers events to reduce API calls
203 2. Sends events in batches
204 3. Handles retries and failures
205 4. Automatically flushes at regular intervals
206 5. **Automatically flushes on process exit** (Node.js-compatible environments only) - handles `beforeExit`, `SIGINT`, and `SIGTERM` signals
207
208 This ensures that telemetry doesn't impact application performance and that all telemetry is sent before the process exits.
209
210 > **Note:** On Node.js-compatible environments, the SDK automatically registers exit handlers to ensure all pending telemetry is sent.
211
212 ### Cloudflare Workers and Edge Runtimes
213
214 In environments like Cloudflare Workers that don't support `process.on('beforeExit')`, you should manually flush telemetry using `ctx.waitUntil()`:
215
216 ```typescript
217 export default {
218 async fetch(request: Request, env: Env, ctx: ExecutionContext) {
219 const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });
220
221 // Do your work...
222 const result = await composio.tools.execute(...);
223
224 // Ensure telemetry flushes before worker terminates
225 ctx.waitUntil(composio.flush());
226
227 return new Response(JSON.stringify(result));
228 }
229 };
230 ```
231
232 ## Environment Context
233
234 The telemetry system automatically includes environment context with each event:
235
236 ```typescript
237 interface TelemetryMetadata {
238 apiKey: string; // The Composio API key (first 8 chars only, for identification)
239 baseUrl: string; // The Composio API base URL
240 framework: string; // The provider name
241 isAgentic: boolean; // Whether the provider is agentic
242 source: string; // The runtime environment
243 version: string; // The SDK version
244 isBrowser: boolean; // Whether the SDK is running in a browser
245 }
246 ```
247
248 ## Browser vs Node.js
249
250 The SDK automatically detects whether it's running in a browser or Node.js environment and uses the appropriate transport mechanism:
251
252 - In Node.js: Uses ProcessTransport with HTTP requests
253 - In Browser: Uses BrowserTransport with more browser-friendly approaches
254
255 ## Best Practices
256
257 1. **Leave telemetry enabled** if possible to help improve the SDK
258 2. If you need to **disable telemetry** for compliance reasons, use the `allowTracking: false` option
259 3. If you want to **process telemetry locally**, implement a custom transport
260 4. **Never log sensitive data** in your custom transports
261 5. If you **implement a custom provider**, set a meaningful name to improve telemetry insights