Skip to content

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

jkomyno1c773553981e
diff --git a/ts/docs/advanced/telemetry.md b/ts/docs/advanced/telemetry.md
index 1ef9fd431..fa1f48d94 100644
--- a/ts/docs/advanced/telemetry.md
+++ b/ts/docs/advanced/telemetry.md
@@ -203,8 +203,31 @@ The SDK includes a batch processor for telemetry events that:
2. Sends events in batches
3. Handles retries and failures
4. Automatically flushes at regular intervals
+5. **Automatically flushes on process exit** (Node.js-compatible environments only) - handles `beforeExit`, `SIGINT`, and `SIGTERM` signals
-This ensures that telemetry doesn't impact application performance.
+This 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.
+
+### Cloudflare Workers and Edge Runtimes
+
+In environments like Cloudflare Workers that don't support `process.on('beforeExit')`, you should manually flush telemetry using `ctx.waitUntil()`:
+
+```typescript
+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));
+ }
+};
+```
## Environment Context
diff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.ts
index e4b4c44ef..ddc0c29d9 100644
--- a/ts/packages/core/src/composio.ts
+++ b/ts/packages/core/src/composio.ts
@@ -383,4 +383,35 @@ export class Composio<
defaultHeaders: sessionHeaders,
});
}
+
+ /**
+ * Flush any pending telemetry and wait for it to complete.
+ *
+ * In Node.js-compatible environments, telemetry is automatically flushed on process exit.
+ * However, in environments like Cloudflare Workers that don't support process exit events,
+ * you should call this method manually to ensure all telemetry is sent.
+ *
+ * @returns {Promise<void>} A promise that resolves when all pending telemetry has been sent.
+ *
+ * @example
+ * ```typescript
+ * // In a Cloudflare Worker, use ctx.waitUntil to ensure telemetry is flushed
+ * 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));
+ * }
+ * };
+ * ```
+ */
+ async flush(): Promise<void> {
+ await telemetry.flush();
+ }
}
diff --git a/ts/packages/core/src/telemetry/BatchProcessor.ts b/ts/packages/core/src/telemetry/BatchProcessor.ts
index 1c8249da4..dd13b0514 100644
--- a/ts/packages/core/src/telemetry/BatchProcessor.ts
+++ b/ts/packages/core/src/telemetry/BatchProcessor.ts
@@ -9,7 +9,7 @@ export class BatchProcessor {
private batchSize: number;
private processBatchCallback: (data: TelemetryMetricPayloadBody) => Promise<void>;
private timer: NodeJS.Timeout | null = null;
- private pendingFlush: Promise<void> | null = null;
+ private pendingBatches: Set<Promise<void>> = new Set();
constructor(
time: number = 2000,
@@ -40,12 +40,10 @@ export class BatchProcessor {
// Silently ignore errors - they should be handled by the callback
})
.finally(() => {
- if (this.pendingFlush === pending) {
- this.pendingFlush = null;
- }
+ this.pendingBatches.delete(pending);
});
- this.pendingFlush = pending;
+ this.pendingBatches.add(pending);
}
if (this.timer) {
clearTimeout(this.timer);
@@ -54,13 +52,13 @@ export class BatchProcessor {
}
/**
- * Flush any pending batch and wait for it to complete.
+ * Flush any pending batches and wait for all of them to complete.
* Useful for ensuring telemetry is sent before process exit.
*/
async flush(): Promise<void> {
this.processBatch();
- if (this.pendingFlush) {
- await this.pendingFlush;
+ if (this.pendingBatches.size > 0) {
+ await Promise.all(this.pendingBatches);
}
}
}
diff --git a/ts/packages/core/src/telemetry/Telemetry.ts b/ts/packages/core/src/telemetry/Telemetry.ts
index 25c08edcc..a77ca656b 100644
--- a/ts/packages/core/src/telemetry/Telemetry.ts
+++ b/ts/packages/core/src/telemetry/Telemetry.ts
@@ -42,6 +42,7 @@ export class TelemetryTransport {
private readonly telemetrySourceName = 'typescript-sdk';
private readonly telemetryServiceName = 'sdk';
private readonly telemetryLanguage = 'typescript';
+ private exitHandlersRegistered = false;
private batchProcessor = new BatchProcessor(200, 10, async (data: TelemetryMetricPayloadBody) => {
logger.debug('Sending batch of telemetry metrics', data);
@@ -59,6 +60,9 @@ export class TelemetryTransport {
platform: this.telemetryMetadata?.isBrowser ? 'browser' : 'node',
environment: getEnvVariable('NODE_ENV', 'production') as TelemetryMetricSource['environment'],
};
+ // Register exit handlers to automatically flush telemetry before process exit
+ this.registerExitHandlers();
+
// send telemetry event for SDK initialization
this.sendMetric([
{
@@ -268,11 +272,54 @@ export class TelemetryTransport {
/**
* Flush any pending telemetry and wait for it to complete.
- * Call this before process exit to ensure all telemetry is sent.
+ * This is automatically called on process exit in Node.js environments.
*/
async flush(): Promise<void> {
await this.batchProcessor.flush();
}
+
+ /**
+ * Register process exit handlers to automatically flush telemetry.
+ * Only registers handlers in Node.js environments (not in browsers).
+ */
+ private registerExitHandlers(): void {
+ // Only register once and only in Node.js environments
+ if (this.exitHandlersRegistered || typeof process === 'undefined' || !process.on) {
+ return;
+ }
+
+ this.exitHandlersRegistered = true;
+
+ const flushSync = () => {
+ // Use a flag to track if we're already flushing to prevent double-flush
+ this.flush().catch(error => {
+ logger.debug('Error flushing telemetry on exit', error);
+ });
+ };
+
+ // beforeExit is emitted when Node.js empties its event loop and has nothing else to schedule
+ // This is the best place to flush async operations
+ process.on('beforeExit', () => {
+ flushSync();
+ });
+
+ // Handle SIGINT (Ctrl+C) and SIGTERM (kill command)
+ const signalHandler = (signal: string) => {
+ logger.debug(`Received ${signal}, flushing telemetry...`);
+ this.flush()
+ .catch(error => {
+ logger.debug('Error flushing telemetry on signal', error);
+ })
+ .finally(() => {
+ // Re-emit the signal to allow normal process termination
+ process.removeListener(signal as NodeJS.Signals, () => signalHandler(signal));
+ process.kill(process.pid, signal);
+ });
+ };
+
+ process.on('SIGINT', () => signalHandler('SIGINT'));
+ process.on('SIGTERM', () => signalHandler('SIGTERM'));
+ }
}
export const telemetry = new TelemetryTransport();
diff --git a/ts/packages/core/test/telemetry/TelemetryService.test.ts b/ts/packages/core/test/telemetry/TelemetryService.test.ts
index f7553932e..6bc2abeda 100644
--- a/ts/packages/core/test/telemetry/TelemetryService.test.ts
+++ b/ts/packages/core/test/telemetry/TelemetryService.test.ts
@@ -83,7 +83,7 @@ describe('BatchProcessor', () => {
await asyncProcessor.flush();
});
- it('should track pending flush promise for async callbacks', async () => {
+ it('should track pending batches for async callbacks', async () => {
let resolveCallback: () => void;
const asyncCallback = vi.fn().mockImplementation(() => {
return new Promise<void>(resolve => {
@@ -96,13 +96,13 @@ describe('BatchProcessor', () => {
asyncProcessor.pushItem(createPayload());
// @ts-expect-error: private access for test
- expect(asyncProcessor.pendingFlush).toBeInstanceOf(Promise);
+ expect(asyncProcessor.pendingBatches.size).toBe(1);
resolveCallback!();
await asyncProcessor.flush();
// @ts-expect-error: private access for test
- expect(asyncProcessor.pendingFlush).toBeNull();
+ expect(asyncProcessor.pendingBatches.size).toBe(0);
});
it('should silently handle errors in async callbacks', async () => {
@@ -198,6 +198,100 @@ describe('BatchProcessor', () => {
await expect(asyncProcessor.flush()).resolves.toBeUndefined();
expect(asyncCallback).not.toHaveBeenCalled();
});
+
+ it('should await all concurrent batches when flush is called', async () => {
+ const completionOrder: number[] = [];
+ let resolveFirst: () => void;
+ let resolveSecond: () => void;
+
+ const asyncCallback = vi
+ .fn()
+ .mockImplementationOnce(() => {
+ return new Promise<void>(resolve => {
+ resolveFirst = resolve;
+ }).then(() => {
+ completionOrder.push(1);
+ });
+ })
+ .mockImplementationOnce(() => {
+ return new Promise<void>(resolve => {
+ resolveSecond = resolve;
+ }).then(() => {
+ completionOrder.push(2);
+ });
+ });
+
+ const asyncProcessor = new BatchProcessor(50, 2, asyncCallback);
+
+ // Trigger first batch
+ asyncProcessor.pushItem(createPayload());
+ asyncProcessor.pushItem(createPayload());
+
+ // Trigger second batch while first is still processing
+ asyncProcessor.pushItem(createPayload());
+ asyncProcessor.pushItem(createPayload());
+
+ expect(asyncCallback).toHaveBeenCalledTimes(2);
+
+ // @ts-expect-error: private access for test
+ expect(asyncProcessor.pendingBatches.size).toBe(2);
+
+ // Start flush, which should wait for both batches
+ const flushPromise = asyncProcessor.flush();
+
+ // Resolve second batch first (out of order)
+ resolveSecond!();
+ // Small delay to let promises settle
+ await new Promise(r => setTimeout(r, 10));
+
+ // @ts-expect-error: private access for test
+ expect(asyncProcessor.pendingBatches.size).toBe(1);
+
+ // Resolve first batch
+ resolveFirst!();
+
+ // Now flush should complete
+ await flushPromise;
+
+ // Both batches should have completed
+ expect(completionOrder).toEqual([2, 1]);
+ // @ts-expect-error: private access for test
+ expect(asyncProcessor.pendingBatches.size).toBe(0);
+ });
+
+ it('should not lose earlier batches when new batches are started', async () => {
+ const batchesProcessed: number[][] = [];
+ let resolvers: (() => void)[] = [];
+
+ const asyncCallback = vi.fn().mockImplementation((batch: any[]) => {
+ return new Promise<void>(resolve => {
+ resolvers.push(resolve);
+ }).then(() => {
+ batchesProcessed.push(batch.map((_, i) => i));
+ });
+ });
+
+ const asyncProcessor = new BatchProcessor(50, 1, asyncCallback); // batch size 1 for easier testing
+
+ // Push 3 items, each triggers a batch immediately
+ asyncProcessor.pushItem(createPayload({ functionName: 'batch1' }));
+ asyncProcessor.pushItem(createPayload({ functionName: 'batch2' }));
+ asyncProcessor.pushItem(createPayload({ functionName: 'batch3' }));
+
+ expect(asyncCallback).toHaveBeenCalledTimes(3);
+
+ // @ts-expect-error: private access for test
+ expect(asyncProcessor.pendingBatches.size).toBe(3);
+
+ // Resolve all in order
+ resolvers.forEach(r => r());
+ await asyncProcessor.flush();
+
+ // All 3 batches should have been processed
+ expect(batchesProcessed.length).toBe(3);
+ // @ts-expect-error: private access for test
+ expect(asyncProcessor.pendingBatches.size).toBe(0);
+ });
});
});