Skip to content

README.md

Latest commit

 

History

History
176 lines (115 loc) · 5.85 KB

README.md

File metadata and controls

176 lines (115 loc) · 5.85 KB

LogAn (Log Analyzer)

LogAn is an intelligent log analysis tool that extracts key insights for SREs/Support Engineers/Developers, to identify and diagnose ongoing issues from logs. It generates two reports: (1) Summary Report presents a table of the representative log lines — each with its predicted golden signals and fault categories — along with the frequency of its occurrence. By using this approach, we've found that the tool can reduce the data volume by up to 90%, since most log lines are informational. (2) Diagnosis Report presents a chronologically ordered set of relevant log windows with user-configurable granularity (e.g., 30s, 1m).

Architecture

Key Features

Features

How to Run

Option 1 - Using Containers (Recommended)

Running Container Image

We provide a container image that you can run standalone or integrate into automated pipelines to analyze logs.

mkdir -p ./tmp/output

podman run --rm \
    -v ./examples/:/data/input/:z \
    -v ./tmp/output/:/data/output/:z \
    -e LOGAN_INPUT_FILES="/data/input/Linux_2k.log" \
    -e LOGAN_OUTPUT_DIR=/data/output/ \
    ghcr.io/log-analyzer/logan:latest

Environment Variables

Variable Default Description
LOGAN_INPUT_FILES `` Input files/directories (comma-separated for multiple)
LOGAN_INPUT_GLOB `` Input file pattern (glob) for matching multiple files
LOGAN_OUTPUT_DIR /data/output Output directory for analysis results
LOGAN_TIME_RANGE all-data Time range filter: all-data, 1-day, 2-day, ..., 1-week, 2-week, 1-month
LOGAN_MODEL_TYPE zero_shot Model type: zero_shot, similarity, custom
LOGAN_MODEL crossencoder Model for classification: bart, crossencoder, or custom HuggingFace model
LOGAN_DEBUG_MODE true Enable debug mode (saves additional metadata files)
LOGAN_PROCESS_ALL_FILES false Process all text-based files irrespective of file extension
LOGAN_PROCESS_LOG_FILES true Process .log files found in directories
LOGAN_PROCESS_TXT_FILES false Process .txt files found in directories
LOGAN_CLEAN_UP false Clean output directory before running

Build Container Image

If you want to customize the container image, you can clone this repository and build it manually:

podman build -t logan -f Containerfile .

Option 2 - Local

You can also directly clone this repository and set up the project without using a container. Make sure you have Python 3 and uv available on your system.

# Setup venv
uv venv
source .venv/bin/activate

uv pip install -r requirements.txt

# Run Log Analysis
uv run logan analyze \
    -f "examples/Linux_2k.log" \
    -o "tmp/output"

How to View the Reports (Output)

uv run logan view -d "tmp/output"

# server should be available at http://localhost:8000/log_diagnosis

MCP Server (for AI Agents)

LogAn exposes its analysis capabilities via the Model Context Protocol (MCP), allowing AI agents (Claude Desktop, Claude Code, custom agents) to analyze logs programmatically.

Setup

# Install with MCP dependencies
uv pip install -e ".[mcp]"

Running the Server

# stdio transport (for Claude Desktop / Claude Code)
logan-mcp

# HTTP transport (for remote agents)
logan-mcp --transport streamable-http

Analysis results are stored in ~/.logan/runs/<timestamp>/ by default.

Available Tools

Tool Description
analyze_logs Run the full analysis pipeline (preprocessing, Drain3 templatization, anomaly detection). Returns each unique log template with its representative log line, golden signal, fault categories, and occurrence count.
extract_templates Extract unique log patterns via Drain3 without ML classification. Fast (seconds) — useful for quickly understanding log structure before deciding to run full analysis.

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "logan": {
      "command": "logan-mcp"
    }
  }
}

Testing with MCP Inspector

mcp dev logan/mcp/server.py

Examples

Check out tutorials for more examples on advanced usages.

🔥 Citation

If you use LogAn for publication, please cite the following research papers:

Authors & Contributors

This project was originally developed by IBM Research and is actively supported and maintained by Red Hat.

IBM Research

  • Pranjal Gupta
  • Harshit Kumar
  • Prateeti Mohapatra

Red Hat

  • Pradeep Surisetty
  • Pravin Satpute
  • Rahul Shetty
  • Jan Hutar
  • Nikhil Jain

We welcome contributions from the community!