FloWatcher 🐾

A simplified, real-time log monitoring tool built during Be Hackathon in under 48 hours!

Keep an eye on your long-running programs with intelligent alerts and a simplified web interface. Whether it's machine learning models training overnight or complex simulations crunching data, FloWatcher alerts you instantly, saving you time and headaches.

video demo (to do)

Features

• Web Dashboard: Simplified interface to view logs, alerts, and execution history.
• Real-Time Log Monitoring: Watch your scripts execute live.
• Customizable Alert Rules: Personalize alerts by defining rules with natural language queries, keywords, or specific log levels.
• Alert System: Keep track of specific logs and send notifications via Telegram or in-app alerts.

Setup

1. Configure Environment Variables

Create the .env from .env.example and update the following:

OPENAI_API_KEY = "your_open_ai_api_key" 
TELEGRAM_BOT_TOKEN = "your_telegram_bot_token"
TELEGRAM_CHAT_ID = "your_telegram_chat_id"

For the OpenAI API key, you can get it from OpenAI's platform. You will only need it if you want to define natural language rules.

The Telegram bot token and chat ID can be obtained by following the instructions in the Telegram Integration section below.

2. Run on virtual environment

Using uv (recommended)

You can run the following command which directly creates the virtual environment with the dependenies from pyproject.toml and starts the Flask app.

uv run python index.py

Using pip (oldschool)

python -m venv venv # create virtual env
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt # install dependencies
python index.py # start server

By default, the Flask web interface will be available at http://localhost:4980.

Telegram Integration

FloWatcher integrates with Telegram for instant notifications. Here's how to set it up:

1. Create a Telegram Bot:

   • Open Telegram and search for @BotFather.
   • Send /newbot and follow the prompts to create your bot.
   • Save the Bot Token provided.

2. Get Your Chat ID:

   • Start a chat with your new bot and send a message to it.
   • Visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates in your browser.
   • Look for the "chat":{"id":...} in the JSON response – that's your Chat ID.

3. Configure Environment:

   • Add the TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID to your .env file.

Now, you'll receive Telegram alerts alongside in-app notifications!

How to Use FloWatcher

1. Define alert rules: You can define three types of rules.
   • Natural language: Uses an LLM to determine if the log matches a natural language query.
   • Keywords: Searches for that keyword in the log.
   • Value: Checks if a specific field from a log matches said value (e.g., level: error).

A log example according to our data schema:

{
   "source": "stdout", 
   "level": "info", 
   "message": "[INFO] Train acc: 0.9233 | loss: 0.2082 || Val acc: 0.9227 | loss: 0.2080",
   "timestamp": "2026-05-12T18:44:45.726103", 
   "event_id": "c05d357f-3bd9-4df4-b7ad-411349cd3877"
}

2. Execute the script you want to monitor: Copy the absolute path of the script to execute. In the sample_scripts folder, there are some examples with logs for you to test. Paste it in the form of the interface and click execute.

3. Monitor: Check the alerts, live logs, and history sections, and check Telegram bot messages if configured correctly. You can also access the Flask server from your mobile phone if you are on the same network or through a VPN.