log-detective

🕵️ AI-powered log analysis tool that helps you quickly understand and debug error logs using GitHub Copilot.

What is log-detective?

log-detective is a command-line tool and API server that analyzes error logs using AI. Simply run the command, and it starts a web server with a beautiful UI where you can paste your error logs and get instant AI-powered analysis and solutions.

Features:

• 🤖 AI-powered log analysis using GitHub Copilot
• 🎨 Beautiful web UI for easy interaction
• 🗄️ Optional MongoDB integration to save analysis history
• 🔒 Built-in security (CORS, rate limiting, helmet)
• 🚀 Works as CLI tool or as part of your Node.js app
• 🐳 Docker support included

Quick Start

Installation

# Install globally
npm install -g log-detective

# Or install locally in a project
npm install log-detective

Basic Usage

# Start the server (runs on http://localhost:3001)
log-detective

# Or if installed locally
npx log-detective

Then open your browser to http://localhost:3001 and start analyzing logs!

Configuration

Required Environment Variables

Create a .env file in your working directory:

# Required: Your GitHub Copilot API key
COPILOT_API_KEY=your_github_copilot_api_key_here

How to get your COPILOT_API_KEY:

1. Visit GitHub Copilot API documentation
2. Generate an API token from your GitHub settings
3. Add it to your .env file

Optional Configuration

# Server port (default: 3001)
PORT=3001

# MongoDB connection (for saving analysis history)
MONGO_URI=mongodb+srv://user:[email protected]/logdetective

# Use local MongoDB (with docker-compose)
USE_LOCAL_MONGO=true
LOCAL_MONGO_URI=mongodb://localhost:27017/logdetective

# Environment mode
NODE_ENV=production

# Additional CORS origins (comma-separated)
ALLOWED_ORIGINS=https://yourdomain.com,https://api.yourdomain.com

Usage Examples

Example 1: Analyze a Simple Error

1. Start log-detective:

   log-detective

2. Open http://localhost:3001 in your browser

3. Paste your error log:

   TypeError: Cannot read property 'map' of undefined
       at processUsers (/app/users.js:45:20)
       at async getUserData (/app/controller.js:12:5)

4. Get instant AI analysis with:

   • Root cause identification
   • Suggested fixes
   • Prevention tips

Example 2: Using the API Directly

# POST to the /analyze endpoint
curl -X POST http://localhost:3001/analyze \
  -H "Content-Type: application/json" \
  -d '{"logError": "Your error log here"}'

Response:

{
  "report": "AI analysis of your error...",
  "saved": true,
  "case": {
    "_id": "...",
    "logError": "Your error log",
    "report": "AI analysis...",
    "createdAt": "2026-03-04T00:00:00.000Z"
  }
}

Example 3: View Analysis History

# GET saved cases
curl http://localhost:3001/cases

API Reference

POST /analyze

Analyze an error log using AI.

Request Body:

{
  "logError": "Your error log or stack trace"
}

Response:

{
  "report": "AI-generated analysis and solution",
  "saved": true,
  "case": { /* saved case object if MongoDB is configured */ }
}

Error Codes:

• 400 - No log provided or log is empty
• 413 - Log is too large (max 50,000 characters)
• 429 - Rate limit exceeded (30 requests/minute)
• 500 - Server error
• 502 - AI service error

GET /cases

Get all saved analysis cases (requires MongoDB).

Response:

[
  {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "logError": "Error log text",
    "report": "AI analysis",
    "createdAt": "2026-03-04T00:00:00.000Z"
  }
]

GET /health

Health check endpoint.

Response:

{
  "status": "ok"
}

Advanced Usage

Running with Docker

# Pull and run
docker pull yourusername/log-detective
docker run -p 3001:3001 --env-file .env log-detective

# Or with docker-compose (includes MongoDB)
curl -O https://raw.githubusercontent.com/yourusername/log-detective/main/docker-compose.yml
docker compose up

Using as a Library

import express from 'express';
import logDetective from 'log-detective';

const app = express();

// Mount log-detective at a subpath
app.use('/detective', logDetective);

app.listen(3000);

Custom Port

# Set port via environment variable
PORT=8080 log-detective

# Or in .env file
echo "PORT=8080" > .env
log-detective

Database Setup

Option 1: No Database (Stateless)

Just run without MONGO_URI - analysis works but history isn't saved.

Option 2: MongoDB Atlas (Recommended)

1. Create free account at MongoDB Atlas
2. Create a cluster and get connection string
3. Add to .env:

   MONGO_URI=mongodb+srv://user:[email protected]/logdetective

Option 3: Local MongoDB

# Install MongoDB locally or use Docker
docker run -d -p 27017:27017 mongo:6

# Add to .env
MONGO_URI=mongodb://localhost:27017/logdetective

Troubleshooting

"COPILOT_API_KEY is not set"

Solution: Create a .env file with your API key:

echo "COPILOT_API_KEY=your_key_here" > .env
log-detective

"Cannot connect to MongoDB"

Solutions:

• Check your MONGO_URI connection string
• Verify MongoDB is running
• For MongoDB Atlas: whitelist your IP address
• Run without database (omit MONGO_URI) for stateless operation

Rate Limit (429 errors)

The server limits requests to 30 per minute per IP. Wait a minute and try again, or adjust the limit in your own deployment.

Port Already in Use

# Use a different port
PORT=3002 log-detective

Security Notes

⚠️ Important:

• Never commit your .env file or API keys to git
• Use environment variables in production (not .env files)
• Rotate your COPILOT_API_KEY regularly
• Keep the package updated: npm update -g log-detective

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

• 🐛 Report issues
• 💬 Discussions
• 📧 Email: [email protected]

License

MIT © 2026

Changelog

See CHANGELOG.md for version history.

Made with ❤️ for developers who hate debugging alone

⭐ If log-detective helped you, consider starring the project!