AI Logs Watcher

An AI-powered log monitoring and alerting system that uses artificial intelligence to analyze log entries and send SMS notifications via Twilio when critical issues are detected.

Features Status

✅ Available

• 🤖 AI-Powered Analysis: Uses AI to intelligently analyze log entries and detect critical issues
• ☁️ Cloud tools: Server that exposes cloud tools and manage github repository exploration
• 📱 SMS Alerts: Automatic SMS notifications via Twilio for critical and warning conditions
• ⚡ Real-time Monitoring: Configurable polling intervals for continuous log analysis
• 🎯 Smart Detection: Advanced keyword heuristics for detecting critical system failures
• 📊 Flexible Log Input: Support for single logs, multi-line strings, or arrays of log entries
• 🔧 Highly Configurable: Customizable AI models, polling intervals, and alert thresholds
• 📞 Voice Interactive Calling: AI-powered voice calls for critical alerts with interactive responses
• 📝 Enhanced Logger: Drop-in console replacement with automatic AI feeding and optional file writing

Future

• 📋 Phone Contacts Management: Manage multiple contact lists with priority levels and escalation chains
• 🔄 Alert Fallbacks: Automatic fallback mechanisms when primary contacts are unavailable
• 📈 Analytics Dashboard: Real-time monitoring dashboard with alert history and trends

Installation

npm install @blackbox_ai/ai-logs-watcher

Important: Environment Variables Setup

⚠️ Critical: This library requires environment variables to be configured in your application. Make sure to call dotenv.config() (or your preferred environment configuration method) before importing and using the Ailogw package:

// At the top of your application entry point (e.g., index.ts, app.ts)
import dotenv from 'dotenv';
dotenv.config();

// Then import and use Ailogw
import { Ailogw } from '@blackbox_ai/ai-logs-watcher';

const ailogwatch = new Ailogw({
  // ... your configuration
});

Alternatively, you can set environment variables directly in your deployment platform (Vercel, Heroku, AWS, etc.) or use other environment management tools.

Quick Start

import { Ailogw } from "./Ailogw/Ailogw";

const ailogwatch = new Ailogw({
    name: "vercel",
    twilio: {
        numberFrom: "+17153645914"
    },
    events: {
        async alert({ options, logs, diagnostic, sendSms }) {
            switch (diagnostic.raw.status) {
                case "warning":
                case "normal": {
                    await sendSms("+33727926138", diagnostic.formatted);
                    return;
                }
                case "critical": {
                    await sendSms("+33727926138", diagnostic.formatted);
                    return;
                }
            }
        }
    }
});

// Feed logs to be analyzed
ailogwatch.feedLog("2024-09-16 ERROR Database connection failed");

Configuration

Environment Variables

Final environment variables after completion of the guide

## Required for step 2
AILOGW_TWILIO_ACCOUNT_SID="<your_twilio_account_sid>"
AILOGW_TWILIO_AUTH_TOKEN="<your_twilio_auth_token>"
AILOGW_NUMBER_TO="<destination_phone_number>"      # The phone number to send SMS alerts to
AILOGW_NUMBER_FROM="<twilio_phone_number>"         # Your Twilio phone number (sender)
ELEVENLABS_API_KEY="<your_elevenlabs_api_key>"
## Required for step 3 (for eleven labs agents and voice)
AILOGW_ALERT_AGENT_ID="<your_alert_agent_id>"
AILOGW_GITHUB_AGENT_ID="<your_github_agent_id>"
BLACKBOX_API_KEY="<your_blackbox_api_key>"

# Optional: disable/enable verbose mode
AILOGW_LOG=<boolean>

1 - Deploy the Tools Server

To use AI Logs Watcher, you need to deploy the required tools server. You can do this on any cloud platform of your choice (such as Render, Vercel, etc.).

• Repository: fragola-cloud
• Instructions: Follow the README in the linked repository for deployment steps and required environment variables.

Once deployed, you will have a server baseURL (e.g., https://your-tools-server-url.com) that you will use in the next configuration step.

2 - Script to import the elevenLabs agents config to your elevenLabs account (check required envs for step 2 above)

Clone the AI-logs-watcher repository and set up your environment:

git clone https://github.com/blackboxaicode/AI-logs-watcher.git
cd AI-logs-watcher
cp .env.example .env   #  ⚠️️ env variables from step 2 must be present.
npm install

Then run the ElevenLabs configuration script with your tools server baseURL:

npm run config-elevenlabs <your_tools_server_baseURL>

After running the script, it will output two agent IDs: AILOGW_ALERT_AGENT_ID and AILOGW_GITHUB_AGENT_ID.
Copy both of these values into your .env file as shown above.

3 - Run the demo server (check required envs for step 3 above)

Clone the server-demo repository and set up your environment:

git clone https://github.com/blackboxaicode/server-demo.git
cd server-demo
cp .env.example .env

Copy all the environment variables from the previous steps into the server-demo .env file. Your .env should now contain all the variables listed in the "Final environment variables" section above:

# Complete environment variables needed in server-demo/.env
AILOGW_TWILIO_ACCOUNT_SID="<your_twilio_account_sid>"
AILOGW_TWILIO_AUTH_TOKEN="<your_twilio_auth_token>"
AILOGW_NUMBER_TO="<destination_phone_number>"
AILOGW_NUMBER_FROM="<twilio_phone_number>"
ELEVENLABS_API_KEY="<your_elevenlabs_api_key>"
AILOGW_ALERT_AGENT_ID="<your_alert_agent_id>"          # From step 2
AILOGW_GITHUB_AGENT_ID="<your_github_agent_id>"        # From step 2
BLACKBOX_API_KEY="<your_blackbox_api_key>"
AILOGW_LOG=<boolean>

Install Bun (if not already installed) - see Bun installation guide.

Install dependencies and start the server:

bun install
bun index.ts

The server will now simulate database failures and call you.

Usage Examples

Basic Log Monitoring

const watcher = new Ailogw({
    name: "production-api",
    twilio: {
            numberFrom: "+17153645914"
    },
    events: {
        alert: async ({ options, logs, diagnostic, sendSms }) => {
            if (diagnostic.raw.status === "critical") {
                await sendSms("+1234567890", diagnostic.formatted);
            }
        }
    }
});

// Single log entry
watcher.feedLog("2024-09-16 10:30:25 ERROR Database connection failed");

// Multiple log entries
watcher.feedLog([
    "2024-09-16 10:30:25 INFO Server started",
    "2024-09-16 10:30:26 WARN High memory usage",
    "2024-09-16 10:30:27 CRITICAL System overload"
]);

Custom Polling Configuration

const watcher = new Ailogw({
    name: "database-logs",
    polling: {
        delay: "5:minutes",          // Check every 5 minutes
        tailAmount: 20               // Analyze last 20 log entries
    },
    events: {
        alert: async ({ options, logs, diagnostic, sendSms }) => {
            console.log(`Alert Status: ${diagnostic.raw.status}`);
            if (diagnostic.raw.topErrors) {
                console.log("Critical errors found:", diagnostic.raw.topErrors);
            }
        }
    }
});

Advanced AI Configuration

const watcher = new Ailogw({
    name: "advanced-monitoring",
    clientOptions: {
        baseURL: "https://api.blackbox.ai",
        apiKey: "sk-your-api-key"
    },
    modelSettings: {
        model: "gpt-4",
        temperature: 0.1
        // and any other openai compatible options
    },
    events: {
        alert: async ({ options, logs, diagnostic, sendSms }) => {
            // Custom alert logic
        }
    }
});

Log Status Detection

The AI analyzes logs and categorizes them into three severity levels:

• 🟢 Normal: Standard operation, no issues detected
• 🟡 Warning: Potential issues that should be monitored
• 🔴 Critical: Severe problems requiring immediate attention

Critical Detection Keywords

The system automatically detects critical issues based on keywords such as:

• FATAL, PANIC, EMERGENCY, SEVERE
• OOM, OUT OF MEMORY, SEGFAULT
• CRASH, KERNEL PANIC, DATA LOSS
• SECURITY BREACH, DISK FAILURE
• SERVICE UNAVAILABLE, DEADLOCK And any other words related to a critical issue

Error Handling

The system includes built-in error handling for:

• Invalid config e.g credentials
• Invalid time units in polling configuration
• AI service connectivity issues
• SMS delivery failures

API Reference

Class Methods

feedLog(log: string | string[])

Feeds log entries to the watcher for analysis.

activatePolling()

Starts or resumes the log polling process.

pausePolling()

Pauses the log polling process.

get options()

Returns the current configuration options.

createLogger(options?: CreateLoggerOptions)

Creates an enhanced logger that automatically feeds all log entries to the Ailogw instance for AI analysis while maintaining full console compatibility.

Features:

• 🔄 Automatic Log Feeding: Every log call automatically feeds to AI analysis
• 📁 File Writing: Optional file destinations for each log level
• 🕒 Timestamping: All logs are automatically timestamped
• ⚡ Console Compatible: Drop-in replacement for console object
• 🛡️ Error Handling: Graceful handling of file writing errors

Parameters:

interface CreateLoggerOptions {
  destination?: {
    log?: string;     // File path for general logs
    error?: string;   // File path for error logs
    warn?: string;    // File path for warning logs
    info?: string;    // File path for info logs
    debug?: string;   // File path for debug logs
  }
}

Examples:

// Basic usage - automatic AI analysis only
const logger = ailogw.createLogger();
logger.info("Server started successfully");
logger.error("Database connection failed");

// With file destinations - logs written to files AND analyzed by AI
const logger = ailogw.createLogger({
  destination: {
    info: "./logs/info.log",
    error: "./logs/errors.log",
    warn: "./logs/warnings.log",
    debug: "./logs/debug.log"
  }
});

// All standard console methods work
logger.log("General message");
logger.info("Information message");  
logger.warn("Warning message");
logger.error("Error occurred");
logger.debug("Debug information");

// Supports multiple arguments like console
logger.error("Database error:", error.message, { userId: 123, timestamp: Date.now() });

Log Format: All logs are formatted as: YYYY-MM-DDTHH:mm:ss.sssZ [LEVEL] your message here

Example output:

2024-09-30T14:30:25.123Z INFO Server started successfully
2024-09-30T14:30:26.456Z ERROR Database connection failed

Constructor Options

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project license will be available soon.

Development & Testing

Running Example Demos

The repository includes example demos to help you test and understand the voice calling functionality. These examples are not included in the npm package but are available in the repository for development purposes.

Prerequisites

Before running the demos, ensure you have:

• Cloned the repository: git clone https://github.com/blackboxaicode/AI-logs-watcher.git
• Installed dependencies: npm install
• Set up all required environment variables (see Configuration section above)

Available Demos

1. Voice Demo with Polling (Continuous Monitoring)

This demo simulates continuous log monitoring with automatic polling. It feeds logs periodically and triggers voice calls when critical issues are detected.

npx tsx examples/voice-polling.ts

Features:

• Polls logs every 1 second (configurable)
• Analyzes the last 10 log entries per cycle
• Automatically triggers voice calls for critical alerts
• Demonstrates graceful shutdown handling

2. Voice Demo On-Demand (Single Analysis)

This demo performs a one-time analysis of all logs without continuous polling. Useful for testing immediate log analysis and voice call functionality.

npx tsx examples/voice-ondemand.ts

Features:

• Analyzes all logs immediately (no polling)
• Triggers voice call if critical issues are found
• Automatically exits after analysis or 5-minute timeout
• Demonstrates the triggerAnalysis() method

Demo Requirements

Both demos require the following environment variables:

AILOGW_NUMBER_TO="<destination_phone_number>"
AILOGW_NUMBER_FROM="<twilio_phone_number>"
ELEVENLABS_API_KEY="<your_elevenlabs_api_key>"
AILOGW_ALERT_AGENT_ID="<your_alert_agent_id>"
AILOGW_GITHUB_AGENT_ID="<your_github_agent_id>"

Support

For support and questions, please open an issue on the GitHub repository.