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
Telemetry System Overview
This document describes how telemetry is implemented in the SDK, including the main components, their responsibilities, and the data flow.
1. Telemetry Architecture Overview
Purpose: The telemetry system collects, batches, and sends usage and error data from the SDK to a remote telemetry server, with minimal impact on application performance.
Key Components:
TelemetryTransport: Main class for instrumentation and telemetry logic.BatchProcessor: Buffers and batches telemetry events before sending.TelemetryService: Handles HTTP requests to the telemetry API.- Types: Define the structure of telemetry payloads.
2. BatchProcessor
Role: Efficiently batches telemetry events to reduce the number of API calls and avoid performance bottlenecks.
How it works:
- Maintains an internal array (
batch) to store telemetry events. - Configurable batch size and time interval (defaults: 100 items or 2 seconds).
- When an event is added via
pushItem:- If the batch size is reached, immediately processes (sends) the batch.
- If not, starts a timer (if not already running) to process the batch after the interval.
processBatch:- Invokes a callback (provided at construction) with the current batch.
- Clears the batch and resets the timer.
3. TelemetryTransport (Main Telemetry Class)
Initialization:
- Configured with metadata (SDK version, environment, provider, etc.).
- Sets up a
BatchProcessorwith a callback to send metrics viaTelemetryService.sendMetric.
Instrumentation:
- The
instrumentmethod wraps all async methods of a given instance (e.g., SDK classes). - For each method call:
- Creates a telemetry payload with function name, arguments, timestamp, etc.
- Pushes the payload to the batch processor.
- If the method throws an error, captures error details and sends error telemetry immediately.
Sending Telemetry:
- Metrics: Batched and sent via
TelemetryService.sendMetric(POST to/metrics/invocations). - Errors: Sent immediately via
TelemetryService.sendErrorLog(POST to/errors).
Environment Awareness:
- Telemetry is disabled in certain environments (e.g.,
test,ci, or ifTELEMETRY_DISABLEDis set).
4. TelemetryService
- sendMetric: Sends a batch of telemetry events to the
/metrics/invocationsendpoint. - sendErrorLog: Sends a single error event to the
/errorsendpoint. - Implementation: Uses
fetchwith JSON payloads.
5. Telemetry Payload Structure
Types: Defined in TelemetryService.types.ts using Zod schemas and TypeScript types.
Payload Fields:
functionName: Name of the function/method invoked.durationMs: Duration of the invocation (optional).timestamp: Epoch time of the event.props: Additional properties (e.g., method arguments).source: Metadata about the SDK/runtime.metadata: Project/provider info.error: Error details (if any).
6. Error Handling
Error Instrumentation:
- If an instrumented method throws, the error is captured.
- Error details (name, message, stack, code) are included in the telemetry payload.
- Each error is assigned a unique
errorIdif not already present.
7. Usage Example
const telemetry = new TelemetryTransport();
telemetry.setup(metadata); // metadata includes SDK version, provider, etc.
telemetry.instrument(someSdkInstance); // Instruments all async methods for telemetry
8. Summary of Flow
- SDK initializes telemetry with environment and version info.
- SDK classes are instrumented so all async method calls are logged.
- Each method call generates a telemetry event, which is batched.
- BatchProcessor sends events in bulk (by size or time) to the telemetry server.
- Errors are captured and sent immediately.
- TelemetryService handles the actual HTTP requests.
9. Telemetry Service Hosting & Source
- The telemetry services are hosted at: https://telemetry.composio.io
- The source code for the telemetry backend is available in the ComposioHQ/hermes repository.
- The relevant backend implementation can be found in the
/apps/telemetry-proxydirectory of that repository.