Logsum Documentation

Intelligent Log Summarization & Automated Root-Cause Analysis powered by LLMs.

📌 Overview

Logsum is an AI-powered log analysis tool that leverages Large Language Models (LLMs) to parse, summarize, and diagnose complex application logs. Logsum quickly identifies issues, cites log evidence, and provides actionable code fixes.

Logsum is available in three distributions:

• 💻 CLI Application – Fast terminal-based log summarization from files or raw strings.
• 📦 NPM Package – Programmatic integration into Node.js / TypeScript applications.
• 🔌 VS Code Extension – In-editor log highlighting and automated diagnostic reports.

✨ Key Features

• 🔍 Automated Error Detection: Rapidly determines if logs contain critical errors, warnings, or normal operation traces.
• 🧾 Evidence-Based Analysis: Cites precise log excerpts and timestamps to back up every finding.
• 🛠️ Actionable Resolution: Generates step-by-step troubleshooting instructions and suggested code fixes.
• 🤖 LLM Agnostic: Compatible with local models (e.g., Ollama, LocalAI) and cloud providers (e.g., OpenAI, Anthropic, custom OpenAI-compatible endpoints).
• ⚡ Flexible Input Options: Pass logs via raw text strings or direct file paths

🧰 Ecosystem Overview

| Ecosystem | Use Case | Installation | | :--- | :--- | :--- | | CLI App | Terminal log inspection & shell integration | npm install -g logsum | | NPM Package | Programmatic usage in backend tools & pipelines | npm install logsum | | VS Code Extension | Native IDE highlighting & terminal output analysis | Search logsum by SpecialJayy |

🚀 Installation & Usage

1. 💻 CLI Application

The CLI tool allows you to summarize and diagnose logs directly from your command-line environment.

Installation

# Global installation for universal CLI access
npm install -g logsum

# Or run on demand with npx
npx logsum -h

CLI Command Options

| Flag | Name | Description | Default / Required | | :--- | :--- | :--- | :--- | | -h | --help | Show help menu and available options | Optional | | -s | --string | Pass log content directly as a raw string | Optional | | -p | --path | Pass path to a log file (.log, .txt, .json) | Optional | | -m | --model | Specify the LLM model name | Optional (Default: configured default) | | -u | --url | Custom LLM endpoint base URL | Optional (Default: http://localhost:13305/v1) | | -k | --key | API Key for authenticated LLM services | Optional (Default: ollama) |

Examples

Analyze logs from a file:

logsum -p ./logs/app-error.txt

Analyze raw log string:

logsum -s "2026-08-27 14:02:11 [ERROR] Connection refused at Database.connect (db.ts:42)"

2. 📦 NPM Package

Integrate Logsum directly into your Node.js or TypeScript applications to build automated error handling or log monitoring systems.

Installation

npm install logsum

Programmatic Usage

import { summarizeLogs } from 'logsum';

async function analyzeApplicationLogs() {
  const sampleLogs = `
    2026-08-27 14:02:11 [ERROR] Connection refused at Database.connect (db.ts:42)
    2026-08-27 14:02:12 [WARN] Retrying connection attempt 1/3...
    2026-08-27 14:02:15 [FATAL] Max retries reached. Database unreachable.
  `;

  try {
    /**
     * Function Signature:
     * summarizeLogs(logs: string, model?: string, url?: string, apiKey?: string): Promise<string>
     * 
     * Note: `apiKey` is optional and defaults to "ollama".
     */
    const result = await summarizeLogs(
      sampleLogs,
      'llama3',                  // Model name
      'http://localhost:11434/v1',  // Endpoint URL
      'ollama'                   // API Key
    );

    console.log('=== Logsum Diagnostic Report ===
');
    console.log(result);
  } catch (error) {
    console.error('Log Analysis Error:', error);
  }
}

analyzeApplicationLogs();

3. 🔌 VS Code Extension

Diagnose logs without leaving Visual Studio Code.

Installation

1. Open VS Code and navigate to the Extensions Tab (Ctrl+Shift+X or Cmd+Shift+X).
2. Search for logsum published by SpecialJayy.
3. Click Install.

Setup & Configuration

1. Open VS Code Settings (Ctrl+, / Cmd+,).
2. Search for logsum settings:
   • Model: Set your preferred LLM model (e.g., llama3, gpt-4o).
   • URL: Set the API endpoint (e.g., http://localhost:13305/v1).
   • API Key: Add your provider's API key if using paid cloud endpoints (defaults to ollama).

Step-by-Step Usage

1. Open any document or log file in VS Code.
2. Highlight the section of logs you wish to analyze.
3. Open the Command Palette (F1 or Ctrl+Shift+P / Cmd+Shift+P).
4. Type Summarize logs with logsum and select it.
5. Watch the summary and diagnostic output appear in the integrated terminal/output window once complete.

📊 Sample Output Structure

When Logsum completes processing, it delivers a formatted analysis report:

## 🚨 Log Summary Report

### Error Status: DETECTED

#### 1. Core Issue Summary
The service failed to establish a database connection, leading to a fatal application process exit after 3 failed retries.

#### 2. Log Evidence
- Line 2: `2026-08-27 14:02:11 [ERROR] Connection refused at Database.connect (db.ts:42)`
- Line 4: `2026-08-27 14:02:15 [FATAL] Max retries reached. Database unreachable.`

#### 3. Root Cause Analysis
The network socket to the database host was rejected. This typically occurs when:
- The database daemon (`postgresql` / `mysql`) is stopped.
- Host configuration (`DB_HOST` / `DB_PORT`) is misconfigured in `.env`.
- Port 5432 is blocked by network firewall rules.

#### 4. Recommended Fixes
1. Check if the database service is running: `systemctl status postgresql`
2. Verify environment connection string settings.
3. Test port connectivity using `nc -zv localhost 5432`.

⚙️ Configuration Defaults

By default, Logsum is configured to work out-of-the-box with Ollama running locally on your machine, enabling zero-cost and privacy-first log analysis:

• Default Endpoint URL: http://localhost:11434
• Default API Key: ollama

To switch to cloud providers (OpenAI, Groq, Anthropic, Azure), simply update the URL, Model, and API Key flags or configuration settings accordingly.

🤝 Contributing & Support

Contributions, issue reports, and feature requests are welcome!

• Author: SpecialJayy
• Repository: GitHub Repository
• Issue Tracker: Report an Issue

📄 License

This project is licensed under the MIT License.