@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
ts 361 lines 12.6 KB
Raw
1 // Extend the Error interface to include errorId
2 declare global {
3 interface Error {
4 errorId?: string;
5 }
6 }
7
8 import { ComposioError as ComposioClientError } from '@composio/client';
9 import { TELEMETRY_EVENTS, TelemetryMetadata } from '../types/telemetry.types';
10 import { getEnvVariable } from '../utils/env';
11 import { BatchProcessor } from './BatchProcessor';
12 import { ComposioError } from '../errors/ComposioError';
13 import { getRandomUUID } from '../utils/uuid';
14 import {
15 TelemetryMetricPayloadBody,
16 TelemetryMetricSource,
17 TelemetryPayload,
18 } from '../services/telemetry/TelemetryService.types';
19 import { TelemetryService } from '../services/telemetry/TelemetryService';
20 import logger from '../utils/logger';
21 import { redactSensitiveText } from './redact';
22 /**
23 * The Telemetry class is used to log the telemetry for any given instance which extends InstrumentedInstance.
24 *
25 * This class is used to instrument the telemetry for the given instance and send the telemetry to the server.
26 * This class is also used to create a global error handler for the given instance.
27 *
28 * @example
29 *
30 * const telemetry = new Telemetry({...});
31 * const composio = new Composio({...})
32 *
33 * telemetry.instrument(composio);
34 * telemetry.instrument(composio.tools);
35 * telemetry.instrument(composio.toolkits);
36 * telemetry.instrument(composio.triggers);
37 *
38 */
39 export class TelemetryTransport {
40 private telemetryMetadata!: TelemetryMetadata;
41 private isTelemetryDisabled: boolean = true;
42 private telemetrySource!: TelemetryMetricSource;
43 private readonly telemetrySourceName = 'typescript-sdk';
44 private readonly telemetryServiceName = 'sdk';
45 private readonly telemetryLanguage = 'typescript';
46 private exitHandlersRegistered = false;
47 private pendingImmediateTelemetry: Set<Promise<void>> = new Set();
48
49 private batchProcessor = new BatchProcessor(200, 10, async (data: TelemetryMetricPayloadBody) => {
50 logger.debug('Sending batch of telemetry metrics', data);
51 await TelemetryService.sendMetric(data as TelemetryPayload[]);
52 });
53
54 setup(metadata: TelemetryMetadata) {
55 this.telemetryMetadata = metadata;
56 this.isTelemetryDisabled = false;
57 this.telemetrySource = {
58 host: this.telemetryMetadata?.host ?? this.telemetrySourceName,
59 service: this.telemetryServiceName,
60 language: this.telemetryLanguage,
61 version: this.telemetryMetadata?.version,
62 platform: this.telemetryMetadata?.isBrowser ? 'browser' : 'node',
63 environment: getEnvVariable('NODE_ENV', 'production') as TelemetryMetricSource['environment'],
64 };
65 // Register exit handlers to automatically flush telemetry before process exit
66 this.registerExitHandlers();
67
68 // send telemetry event for SDK initialization without blocking setup
69 this.deferTelemetry(() =>
70 this.sendMetric([
71 {
72 functionName: TELEMETRY_EVENTS.SDK_INITIALIZED,
73 durationMs: 0,
74 timestamp: Date.now() / 1000,
75 props: {},
76 source: this.telemetrySource,
77 metadata: {
78 provider: this.telemetryMetadata?.provider ?? 'openai',
79 },
80 error: undefined,
81 },
82 ])
83 );
84 }
85
86 /**
87 * Instrument the telemetry for the given instance.
88 *
89 * You can pass the instance and the file name of the instance to instrument the telemetry.
90 * This will instrument all the methods of the instance and log the telemetry for each method call.
91 * @param instance - any instance that extends InstrumentedInstance
92 * @param fileName - the file name of the instance
93 * @returns
94 */
95 instrument<T extends object>(instance: T, fileName?: string) {
96 const proto = Object.getPrototypeOf(instance);
97 // Objects returned by factory functions carry their methods as own properties.
98 const methodSource = proto === Object.prototype || proto === null ? instance : proto;
99 const methodNames = Object.getOwnPropertyNames(methodSource).filter(key => {
100 const descriptor = Object.getOwnPropertyDescriptor(methodSource, key);
101 return (
102 key !== 'constructor' &&
103 descriptor &&
104 typeof descriptor.value === 'function' &&
105 descriptor.value.constructor.name === 'AsyncFunction'
106 );
107 });
108 // prioritize the explicitly passed class name, then fall back to constructor name, then 'unknown'
109 const instrumentedClassName = fileName ?? instance.constructor?.name ?? 'unknown';
110
111 for (const name of methodNames) {
112 const originalMethod = (instance as unknown as Record<string, Function>)[name] as (
113 ...args: unknown[]
114 ) => Promise<unknown>;
115
116 (instance as unknown as Record<string, Function>)[name] = async (...args: unknown[]) => {
117 // Check telemetry status once at the start to ensure consistent behavior
118 const telemetryEnabled = this.shouldSendTelemetry();
119 const startTime = telemetryEnabled ? Date.now() : undefined;
120
121 try {
122 const result = await originalMethod.apply(instance, args);
123
124 // Only collect telemetry if setup() has been called (telemetry is enabled)
125 if (telemetryEnabled && startTime !== undefined) {
126 const durationMs = Date.now() - startTime;
127 const telemetryPayload: TelemetryPayload = {
128 functionName: `${instrumentedClassName}.${name}`,
129 durationMs,
130 timestamp: startTime / 1000,
131 props: {
132 fileName: instrumentedClassName,
133 method: name,
134 },
135 metadata: {
136 provider: this.telemetryMetadata?.provider ?? 'openai',
137 },
138 error: undefined,
139 source: this.telemetrySource,
140 };
141
142 this.batchProcessor.pushItem(telemetryPayload);
143 }
144
145 return result;
146 } catch (error) {
147 if (error instanceof Error) {
148 if (!error.errorId) {
149 error.errorId = getRandomUUID();
150 // Only send error telemetry if telemetry is enabled
151 if (telemetryEnabled && startTime !== undefined) {
152 const durationMs = Date.now() - startTime;
153 this.prepareAndSendErrorTelemetry(
154 error,
155 instrumentedClassName,
156 name,
157 startTime,
158 durationMs
159 );
160 }
161 }
162 }
163 throw error;
164 }
165 };
166 }
167
168 return instance;
169 }
170
171 /**
172 * Check if the telemetry should be sent.
173 * @returns true if the telemetry should be sent, false otherwise
174 */
175 private shouldSendTelemetry() {
176 const telemetryDisabledEnvironments = ['test', 'ci'];
177 const nodeEnv = (getEnvVariable('NODE_ENV', 'development') || '').toLowerCase();
178 const isDisabledEnvironment = telemetryDisabledEnvironments.includes(nodeEnv);
179 const isTelemetryDisabledByEnv = getEnvVariable('TELEMETRY_DISABLED', 'false') === 'true';
180
181 return !this.isTelemetryDisabled && !isTelemetryDisabledByEnv && !isDisabledEnvironment;
182 }
183
184 /**
185 * Prepare and send the error telemetry.
186 *
187 * @param {unknown} error - The error to send.
188 * @param {string} instrumentedClassName - The class name of the instrumented class.
189 * @param {string} name - The name of the method that threw the error.
190 * @param {number} startTime - The start time of the method invocation in milliseconds.
191 * @param {number} durationMs - The duration of the method invocation in milliseconds.
192 */
193 private prepareAndSendErrorTelemetry(
194 error: unknown,
195 instrumentedClassName: string,
196 name: string,
197 startTime: number,
198 durationMs: number
199 ) {
200 const telemetryPayload: TelemetryPayload = {
201 functionName: `${instrumentedClassName}.${name}`,
202 durationMs,
203 timestamp: startTime / 1000,
204 props: {
205 fileName: instrumentedClassName,
206 method: name,
207 },
208 metadata: {
209 provider: this.telemetryMetadata?.provider ?? 'openai',
210 },
211 source: this.telemetrySource,
212 };
213 // Redact secrets (URLs with tokens, Authorization headers, API keys, etc.)
214 // from free-form error text before it is transported off-process.
215 // client error, this is likely handled by the API itseld
216 if (error instanceof ComposioClientError) {
217 telemetryPayload.error = {
218 errorId: error.errorId,
219 name: error.name,
220 message: redactSensitiveText(error.message),
221 stack: redactSensitiveText(error.stack),
222 };
223 } else if (error instanceof ComposioError) {
224 telemetryPayload.error = {
225 errorId: error.errorId,
226 name: error.name,
227 code: error.code,
228 message: redactSensitiveText(error.message),
229 stack: redactSensitiveText(error.stack),
230 };
231 } else if (error instanceof Error) {
232 telemetryPayload.error = {
233 errorId: error.errorId,
234 name: error.name ?? 'Unknown error',
235 message: redactSensitiveText(error.message),
236 stack: redactSensitiveText(error.stack),
237 };
238 }
239
240 this.deferTelemetry(() => this.sendErrorTelemetry(telemetryPayload));
241 }
242
243 private deferTelemetry(callback: () => Promise<void>): void {
244 const pending = new Promise<void>(resolve => {
245 const run = () => {
246 Promise.resolve()
247 .then(callback)
248 .catch(error => {
249 logger.debug('Error sending deferred telemetry', error);
250 })
251 .finally(resolve);
252 };
253
254 if (typeof queueMicrotask === 'function') {
255 queueMicrotask(run);
256 } else {
257 setTimeout(run, 0);
258 }
259 });
260
261 this.pendingImmediateTelemetry.add(pending);
262 pending.finally(() => {
263 this.pendingImmediateTelemetry.delete(pending);
264 });
265 }
266
267 private async flushImmediateTelemetry(): Promise<void> {
268 while (this.pendingImmediateTelemetry.size > 0) {
269 await Promise.all(Array.from(this.pendingImmediateTelemetry));
270 }
271 }
272
273 /**
274 * Send the telemetry payload to the server.
275 * @param payload - the telemetry payload to send
276 * @returns
277 */
278 async sendMetric(payload: TelemetryMetricPayloadBody) {
279 if (!this.shouldSendTelemetry()) {
280 logger.debug('Telemetry is disabled, skipping metric telemetry', payload);
281 return;
282 }
283 try {
284 logger.debug('SDK Metric', payload);
285 await TelemetryService.sendMetric(payload);
286 } catch (error) {
287 logger.error('Error sending metric telemetry', error);
288 }
289 }
290 // @TODO: check if this will send the error telemetry to the server
291 async sendErrorTelemetry(payload: TelemetryPayload) {
292 if (!this.shouldSendTelemetry()) {
293 logger.debug('Telemetry is disabled, skipping metric telemetry', payload);
294 return;
295 }
296 try {
297 logger.debug('SDK Error Telemetry', payload);
298 await TelemetryService.sendErrorLog(payload);
299 } catch (error) {
300 logger.error('Error sending error telemetry', error);
301 }
302 }
303
304 /**
305 * Flush any pending telemetry and wait for it to complete.
306 * This is automatically called on process exit in Node.js environments.
307 */
308 async flush(): Promise<void> {
309 await this.batchProcessor.flush();
310 await this.flushImmediateTelemetry();
311 }
312
313 /**
314 * Register process exit handlers to automatically flush telemetry.
315 * Only registers handlers in Node.js environments (not in browsers).
316 */
317 private registerExitHandlers(): void {
318 // Only register once and only in Node.js environments
319 if (this.exitHandlersRegistered || typeof process === 'undefined' || !process.on) {
320 return;
321 }
322
323 this.exitHandlersRegistered = true;
324
325 const flushSync = () => {
326 // Use a flag to track if we're already flushing to prevent double-flush
327 this.flush().catch(error => {
328 logger.debug('Error flushing telemetry on exit', error);
329 });
330 };
331
332 // beforeExit is emitted when Node.js empties its event loop and has nothing else to schedule
333 // This is the best place to flush async operations
334 process.on('beforeExit', () => {
335 flushSync();
336 });
337
338 // Handle SIGINT (Ctrl+C) and SIGTERM (kill command)
339 // Store handler references so they can be properly removed
340 const createSignalHandler = (signal: NodeJS.Signals) => {
341 const handler = () => {
342 logger.debug(`Received ${signal}, flushing telemetry...`);
343 this.flush()
344 .catch(error => {
345 logger.debug('Error flushing telemetry on signal', error);
346 })
347 .finally(() => {
348 // Remove the handler before re-emitting to prevent infinite loop
349 process.removeListener(signal, handler);
350 process.kill(process.pid, signal);
351 });
352 };
353 return handler;
354 };
355
356 process.on('SIGINT', createSignalHandler('SIGINT'));
357 process.on('SIGTERM', createSignalHandler('SIGTERM'));
358 }
359 }
360
361 export const telemetry = new TelemetryTransport();