> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BLACKBOX AI Logger

> An AI-powered server log monitoring and error management solution that analyzes millions of server logs, detects issues instantly, and notifies engineers via voice-powered notifications using ElevenLabs' advanced speech-to-text and text-to-speech capabilities.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/3hRJRQaABBU" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Overview

BLACKBOX AI Logger is an innovative AI tool designed to revolutionize server log monitoring and error management. Powered by ElevenLabs' advanced speech-to-text and text-to-speech capabilities, it continuously scans millions of server logs to detect and resolve errors in real-time, minimizing downtime and promoting smarter coding practices.

The system provides instant engineer notification upon error detection, automated issue resolution before service disruption, and an interactive voice agent that can explain error contexts, analyze code repositories for root causes, suggest fixes, and even assist with implementation. It's an all-in-one end-to-end solution for proactive server error management.

## Getting Started

BLACKBOX AI Logger is available as an npm package for easy integration into your projects. Install it via:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install @blackbox_ai/ai-logs-watcher
```

##### Basic Setup

Import and initialize the logger in your application:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { Ailogw, ElevenLabsVoiceProvider, PrepareCallContext } from "@blackbox_ai/ai-logs-watcher";

const voiceProvider = new ElevenLabsVoiceProvider({
    credentials: {
        apiKey: process.env["ELEVENLABS_API_KEY"]!
    }
});

const ailogwatch = new Ailogw({
    name: "vercel",
    log: true,
    twilio: {
        numberFrom: process.env["AILOGW_NUMBER_FROM"]   // Using Twilio test number for "from"
    },
    voice: voiceProvider,
    polling: {
        delay: "1000:ms",
        tailAmount: 10
    },
    events: {
        async alert({ options, logs, diagnostic, sendSms, voice }) {
            void options, logs;
            const numberTo = process.env["AILOGW_NUMBER_TO"]!;
            switch (diagnostic.raw.status) {
                case "warning":
                case "normal": {
                    // await sendSms(numberTo, diagnostic.formatted);
                    return;
                }
                case "critical": {
                    if (voice && voice instanceof ElevenLabsVoiceProvider) {
                        const context: PrepareCallContext = {
                            githubRepositoryUrl: "https://github.com/your-repo/your-project",
                            namespace: options.name,
                            "the current nodejs version": "20.0.1",
                            "the database": "sqlite",
                            "emergency contact": "Your Name, Title at Company, phone number +xxxxxxxxxx"
                        };
                        const call = await voice.prepareCall(diagnostic.formatted, numberTo, context);
                        console.log(`calling: ${numberTo}`, JSON.stringify(context, null, 2));
                        await call();
                        process.exit(0);
                    }
                    return;
                }
            }
        }
    }
});

const logger = ailogwatch.createLogger();

export {
    ailogwatch,
    logger
}
```

##### Feeding Logs

Feed logs to be analyzed manually or use the logger methods that replace console logging:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Single log entry
ailogwatch.feedLog("2024-09-16 ERROR Database connection failed");

// Multiple log entries
ailogwatch.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"
]);
```

The logger also supports console-like methods (`logger.log`, `logger.warn`, `logger.error`) that can be used in place of `console.log`, `console.warn`, `console.error`. These methods accept key-value pairs as additional arguments for structured logging:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Replace console.log with logger.log
logger.log("Server started successfully", { port: 3000, environment: "production" });

// Replace console.warn with logger.warn
logger.warn("High memory usage detected", { memoryUsage: "85%", threshold: "80%" });

// Replace console.error with logger.error (as shown in examples above)
logger.error("Database connection failed", { error: err.message, retryCount: 3 });
```

##### Complete Setup with Voice Integration

For full functionality including voice notifications and code analysis, follow these deployment steps:

1. **Deploy the Tools Server**\
   Deploy the required tools server on a cloud platform (Render, Vercel, etc.).\
   Repository: [fragola-cloud](https://github.com/blackboxaicode/fragola-cloud)\
   Follow the README for deployment steps and required environment variables. You'll get a server baseURL (e.g., `https://your-tools-server-url.com`).

2. **Configure ElevenLabs Agents**\
   Clone the AI-logs-watcher repository and set up your environment:
   ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   git clone https://github.com/blackboxaicode/AI-logs-watcher.git
   cd AI-logs-watcher
   cp .env.example .env
   npm install
   ```
   Run the ElevenLabs configuration script with your tools server baseURL:
   ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   npm run config-elevenlabs <your_tools_server_baseURL>
   ```
   This will output `AILOGW_ALERT_AGENT_ID` and `AILOGW_GITHUB_AGENT_ID`. Add them to your `.env` file.

3. **Run the Demo Server**\
   Clone the server-demo repository:

   ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   git clone https://github.com/blackboxaicode/server-demo.git
   cd server-demo
   cp .env.example .env
   ```

   Add all required environment variables to `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>"
   AILOGW_GITHUB_AGENT_ID="<your_github_agent_id>"
   BLACKBOX_API_KEY="<your_blackbox_api_key>"
   AILOGW_LOG=<boolean>
   ```

   Install Bun and start the server:

   ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   bun install
   bun index.ts
   ```

   <Note>
     **Important**: Ensure all environment variables are properly configured. The demo server will simulate database failures and initiate voice calls for testing.
   </Note>

With these steps completed, BLACKBOX AI Logger will continuously monitor your server logs, detect anomalies, and provide proactive error resolution through voice-powered notifications and interactive assistance.

## Usage Examples

##### Logging Errors

Use the created logger to log errors with different severity levels:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Log an error with additional context
logger.error({ error: err.message }, 'Failed to create users table');

// Log an error with the full error object
logger.error({ error: err }, "Failed to recover database connection");

// Log a critical error with status
logger.error("Failed to initialize database", { status: "critical", error: err });

// Simple error logging
logger.error("Attempted to query users but database is not connected");
```

##### Manual Log Feeding

You can also manually feed logs for analysis:

```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Single log entry
ailogwatch.feedLog("2024-09-16 10:30:25 ERROR Database connection failed");

// Multiple log entries
ailogwatch.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"
]);
```

## How It Works

When an error is detected in your server logs, BLACKBOX AI Logger follows this automated process:

* **Real-Time Scanning**: Continuously analyzes incoming log entries using advanced AI pattern recognition
* **Error Classification**: Categorizes issues by severity, type, and potential impact
* **Voice Notification**: Alerts engineers via ElevenLabs-powered voice calls with clear explanations based on the severity of the issue
* **Context Analysis**: Provides detailed information about when and where the error occurred
* **Code Repository Investigation**: Searches connected repositories for related code and potential root causes
* **Fix Suggestions**: Generates actionable recommendations for resolution
* **Interactive Support**: Allows engineers to ask questions and request help through voice interaction

## Key Features

##### Continuous Server Monitoring

BLACKBOX AI Logger provides 24/7 oversight of your server infrastructure:

* **Real-Time Log Analysis**: Processes millions of log entries per minute
* **Pattern Recognition**: Uses AI to identify anomalies and error patterns
* **Scalable Architecture**: Handles high-volume log streams without performance degradation

##### Intelligent Error Detection

Advanced AI ensures accurate and timely issue identification:

* **Contextual Analysis**: Understands error relationships and dependencies
* **Severity Assessment**: Prioritizes issues based on user-defined severity levels
* **Predictive Insights**: Identifies potential issues before they cause outages

##### Voice-Powered Notifications

ElevenLabs integration enables natural, effective communication:

* **Instant Voice Alerts**: Immediate engineer notification via phone calls
* **Clear Explanations**: Detailed error context delivered through natural speech
* **Interactive Conversations**: Engineers can ask questions and request clarification

##### Code Repository Integration

Deep code analysis for comprehensive error resolution:

* **Root Cause Identification**: Traces errors back to specific code sections
* **Automated Fix Suggestions**: Suggests fixes based on the error and the code repository.
* **Repository Search**: Scans entire codebases for related issues and patterns

##### Interactive Voice Agent

An AI assistant that provides ongoing support:

* **Question Answering**: Responds to engineer queries about errors and fixes
* **Implementation Guidance**: Provides step-by-step fix instructions
* **Learning Adaptation**: Improves recommendations based on feedback and outcomes

##### Comprehensive Reporting

Detailed insights for continuous improvement:

* **Error Trend Analysis**: Identifies recurring issues and patterns
* **Performance Metrics**: Tracks resolution times and system uptime
* **Audit Logs**: Maintains complete records of all detections and actions

## Benefits

* **Minimized Downtime**: Proactive error detection and resolution prevents service disruptions
* **Enhanced Efficiency**: Automated analysis reduces manual log review time by up to 90%
* **Faster Resolution**: Voice-powered notifications enable immediate response to critical issues
* **Cost Reduction**: Prevents revenue loss from outages and reduces debugging costs
* **Scalability**: Handles massive log volumes without additional infrastructure investment

## Use Cases

* **Production Monitoring**: Real-time oversight of live server environments
* **DevOps Integration**: Automated error handling in CI/CD pipelines
* **Incident Response**: Rapid identification and resolution of critical system failures
* **Performance Optimization**: Detection of performance bottlenecks and resource issues
* **Security Monitoring**: Identification of suspicious activities and potential breaches
* **Compliance Auditing**: Automated log analysis for regulatory requirements
* **Microservices Management**: Monitoring distributed systems and service dependencies

BLACKBOX AI Logger transforms server error management from reactive firefighting to proactive prevention, ensuring your systems remain stable and your team stays focused on innovation rather than maintenance.