Turning Server Logs into Incident Summaries with Java and Groq

I built a small Java CLI that uses Groq’s LLM API to turn noisy server logs into structured incident summaries: root cause, severity, affected components, and suggested fixes.

Introduction

Server logs are useful, but during an incident they can also become overwhelming.

A single failure can produce hundreds or thousands of lines in a few minutes. You search for ERROR, skim stack traces, follow timestamps, jump between services, and slowly piece together what actually happened.

The problem is not that logs are useless. The problem is that logs are raw events, not explanations.

I built ai-log-analyzer to explore a simple idea:

Can a Java CLI turn noisy server logs into a short, structured incident summary using an LLM?

This is not meant to replace observability platforms, incident response workflows, or proper monitoring. It is a small developer tool that shows how LLMs can help summarize unstructured operational data.

The goal was simple:

Input: a plain-text log file
Processing: split the file into LLM-friendly chunks
Output: root cause, severity, affected components, fix suggestions, and summary
Constraint: keep the setup minimal and easy to run locally

The Problem: Logs Are Events, Not Intelligence

Here is a familiar debugging flow:

A service starts failing.
You open the logs.
You see a wall of timestamps, warnings, retries, and stack traces.
You grep for ERROR.
You still have to figure out which event actually matters.

Logs tell you what happened. They do not always tell you why it happened or what to do next.

That analysis still lands on the engineer.

This project tries to reduce that manual step. Instead of reading every line yourself, the tool sends chunks of logs to an LLM and asks for a structured analysis.

Architecture

The architecture is intentionally small.

The project has three main pieces:

LogChunker — reads the log file and breaks it into smaller chunks
GroqClient — sends each chunk to Groq’s API and parses the response
AnalysisResult — stores the structured result returned by the model

Why Groq?

Groq has a straightforward API, low-latency inference, and easy access to models like llama-3.3-70b-versatile. For this project, I wanted something simple enough to call from a Java CLI without adding unnecessary infrastructure.

Why Java 21 HttpClient?

Java 21’s built-in HttpClient is good enough for this use case. I did not want to add an external HTTP dependency just to make one API call.

Why Maven Shade?

The Maven Shade plugin produces a single executable JAR. That makes the tool easy to build and run without classpath issues.

Project Structure

java-ai-log-analyzer/
├── pom.xml
├── README.md
├── sample-logs/
│   └── app.log
└── src/main/java/com/mulhaq/loganalyzer/
    ├── LogAnalyzer.java      # main entry point and CLI handling
    ├── GroqClient.java       # Groq API calls
    ├── LogChunker.java       # reads and chunks log files
    └── AnalysisResult.java   # structured analysis result

Stack and Tooling

The project uses:

Java 21
Maven
Jackson for JSON parsing
Groq API
Maven Shade plugin for a runnable JAR

The build command is:

mvn clean package

The output is:

target/java-ai-log-analyzer-1.0-shaded.jar

Key Implementation Pieces

1. LogChunker: Splitting the Log File

LLMs have context limits, so the tool does not send the entire log file in one request. It splits the file into smaller chunks.

public class LogChunker {
    private static final int CHUNK_SIZE = 3000;

    public static List<String> chunkLogFile(String filePath) throws Exception {
        String content = Files.readString(Paths.get(filePath));
        List<String> chunks = new ArrayList<>();
        int length = content.length();

        for (int i = 0; i < length; i += CHUNK_SIZE) {
            int end = Math.min(i + CHUNK_SIZE, length);
            chunks.add(content.substring(i, end));
        }

        return chunks;
    }
}

The current version uses a simple character-based chunking strategy. It works for a prototype, but a production version should be smarter: chunk by timestamp ranges, request boundaries, stack traces, or service sections.

2. GroqClient: Calling the LLM API

The GroqClient sends each chunk to Groq and asks for a structured JSON response.

public class GroqClient {
    private static final String API_URL = "https://api.groq.com/openai/v1/chat/completions";
    private static final String MODEL = "llama-3.3-70b-versatile";

    private final String apiKey;
    private final HttpClient httpClient;
    private final ObjectMapper mapper;

    public AnalysisResult analyzeChunk(String logChunk) throws Exception {
        String prompt = "Analyze this server log chunk and provide: root cause, "
                + "affected components, severity (critical/high/medium/low), fix suggestions, "
                + "and a summary. Return as JSON with keys: rootCause, affectedComponents, "
                + "severity, fixSuggestions, summary.\n\nLog:\n" + logChunk;

        String requestBody = mapper.writeValueAsString(Map.of(
                "model", MODEL,
                "messages", List.of(Map.of("role", "user", "content", prompt)),
                "temperature", 0.3
        ));

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(API_URL))
                .header("Authorization", "Bearer " + apiKey)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        HttpResponse<String> response = httpClient.send(
                request,
                HttpResponse.BodyHandlers.ofString()
        );

        if (response.statusCode() != 200) {
            throw new RuntimeException("Groq API error: " + response.statusCode());
        }

        var responseJson = mapper.readTree(response.body());
        String content = responseJson.get("choices")
                .get(0)
                .get("message")
                .get("content")
                .asText();

        return mapper.readValue(content, AnalysisResult.class);
    }
}

One practical lesson from this build: model names can change.

I originally used llama3-8b-8192, but that model was later unavailable. I switched to llama-3.3-70b-versatile, and the output quality improved. In a real tool, I would make the model configurable instead of hardcoding it.

3. AnalysisResult: Structuring the Output

The model response is parsed into a simple Java object.

public class AnalysisResult {
    @JsonProperty("rootCause")
    public String rootCause;

    @JsonProperty("affectedComponents")
    public List<String> affectedComponents;

    @JsonProperty("severity")
    public String severity;

    @JsonProperty("fixSuggestions")
    public List<String> fixSuggestions;

    @JsonProperty("summary")
    public String summary;
}

This keeps the CLI output predictable and easier to consume later if I want to write results to JSON, Markdown, or another system.

4. LogAnalyzer: The CLI Entry Point

The main class reads the API key, chunks the log file, sends each chunk to Groq, and prints the analysis.

public class LogAnalyzer {
    public static void main(String[] args) throws Exception {
        if (args.length == 0) {
            System.err.println("Usage: java -jar java-ai-log-analyzer-1.0-shaded.jar <log-file>");
            System.exit(1);
        }

        String apiKey = System.getenv("GROQ_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("Error: GROQ_API_KEY environment variable not set.");
            System.exit(1);
        }

        List<String> chunks = LogChunker.chunkLogFile(args[0]);
        GroqClient client = new GroqClient(apiKey);

        System.out.println("=== AI-Powered Log Analyzer ===\n");
        System.out.println("Log file: " + args[0]);
        System.out.println("Total chunks: " + chunks.size() + "\n");

        for (int i = 0; i < chunks.size(); i++) {
            System.out.println("--- Chunk " + (i + 1) + " of " + chunks.size() + " ---");

            AnalysisResult result = client.analyzeChunk(chunks.get(i));

            System.out.println("Root Cause: " + result.rootCause);
            System.out.println("Severity: " + result.severity);
            System.out.println("Affected Components:");
            result.affectedComponents.forEach(c -> System.out.println(" - " + c));
            System.out.println("Fix Suggestions:");
            result.fixSuggestions.forEach(s -> System.out.println(" - " + s));
            System.out.println("Summary: " + result.summary + "\n");
        }

        System.out.println("=== Analysis Complete ===");
    }
}

Example Output

I ran it against a small sample log file included in the repo.

=== AI-Powered Log Analyzer ===
Log file: sample-logs/app.log
File size: 3.70 KB
Reading and chunking log file...
Total chunks: 2

--- Chunk 1 of 2 ---
Root Cause: Database connection pool exhaustion due to prolonged request processing
Severity: critical
Affected Components:
 - DatabasePool
 - AuthService
 - CacheManager
 - DataSyncService
 - ApiGateway
 - RequestHandler
Fix Suggestions:
 - Increase the database connection pool size
 - Optimize database queries to reduce connection usage
 - Implement connection timeout and retry mechanisms
 - Monitor and alert on connection pool utilization
 - Regularly check for and resolve data inconsistencies
Summary: The application experienced a critical outage due to database connection pool exhaustion. Requests were queued and timed out as new connections could not be established.

--- Chunk 2 of 2 ---
Root Cause: Unknown, but a repair was initiated
Severity: low
Affected Components:
 - Database
 - Connection Pool
 - Cache Cluster
 - Request Handler
 - Data Sync Service
Fix Suggestions:
 - Monitor system logs for similar issues
 - Verify database consistency regularly
 - Review connection pool and cache cluster configurations
Summary: The system experienced an issue requiring a database consistency repair. Repair was successful and all components are now fully operational.

=== Analysis Complete ===

That is the main value of this project: noisy logs become a short, structured incident summary.

It is not perfect, but it gives an engineer a faster starting point.

Privacy Note

Logs can contain sensitive information: tokens, emails, customer IDs, internal URLs, stack traces, headers, and infrastructure details.

Before sending logs to any external LLM API, scrub sensitive data.

For a production-grade version, I would add a redaction layer before the API call. That layer should remove or mask:

API keys
access tokens
emails
IP addresses where needed
customer identifiers
internal service URLs
request headers
personally identifiable information

This project should be treated as a local developer prototype unless proper redaction and security controls are added.

Limitations

This is not a replacement for a full observability pipeline.

A few limitations are worth calling out:

The analyzer depends on the quality of the model response.
It processes chunks independently, so cross-chunk reasoning is limited.
The current version does not deduplicate repeated errors.
It does not validate every model response against a strict schema before parsing.
Very large logs should be pre-filtered or split before analysis.
The chunking strategy is simple and may split related events across chunks.
Sensitive logs should be scrubbed before being sent to an external API.

For a production version, I would add structured validation, retries, redaction, aggregation across chunks, and better error handling.

How to Run It Yourself

Prerequisites

Java 21
Maven 3.8+
Groq API key from console.groq.com

Steps

# 1. Set your API key
export GROQ_API_KEY="your-api-key-here"

# 2. Clone the repo
git clone https://github.com/mulhaq/blogs
cd blogs/java-ai-log-analyzer

# 3. Build
mvn clean package

# 4. Run against the sample log
java -jar target/java-ai-log-analyzer-1.0-shaded.jar sample-logs/app.log

# 5. Optional: save output to a file
java -jar target/java-ai-log-analyzer-1.0-shaded.jar sample-logs/app.log > analysis.txt

Common Issues

GROQ_API_KEY not found

Make sure the variable is exported in your current shell session.

Connection timeout

You may be hitting rate limits or network issues. Wait and retry.

Out of memory on huge files

Pre-split large logs before analysis:

split -l 1000 app.log app-log-part-

Then analyze each batch separately.

What I Would Improve Next

There are several directions I would take this project next.

1. Smarter Chunking

Instead of splitting every 3000 characters, chunk logs by timestamp, request ID, trace ID, or stack trace boundary.

2. Aggregated Summary

Right now each chunk is analyzed separately. A better version would produce a final summary across all chunks.

3. Redaction Layer

Before calling the LLM API, detect and mask secrets, emails, tokens, and internal identifiers.

4. Schema Validation

The model is asked to return JSON, but production code should validate and repair malformed responses.

5. Streaming Mode

A future version could tail a live log file and analyze new chunks as they arrive.

6. Observability Integrations

The results could be sent to tools like Grafana Loki, Datadog, Slack, or PagerDuty.

7. Custom Severity Rules

Different teams define severity differently. A config file could let teams define what critical, high, or medium means in their environment.

Conclusion

Logs are one of the most valuable sources of operational truth, but they are not always easy to reason about during an incident.

This project is a small experiment in using LLMs as a debugging assistant. The LLM does not replace engineering judgment, but it can help summarize noisy logs, identify likely causes, and suggest starting points for investigation.

The broader pattern is useful:

Find a repetitive engineering task, wrap it in a small tool, and use an LLM to reduce the manual analysis step.

Logs are one example. The same pattern could apply to exception traces, failed CI logs, pull request diffs, incident notes, or deployment summaries.

For me, the value is not just the tool itself. It is the workflow: take a common engineering pain point, build a focused implementation, test it on a realistic input, document the tradeoffs, and keep improving it.

Full source code: https://github.com/mulhaq/blogs/tree/main/java-ai-log-analyzer

Tags: #java #ai #groq #devtools

推荐订阅源

DEV Community