How the Sync Agent works

The ActivityWatch Sync Agent is a service designed to periodically synchronize event data from ActivityWatch to Prometheus, ensuring structured, efficient, and reliable data collection.

It follows a sequential workflow to maintain data integrity and implements a robust error-handling mechanism to ensure no data is lost.

🔄 Sync Routine – Step-by-Step

Each sync routine consists of four key steps that run sequentially:

1️⃣ Retrieve All Buckets

The agent starts by retrieving all available buckets from ActivityWatch.

• API Call: GET /api/0/buckets/
• Buckets associated with specific watchers can be excluded via the aw-sync-settings.yaml configuration file.

2️⃣ Fetch Events from Each Bucket

For each retrieved bucket, the agent pulls event data.

• API Call: GET /api/0/buckets/<bucket_id>/events
• Uses the last successfully synced timestamp to fetch only new events, reducing redundant requests.

3️⃣ Aggregate Data

The fetched events are processed and aggregated using the agent’s built-in plugin manager, ensuring the data is structured and modified before being pushed.

4️⃣ Push Data to Prometheus

The processed data is then pushed to Prometheus using its Write API.

• The agent waits for confirmation before proceeding to the next bucket.
• This ensures that no data is skipped or lost.

📌 Core Functionalities

🕒 Timestamp Management

• The last successfully pushed event timestamp is stored in checkpoint.json.
• This allows the next sync to resume from where it left off, optimizing efficiency.

⚠️ Error Handling & Retry Mechanism

• If a push fails (e.g., due to network issues), the agent will automatically retry in the next sync cycle.
• No data is lost, as the agent resumes from the last recorded timestamp.

⏲️ Automated Scheduling

• The agent is designed to run periodically using cron jobs.
• Default interval: Every 5 minutes, ensuring near real-time synchronization.

📊 Workflow Overview

1️⃣ Retrieve Buckets ➝ 2️⃣ Fetch Events ➝ 3️⃣ Aggregate Data ➝ 4️⃣ Push to Prometheus ✅

The agent repeats this workflow at scheduled intervals, providing continuous synchronization of ActivityWatch data into Prometheus.