Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(ts/core): fix telemetry implementation handling multiple concurrent promises, add Node.js-specific auto-flush, with Cloudflare Workers escape hatch
jkomyno committed
Jan 7, 2026 at 07:18 UTC
1c773553981e921cbead72f026bae18d17df820b
5 files changed
+206
-13
ts/docs/advanced/telemetry.md
+24
-1
@@ -203,8 +203,31 @@ The SDK includes a batch processor for telemetry events that:
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
207
-This ensures that telemetry doesn't impact application performance.
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
ts/packages/core/src/composio.ts
+31
@@ -383,4 +383,35 @@ export class Composio<
383
defaultHeaders: sessionHeaders,
384
});
385
}
386
+
387
+ /**
388
+ * Flush any pending telemetry and wait for it to complete.
389
+ *
390
+ * In Node.js-compatible environments, telemetry is automatically flushed on process exit.
391
+ * However, in environments like Cloudflare Workers that don't support process exit events,
392
+ * you should call this method manually to ensure all telemetry is sent.
393
+ *
394
+ * @returns {Promise<void>} A promise that resolves when all pending telemetry has been sent.
395
+ *
396
+ * @example
397
+ * ```typescript
398
+ * // In a Cloudflare Worker, use ctx.waitUntil to ensure telemetry is flushed
399
+ * export default {
400
+ * async fetch(request: Request, env: Env, ctx: ExecutionContext) {
401
+ * const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });
402
+ *
403
+ * // Do your work...
404
+ * const result = await composio.tools.execute(...);
405
+ *
406
+ * // Ensure telemetry flushes before worker terminates
407
+ * ctx.waitUntil(composio.flush());
408
+ *
409
+ * return new Response(JSON.stringify(result));
410
+ * }
411
+ * };
412
+ * ```
413
+ */
414
+ async flush(): Promise<void> {
415
+ await telemetry.flush();
416
+ }
417
}
ts/packages/core/src/telemetry/BatchProcessor.ts
+6
-8
@@ -9,7 +9,7 @@ export class BatchProcessor {
9
private batchSize: number;
10
private processBatchCallback: (data: TelemetryMetricPayloadBody) => Promise<void>;
11
private timer: NodeJS.Timeout | null = null;
12
- private pendingFlush: Promise<void> | null = null;
12
+ private pendingBatches: Set<Promise<void>> = new Set();
13
14
constructor(
15
time: number = 2000,
@@ -40,12 +40,10 @@ export class BatchProcessor {
40
// Silently ignore errors - they should be handled by the callback
41
})
42
.finally(() => {
43
- if (this.pendingFlush === pending) {
44
- this.pendingFlush = null;
45
- }
43
+ this.pendingBatches.delete(pending);
44
});
45
48
- this.pendingFlush = pending;
46
+ this.pendingBatches.add(pending);
47
}
48
if (this.timer) {
49
clearTimeout(this.timer);
@@ -54,13 +52,13 @@ export class BatchProcessor {
52
}
53
54
/**
57
- * Flush any pending batch and wait for it to complete.
55
+ * Flush any pending batches and wait for all of them to complete.
56
* Useful for ensuring telemetry is sent before process exit.
57
*/
58
async flush(): Promise<void> {
59
this.processBatch();
62
- if (this.pendingFlush) {
63
- await this.pendingFlush;
60
+ if (this.pendingBatches.size > 0) {
61
+ await Promise.all(this.pendingBatches);
62
}
63
}
64
}
ts/packages/core/src/telemetry/Telemetry.ts
+48
-1
@@ -42,6 +42,7 @@ export class TelemetryTransport {
42
private readonly telemetrySourceName = 'typescript-sdk';
43
private readonly telemetryServiceName = 'sdk';
44
private readonly telemetryLanguage = 'typescript';
45
+ private exitHandlersRegistered = false;
46
47
private batchProcessor = new BatchProcessor(200, 10, async (data: TelemetryMetricPayloadBody) => {
48
logger.debug('Sending batch of telemetry metrics', data);
@@ -59,6 +60,9 @@ export class TelemetryTransport {
60
platform: this.telemetryMetadata?.isBrowser ? 'browser' : 'node',
61
environment: getEnvVariable('NODE_ENV', 'production') as TelemetryMetricSource['environment'],
62
};
63
+ // Register exit handlers to automatically flush telemetry before process exit
64
+ this.registerExitHandlers();
65
+
66
// send telemetry event for SDK initialization
67
this.sendMetric([
68
{
@@ -268,11 +272,54 @@ export class TelemetryTransport {
272
273
/**
274
* Flush any pending telemetry and wait for it to complete.
271
- * Call this before process exit to ensure all telemetry is sent.
275
+ * This is automatically called on process exit in Node.js environments.
276
*/
277
async flush(): Promise<void> {
278
await this.batchProcessor.flush();
279
}
280
+
281
+ /**
282
+ * Register process exit handlers to automatically flush telemetry.
283
+ * Only registers handlers in Node.js environments (not in browsers).
284
+ */
285
+ private registerExitHandlers(): void {
286
+ // Only register once and only in Node.js environments
287
+ if (this.exitHandlersRegistered || typeof process === 'undefined' || !process.on) {
288
+ return;
289
+ }
290
+
291
+ this.exitHandlersRegistered = true;
292
+
293
+ const flushSync = () => {
294
+ // Use a flag to track if we're already flushing to prevent double-flush
295
+ this.flush().catch(error => {
296
+ logger.debug('Error flushing telemetry on exit', error);
297
+ });
298
+ };
299
+
300
+ // beforeExit is emitted when Node.js empties its event loop and has nothing else to schedule
301
+ // This is the best place to flush async operations
302
+ process.on('beforeExit', () => {
303
+ flushSync();
304
+ });
305
+
306
+ // Handle SIGINT (Ctrl+C) and SIGTERM (kill command)
307
+ const signalHandler = (signal: string) => {
308
+ logger.debug(`Received ${signal}, flushing telemetry...`);
309
+ this.flush()
310
+ .catch(error => {
311
+ logger.debug('Error flushing telemetry on signal', error);
312
+ })
313
+ .finally(() => {
314
+ // Re-emit the signal to allow normal process termination
315
+ process.removeListener(signal as NodeJS.Signals, () => signalHandler(signal));
316
+ process.kill(process.pid, signal);
317
+ });
318
+ };
319
+
320
+ process.on('SIGINT', () => signalHandler('SIGINT'));
321
+ process.on('SIGTERM', () => signalHandler('SIGTERM'));
322
+ }
323
}
324
325
export const telemetry = new TelemetryTransport();
ts/packages/core/test/telemetry/TelemetryService.test.ts
+97
-3
@@ -83,7 +83,7 @@ describe('BatchProcessor', () => {
83
await asyncProcessor.flush();
84
});
85
86
- it('should track pending flush promise for async callbacks', async () => {
86
+ it('should track pending batches for async callbacks', async () => {
87
let resolveCallback: () => void;
88
const asyncCallback = vi.fn().mockImplementation(() => {
89
return new Promise<void>(resolve => {
@@ -96,13 +96,13 @@ describe('BatchProcessor', () => {
96
asyncProcessor.pushItem(createPayload());
97
98
// @ts-expect-error: private access for test
99
- expect(asyncProcessor.pendingFlush).toBeInstanceOf(Promise);
99
+ expect(asyncProcessor.pendingBatches.size).toBe(1);
100
101
resolveCallback!();
102
await asyncProcessor.flush();
103
104
// @ts-expect-error: private access for test
105
- expect(asyncProcessor.pendingFlush).toBeNull();
105
+ expect(asyncProcessor.pendingBatches.size).toBe(0);
106
});
107
108
it('should silently handle errors in async callbacks', async () => {
@@ -198,6 +198,100 @@ describe('BatchProcessor', () => {
198
await expect(asyncProcessor.flush()).resolves.toBeUndefined();
199
expect(asyncCallback).not.toHaveBeenCalled();
200
});
201
+
202
+ it('should await all concurrent batches when flush is called', async () => {
203
+ const completionOrder: number[] = [];
204
+ let resolveFirst: () => void;
205
+ let resolveSecond: () => void;
206
+
207
+ const asyncCallback = vi
208
+ .fn()
209
+ .mockImplementationOnce(() => {
210
+ return new Promise<void>(resolve => {
211
+ resolveFirst = resolve;
212
+ }).then(() => {
213
+ completionOrder.push(1);
214
+ });
215
+ })
216
+ .mockImplementationOnce(() => {
217
+ return new Promise<void>(resolve => {
218
+ resolveSecond = resolve;
219
+ }).then(() => {
220
+ completionOrder.push(2);
221
+ });
222
+ });
223
+
224
+ const asyncProcessor = new BatchProcessor(50, 2, asyncCallback);
225
+
226
+ // Trigger first batch
227
+ asyncProcessor.pushItem(createPayload());
228
+ asyncProcessor.pushItem(createPayload());
229
+
230
+ // Trigger second batch while first is still processing
231
+ asyncProcessor.pushItem(createPayload());
232
+ asyncProcessor.pushItem(createPayload());
233
+
234
+ expect(asyncCallback).toHaveBeenCalledTimes(2);
235
+
236
+ // @ts-expect-error: private access for test
237
+ expect(asyncProcessor.pendingBatches.size).toBe(2);
238
+
239
+ // Start flush, which should wait for both batches
240
+ const flushPromise = asyncProcessor.flush();
241
+
242
+ // Resolve second batch first (out of order)
243
+ resolveSecond!();
244
+ // Small delay to let promises settle
245
+ await new Promise(r => setTimeout(r, 10));
246
+
247
+ // @ts-expect-error: private access for test
248
+ expect(asyncProcessor.pendingBatches.size).toBe(1);
249
+
250
+ // Resolve first batch
251
+ resolveFirst!();
252
+
253
+ // Now flush should complete
254
+ await flushPromise;
255
+
256
+ // Both batches should have completed
257
+ expect(completionOrder).toEqual([2, 1]);
258
+ // @ts-expect-error: private access for test
259
+ expect(asyncProcessor.pendingBatches.size).toBe(0);
260
+ });
261
+
262
+ it('should not lose earlier batches when new batches are started', async () => {
263
+ const batchesProcessed: number[][] = [];
264
+ let resolvers: (() => void)[] = [];
265
+
266
+ const asyncCallback = vi.fn().mockImplementation((batch: any[]) => {
267
+ return new Promise<void>(resolve => {
268
+ resolvers.push(resolve);
269
+ }).then(() => {
270
+ batchesProcessed.push(batch.map((_, i) => i));
271
+ });
272
+ });
273
+
274
+ const asyncProcessor = new BatchProcessor(50, 1, asyncCallback); // batch size 1 for easier testing
275
+
276
+ // Push 3 items, each triggers a batch immediately
277
+ asyncProcessor.pushItem(createPayload({ functionName: 'batch1' }));
278
+ asyncProcessor.pushItem(createPayload({ functionName: 'batch2' }));
279
+ asyncProcessor.pushItem(createPayload({ functionName: 'batch3' }));
280
+
281
+ expect(asyncCallback).toHaveBeenCalledTimes(3);
282
+
283
+ // @ts-expect-error: private access for test
284
+ expect(asyncProcessor.pendingBatches.size).toBe(3);
285
+
286
+ // Resolve all in order
287
+ resolvers.forEach(r => r());
288
+ await asyncProcessor.flush();
289
+
290
+ // All 3 batches should have been processed
291
+ expect(batchesProcessed.length).toBe(3);
292
+ // @ts-expect-error: private access for test
293
+ expect(asyncProcessor.pendingBatches.size).toBe(0);
294
+ });
295
});
296
});
297