# LLM Log Analyzer
[](https://badge.fury.io/py/llm-log-analyzer)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A log analyzer for CI/CD pipelines (Jenkins, GitLab CI, GitHub Actions) that leverages Large Language Models to automatically detect and explain the root cause of failures, suggesting possible fixes.
This project originated from the difficulty of diagnosing issues in Unity build logs, which are notoriously verbose and hard to navigate — especially for less experienced developers. While optimized for Unity by default, the analyzer is fully configurable and can be adapted to any kind of build or runtime logs.
Feel free to contribute with new presets or refinements.
## Features
- **Efficient Processing**: Handles very large logs (>50MB) using streaming techniques
- **Flexible AI Models**: Support for multiple LLM models (Claude, Gemini, OpenAI models)
- **Structured Output**: Provides both human-friendly summaries and machine-readable JSON
- **CI-Ready**: Designed for seamless integration with Jenkins, GitLab CI, and other platforms
- **Configurable**: Customizable error patterns and prompts for different log types
- **Smart Filtering**: Extracts only relevant error information to optimize LLM results
- **Unity-Optimized**: Includes Unity-specific and generic patterns by default
## Installation
### Using pip (Recommended)
```bash
pip install llm-log-analyzer
```
### From GitHub (Development)
```bash
pip install git+https://github.com/renatoaf/llm-log-analyzer
# or pip3 install git+ssh://git@github.com/renatoaf/llm-log-analyzer
```
### Cloning the repo
1. Clone this repository:
```bash
git clone https://github.com/renatoaf/llm-log-analyzer
cd llm-log-analyzer
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
## Setup
Set up API keys for your preferred LLM provider:
**For Gemini:**
```bash
export GOOGLE_API_KEY="your_gemini_api_key"
```
**For OpenAI:**
```bash
export OPENAI_API_KEY="your_openai_api_key"
```
**For Claude:**
```bash
export ANTHROPIC_API_KEY="your_anthropic_api_key"
```
or
```bash
export AWS_BEARER_TOKEN_BEDROCK="your_aws_bearer_token"
export AWS_REGION="your_aws_region" # defaults to us-east-1
```
For using Claude through AWS Bedrock.
**Note**: The analyzer will default to Gemini. You can get a Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey).
## Usage
The usages refer to the package being installed via pip. If you cloned the repo, replace `llm-log-analyzer` by `python3 analyze_log.py` (inside `src/llm_log_analyzer`).
### Basic Usage
```bash
# Check available LLM providers and their status
llm-log-analyzer --list-providers
# Basic analysis (uses generic preset by default)
llm-log-analyzer application.log
# Use Unity preset for Unity build logs
llm-log-analyzer build.log -P unity
# Specify LLM provider with presets
llm-log-analyzer server.log -P generic --provider openai
llm-log-analyzer build.log -P unity --provider gemini
llm-log-analyzer build.log -P unity --provider claude
# Use custom API key with presets
llm-log-analyzer system.log -P generic --provider openai --api-key your_key
llm-log-analyzer build.log -P unity --provider claude --api-key your_key
# Advanced options with presets
llm-log-analyzer app.log -P generic --tail-lines 5000 --output-dir results/ --debug
# Manual file specification
llm-log-analyzer server.log --patterns-file patterns/generic.txt --prompt-file prompts/generic.txt
```
### Command Line Options
Run:
```
llm-log-analyzer -h
```
For detailed options and usage examples.
### Analysis Presets
The analyzer now supports **presets** that combine pattern and prompt files for common use cases. This makes it easier to switch between different types of log analysis.
#### Available Presets
| Preset | Description | Pattern File | Prompt File |
|--------|-------------|-------------|-------------|
| `generic` | General purpose analysis for any application logs | `patterns/generic.txt` | `prompts/generic.txt` |
| `unity` | Unity game engine build logs with game-specific patterns | `patterns/unity.txt` | `prompts/unity.txt` |
#### Using Presets
```bash
# Use preset (recommended approach)
llm-log-analyzer build.log -P unity
llm-log-analyzer server.log -P generic
# Override individual files while using a preset
llm-log-analyzer build.log -P unity --prompt "Focus on memory leaks in Unity builds"
llm-log-analyzer build.log -P generic --patterns-file my-custom-patterns.txt
# Manual file specification
llm-log-analyzer build.log --patterns-file patterns/unity.txt --prompt-file prompts/unity.txt
```
**Default Behavior:** If no preset is specified, the analyzer defaults to the `generic` preset, making it suitable for any type of log analysis out of the box. Beware that this wasn't optimized yet, so results may feel generic.
### Output Files
The analyzer generates two output files:
1. **`analysis.json`** - Machine-readable structured analysis:
```json
{
"root_cause": "Script compilation failed due to a missing definition for 'Armadillo' in the 'CharacterEnum' enum. This suggests a new character was added without updating the enum accordingly.",
"relevant_lines": [
"Assets/Scripts/Gameplay/Controllers/Player/CharacterSoundControllerFactory.cs(148,66): error CS0117: 'CharacterEnum' does not contain a definition for 'Armadillo'",
"Error building Player because scripts have compile errors in the editor"
],
"confidence": 0.95,
"action_suggestion": "Add a definition for the 'Armadillo' character to the 'CharacterEnum' enum in the CharacterSoundControllerFactory.cs file. Ensure the enum is updated whenever new characters are introduced.",
"human_summary": "The Unity build failed due to a script compilation error. The error message indicates that `CharacterEnum` is missing a definition for 'Armadillo'. This likely happened because a new character, 'Armadillo', was added without updating the corresponding enum. To fix this, add a new entry for 'Armadillo' to the `CharacterEnum` enum in the `CharacterSoundControllerFactory.cs` file."
}
```
2. **`analysis.md`** - Human-friendly Markdown summary for Slack/MR comments:
```markdown
# Build Analysis Report
## Summary
The Unity build failed due to a script compilation error. The error message indicates that `CharacterEnum` does not contain a definition for `Armadillo`. This likely means a new character was added without updating the enum. To fix this, add `Armadillo` to the `CharacterEnum` or correct the reference in `CharacterSoundControllerFactory.cs` if a different character was intended.
## Analysis Configuration
**Provider:** GeminiProvider
**Models Used:**
- Chunk Analysis: gemini-1.5-flash
- Final Aggregation: gemini-2.5-pro
**Processing Settings:**
- Max Chunks: 20
- Max Workers: 4
## Analysis Details
**Root Cause:** Script compilation error due to missing definition for 'Armadillo' in 'CharacterEnum'
**Confidence:** 🟢 95.0%
## Action Items
Add the 'Armadillo' definition to the 'CharacterEnum' or correct the reference in 'CharacterSoundControllerFactory.cs' if it's intended to be a different character.
## Relevant Log Lines
Assets/Scripts/Gameplay/Controllers/Player/CharacterSoundControllerFactory.cs(148,66): error CS0117: 'CharacterEnum' does not contain a definition for 'Armadillo'
Error building Player because scripts have compile errors in the editor
```
### Exit Codes
- `0`: No significant failures detected in log
- `1`: Failures found and analyzed
- `2`: Analysis failed (e.g., file not found, API errors)
## LLM Provider Comparison
The analyzer supports multiple LLM providers to fit different needs and budgets:
### Claude (Anthropic)
- **Cost**: Pay-per-use pricing, very expensive
- **Speed**: Fast, but more expensive per request
- **Accuracy**: Excellent, especially for complex log analysis and suggestions for solution
- **Setup**: Requires paid Anthropic account
**Best for**: Complex logs, when you need solution accuracy
### GPT (OpenAI)
- **Cost**: Pay-per-use pricing with competitive rates
- **Speed**: Fast with good throughput
- **Accuracy**: Good for most log analysis tasks
- **Setup**: Requires OpenAI API key from [OpenAI Platform](https://platform.openai.com)
**Best for**: Balanced cost and performance
### Gemini (Google)
- **Cost**: Free tier with generous limits
- **Speed**: Very fast (especially Gemini 1.5 Flash)
- **Accuracy**: Good for most log analysis tasks
- **Setup**: Get API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
**Best for**: CI environments, frequent analysis
Gemini works exceptionally well for Unity builds use case, even with the deprecated Gemini 1.5 models. Given its strong performance and competitive pricing (as of September 2025), it is currently the recommended option for running this analyzer in CI environments.
## CI Integration
### Jenkins Pipeline
```groovy
pipeline {
agent any
environment {
GOOGLE_API_KEY = credentials('google-api-key')
OPENAI_API_KEY = credentials('openai-api-key') # Alternative
ANTHROPIC_API_KEY = credentials('anthropic-api-key') # Alternative
}
stages {
stage('Application Build') {
steps {
sh 'make build > build.log 2>&1'
}
post {
failure {
// Only run analyzer when build fails
echo "Build failed, analyzing logs..."
sh '''
llm-log-analyzer -P unity --output-dir ./analysis/ build.log
# Check if analysis found failures
if [ $? -eq 1 ]; then
echo "Build failures detected and analyzed"
fi
'''
// Archive analysis results
archiveArtifacts artifacts: 'analysis/*', allowEmptyArchive: true
// Publish results to Slack/Teams
script {
if (fileExists('analysis/analysis.md')) {
def analysis = readFile('analysis/analysis.md')
slackSend(
channel: '#builds',
color: 'danger',
message: "🚨 Build Failed - Analysis Results:\n```${analysis}```"
)
}
}
}
always {
// Archive build log for reference
archiveArtifacts artifacts: 'build.log', allowEmptyArchive: true
archiveArtifacts artifacts: 'analysis.md', allowEmptyArchive: true
}
}
}
}
}
```
### GitLab CI
```yaml
# .gitlab-ci.yml
variables:
GOOGLE_API_KEY: $GOOGLE_API_KEY
OPENAI_API_KEY: $OPENAI_API_KEY # Alternative
ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY # Alternative
stages:
- build
- analyze
build_app:
stage: build
script:
- make build > build.log 2>&1
artifacts:
when: always
paths:
- build.log
expire_in: 1 day
log_analysis:
stage: analyze
dependencies:
- build_app
script:
... install llm-log-analyzer ...
- llm-log-analyzer build.log --output-dir analysis/ -P unity
- |
if [ -f analysis/analysis.md ]; then
echo "## 🚨 Build Failed - Log Analysis Results" >> analysis_comment.md
cat analysis/analysis.md >> analysis_comment.md
# Optional: Post to merge request if available
if [ -n "$CI_MERGE_REQUEST_IID" ]; then
curl -X POST \
-H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
-F "body=@analysis_comment.md" \
"$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
fi
fi
artifacts:
when: always
paths:
- analysis/
expire_in: 1 week
when: on_failure
```
## Customization
The analyzer is highly configurable and can be adapted for different log types, environments, and specific project needs.
### Configuration for Different Log Types
#### Generic Application Logs (Default)
By default, the analyzer uses the generic preset suitable for any application logs:
```bash
llm-log-analyzer app.log # Uses generic preset by default
llm-log-analyzer app.log -P generic # Explicitly specify generic preset
```
#### Unity Build Logs
For Unity build logs, use the Unity preset with game-specific patterns and prompts:
```bash
llm-log-analyzer build.log -P unity # Uses Unity-specific patterns and prompts
```
#### Custom Log Types
Create your own patterns and prompts for specific applications:
1. **Create custom patterns file** (`custom_patterns.txt`):
```text
# Custom error patterns for MyApp
MyApp ERROR:
FATAL:
Application crashed
Database connection failed
```
2. **Create custom prompt file** (`custom_prompt.txt`):
```text
You are an iOS specialist investigating errors in a Xcode build log...
```
3. **Use custom configuration**:
```bash
# Start with a preset and override specific parts
llm-log-analyzer build.log -P generic --prompt "You are a DevOps expert analyzing Docker container logs. Look for ..."
llm-log-analyzer xcode.log -P generic --prompt "You are an iOS Developer investigating a crash..."
# Use completely custom files
llm-log-analyzer myapp.log --patterns-file custom_patterns.txt --prompt-file custom_prompt.txt
# Mix preset patterns with custom prompt
llm-log-analyzer build.log -P unity --prompt "Focus specifically on IL2CPP compilation issues..."
```
### Additional Context for Known Issues
You can provide additional context via a file to help the analyzer understand known issues and solutions specific to your project or CI environment. This is particularly useful for:
- Documenting recurring build failures and their solutions
- Providing project-specific troubleshooting information
- Adding context about infrastructure-specific issues
- Including known workarounds for common problems
**Creating a Context File:**
Create a text file (e.g., `context.txt`) with your known issues and solutions, example:
```text
# Unity Build Context
Known Issues:
- Unity 2021.3.5f1 has memory issues on Jenkins agents with <8GB RAM
- Android builds fail on Gradle 7.x due to dependency conflicts with com.google.firebase
- Network timeouts during package resolution in corporate networks
Common Solutions:
- Memory issues: Use agents with more memory or reduce build parallelism with --max-workers 2
- Gradle conflicts: Use Gradle 6.8 or update Firebase to v31.0.0+
- Unity license activation fails on new runners: requires manual activation or check license server connectivity
Build Environment Notes:
- Using GitLab CI with Docker containers
- Jenkins agents have variable memory (4-16GB)
- Corporate firewall may block some package repositories
...
```
**Usage:**
```bash
# Basic usage with context file
llm-log-analyzer build.log -P unity --additional-context-file context.txt
# Different context files for different environments
llm-log-analyzer unity-build.log -P unity --additional-context-file contexts/unity-context.txt
llm-log-analyzer server.log --additional-context-file contexts/server-context.txt
# Combine with other options
llm-log-analyzer build.log --additional-context-file team-knowledge.txt --verbose --debug --output-dir results/
```
**Best Practices for Context Files:**
- Keep context files versioned with your project
- Update context as you discover new issues and solutions
- Use clear headers and bullet points for readability
- Include environment-specific details (OS, versions, infrastructure)
- Document both problems AND their solutions
### Model Selection
Each provider uses optimized models for different tasks:
**OpenAI:**
- Chunk analysis: `gpt-4o-mini`
- Final aggregation: `gpt-4o-mini`
**Gemini:**
- Chunk analysis: `gemini-1.5-flash-latest`
- Final aggregation: `gemini-2.5-pro`
**Claude:** (directly via Anthropic API or AWS Bedrock)
- Chunk analysis: `claude-3-5-haiku-20241022`
- Final aggregation: `claude-3-5-sonnet-20241022`
You can customize these by using the parameters `--aggregation-model` and `--chunk-model`.
## Troubleshooting
### Common Issues
**API Rate Limits**
- The analyzer includes automatic retry with exponential backoff
- Consider using other models for chunk analysis to reduce costs
- Adjust `chunk-size` to reduce API calls
- Limit the number of chunks with `max-chunks`
- Fine tune your filters
**Memory Issues with Large Logs**
- The analyzer uses streaming processing to avoid loading entire logs
- Reduce tail-lines if needed
- Fine tune your filters
**Poor Analysis Quality**
- Ensure your filtered log contains actual error information
- Fine tune your error patterns to reduce noise
- Try increasing tail-lines to capture more context
- Run with debug option and check that error keywords are being detected properly by analyzing the `filtered_log.txt`
- Run with debug option and analyze the final output prompts
**Network/Connectivity**
- Set up proper proxy configuration if behind corporate firewall
- Verify API keys are correctly set
- Check if your network allows HTTPS connections to Anthropic/Gemini API
**JSON Parsing Errors (Gemini)**
- Error: `Invalid control character at: line X column Y`
- **Cause**: Gemini sometimes includes unescaped control characters in JSON responses
- **Solution**: The analyzer now automatically sanitizes JSON responses
- **Workaround**: Use a different provider if Gemini consistently fails: `--list-providers`
### Debug Mode
Enable debug mode (`-d`) and/or verbose logging (`-v`) to diagnose issues:
```bash
llm-log-analyzer -P unity Editor.log --debug
```
This will output debug files (filtered logs, prompt and model responses).
You can additionally run in verbose mode to show API request/response information and details about execution.
```bash
llm-log-analyzer -P unity Editor.log --verbose
```
## Optimization
- **Aggressive Filtering** – Irrelevant noise is stripped out automatically, keeping only error-related lines and context. This minimizes token usage while preserving diagnostic value.
- **Chunked Processing** – If the filtered log is still too large, it is split into smaller chunks. Each chunk is analyzed individually, and results are aggregated into a single root cause report.
- **Tail Limit** – Analysis prioritizes the most recent section of the log, where failures are most likely to occur, reducing cost and improving accuracy.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Submit a pull request
## License
MIT License - see LICENSE file for details.
---
Made with ❤️ for Unity developers tired of manually debugging build failures.
Raw data
{
"_id": null,
"home_page": null,
"name": "llm-log-analyzer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Renato Freitas <renatoaf.dev@gmail.com>",
"keywords": "unity, build, log, analyzer, ci, automation, ai, llm, root-cause-analysis",
"author": null,
"author_email": "Renato Freitas <renatoaf.dev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/46/7f/74bc27fc9ba363eb2b6db9c5e5c0f374e7021968142271e43fafc3d8b41d/llm_log_analyzer-1.2.0.tar.gz",
"platform": null,
"description": "# LLM Log Analyzer\n\n[](https://badge.fury.io/py/llm-log-analyzer)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA log analyzer for CI/CD pipelines (Jenkins, GitLab CI, GitHub Actions) that leverages Large Language Models to automatically detect and explain the root cause of failures, suggesting possible fixes.\n\nThis project originated from the difficulty of diagnosing issues in Unity build logs, which are notoriously verbose and hard to navigate \u2014 especially for less experienced developers. While optimized for Unity by default, the analyzer is fully configurable and can be adapted to any kind of build or runtime logs.\n\nFeel free to contribute with new presets or refinements.\n\n## Features\n\n- **Efficient Processing**: Handles very large logs (>50MB) using streaming techniques\n- **Flexible AI Models**: Support for multiple LLM models (Claude, Gemini, OpenAI models)\n- **Structured Output**: Provides both human-friendly summaries and machine-readable JSON\n- **CI-Ready**: Designed for seamless integration with Jenkins, GitLab CI, and other platforms\n- **Configurable**: Customizable error patterns and prompts for different log types\n- **Smart Filtering**: Extracts only relevant error information to optimize LLM results\n- **Unity-Optimized**: Includes Unity-specific and generic patterns by default\n\n## Installation\n\n### Using pip (Recommended)\n\n```bash\npip install llm-log-analyzer\n```\n\n### From GitHub (Development)\n\n```bash\npip install git+https://github.com/renatoaf/llm-log-analyzer\n# or pip3 install git+ssh://git@github.com/renatoaf/llm-log-analyzer\n```\n\n### Cloning the repo\n\n1. Clone this repository:\n```bash\ngit clone https://github.com/renatoaf/llm-log-analyzer\ncd llm-log-analyzer\n```\n\n2. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n## Setup\n\nSet up API keys for your preferred LLM provider:\n\n**For Gemini:**\n```bash\nexport GOOGLE_API_KEY=\"your_gemini_api_key\"\n```\n\n**For OpenAI:**\n```bash\nexport OPENAI_API_KEY=\"your_openai_api_key\"\n```\n\n**For Claude:**\n```bash\nexport ANTHROPIC_API_KEY=\"your_anthropic_api_key\"\n```\n\nor\n\n```bash\nexport AWS_BEARER_TOKEN_BEDROCK=\"your_aws_bearer_token\"\nexport AWS_REGION=\"your_aws_region\" # defaults to us-east-1\n```\n\nFor using Claude through AWS Bedrock.\n\n**Note**: The analyzer will default to Gemini. You can get a Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey).\n\n## Usage\n\nThe usages refer to the package being installed via pip. If you cloned the repo, replace `llm-log-analyzer` by `python3 analyze_log.py` (inside `src/llm_log_analyzer`).\n\n### Basic Usage\n\n```bash\n# Check available LLM providers and their status\nllm-log-analyzer --list-providers\n\n# Basic analysis (uses generic preset by default)\nllm-log-analyzer application.log\n\n# Use Unity preset for Unity build logs \nllm-log-analyzer build.log -P unity\n\n# Specify LLM provider with presets\nllm-log-analyzer server.log -P generic --provider openai\nllm-log-analyzer build.log -P unity --provider gemini\nllm-log-analyzer build.log -P unity --provider claude\n\n# Use custom API key with presets\nllm-log-analyzer system.log -P generic --provider openai --api-key your_key\nllm-log-analyzer build.log -P unity --provider claude --api-key your_key\n\n# Advanced options with presets\nllm-log-analyzer app.log -P generic --tail-lines 5000 --output-dir results/ --debug\n\n# Manual file specification\nllm-log-analyzer server.log --patterns-file patterns/generic.txt --prompt-file prompts/generic.txt\n```\n\n### Command Line Options\n\nRun:\n```\nllm-log-analyzer -h\n```\n\nFor detailed options and usage examples.\n\n### Analysis Presets\n\nThe analyzer now supports **presets** that combine pattern and prompt files for common use cases. This makes it easier to switch between different types of log analysis.\n\n#### Available Presets\n\n| Preset | Description | Pattern File | Prompt File |\n|--------|-------------|-------------|-------------|\n| `generic` | General purpose analysis for any application logs | `patterns/generic.txt` | `prompts/generic.txt` |\n| `unity` | Unity game engine build logs with game-specific patterns | `patterns/unity.txt` | `prompts/unity.txt` |\n\n#### Using Presets\n\n```bash\n# Use preset (recommended approach)\nllm-log-analyzer build.log -P unity\nllm-log-analyzer server.log -P generic\n\n# Override individual files while using a preset\nllm-log-analyzer build.log -P unity --prompt \"Focus on memory leaks in Unity builds\"\nllm-log-analyzer build.log -P generic --patterns-file my-custom-patterns.txt\n\n# Manual file specification\nllm-log-analyzer build.log --patterns-file patterns/unity.txt --prompt-file prompts/unity.txt\n```\n\n**Default Behavior:** If no preset is specified, the analyzer defaults to the `generic` preset, making it suitable for any type of log analysis out of the box. Beware that this wasn't optimized yet, so results may feel generic.\n\n### Output Files\n\nThe analyzer generates two output files:\n\n1. **`analysis.json`** - Machine-readable structured analysis:\n```json\n{\n \"root_cause\": \"Script compilation failed due to a missing definition for 'Armadillo' in the 'CharacterEnum' enum. This suggests a new character was added without updating the enum accordingly.\",\n \"relevant_lines\": [\n \"Assets/Scripts/Gameplay/Controllers/Player/CharacterSoundControllerFactory.cs(148,66): error CS0117: 'CharacterEnum' does not contain a definition for 'Armadillo'\",\n \"Error building Player because scripts have compile errors in the editor\"\n ],\n \"confidence\": 0.95,\n \"action_suggestion\": \"Add a definition for the 'Armadillo' character to the 'CharacterEnum' enum in the CharacterSoundControllerFactory.cs file. Ensure the enum is updated whenever new characters are introduced.\",\n \"human_summary\": \"The Unity build failed due to a script compilation error. The error message indicates that `CharacterEnum` is missing a definition for 'Armadillo'. This likely happened because a new character, 'Armadillo', was added without updating the corresponding enum. To fix this, add a new entry for 'Armadillo' to the `CharacterEnum` enum in the `CharacterSoundControllerFactory.cs` file.\"\n}\n```\n\n2. **`analysis.md`** - Human-friendly Markdown summary for Slack/MR comments:\n```markdown\n# Build Analysis Report\n\n## Summary\nThe Unity build failed due to a script compilation error. The error message indicates that `CharacterEnum` does not contain a definition for `Armadillo`. This likely means a new character was added without updating the enum. To fix this, add `Armadillo` to the `CharacterEnum` or correct the reference in `CharacterSoundControllerFactory.cs` if a different character was intended.\n\n## Analysis Configuration\n\n**Provider:** GeminiProvider\n\n**Models Used:** \n- Chunk Analysis: gemini-1.5-flash\n- Final Aggregation: gemini-2.5-pro\n\n**Processing Settings:**\n- Max Chunks: 20\n- Max Workers: 4\n\n## Analysis Details\n\n**Root Cause:** Script compilation error due to missing definition for 'Armadillo' in 'CharacterEnum'\n\n**Confidence:** \ud83d\udfe2 95.0%\n\n## Action Items\nAdd the 'Armadillo' definition to the 'CharacterEnum' or correct the reference in 'CharacterSoundControllerFactory.cs' if it's intended to be a different character.\n\n## Relevant Log Lines\nAssets/Scripts/Gameplay/Controllers/Player/CharacterSoundControllerFactory.cs(148,66): error CS0117: 'CharacterEnum' does not contain a definition for 'Armadillo'\n\nError building Player because scripts have compile errors in the editor\n```\n\n### Exit Codes\n\n- `0`: No significant failures detected in log\n- `1`: Failures found and analyzed\n- `2`: Analysis failed (e.g., file not found, API errors)\n\n## LLM Provider Comparison\n\nThe analyzer supports multiple LLM providers to fit different needs and budgets:\n\n### Claude (Anthropic)\n- **Cost**: Pay-per-use pricing, very expensive \n- **Speed**: Fast, but more expensive per request\n- **Accuracy**: Excellent, especially for complex log analysis and suggestions for solution\n- **Setup**: Requires paid Anthropic account\n\n**Best for**: Complex logs, when you need solution accuracy\n\n### GPT (OpenAI)\n- **Cost**: Pay-per-use pricing with competitive rates\n- **Speed**: Fast with good throughput\n- **Accuracy**: Good for most log analysis tasks\n- **Setup**: Requires OpenAI API key from [OpenAI Platform](https://platform.openai.com)\n\n**Best for**: Balanced cost and performance\n\n### Gemini (Google)\n- **Cost**: Free tier with generous limits\n- **Speed**: Very fast (especially Gemini 1.5 Flash)\n- **Accuracy**: Good for most log analysis tasks\n- **Setup**: Get API key from [Google AI Studio](https://makersuite.google.com/app/apikey)\n\n**Best for**: CI environments, frequent analysis\n\nGemini works exceptionally well for Unity builds use case, even with the deprecated Gemini 1.5 models. Given its strong performance and competitive pricing (as of September 2025), it is currently the recommended option for running this analyzer in CI environments.\n\n## CI Integration\n\n### Jenkins Pipeline\n\n```groovy\npipeline {\n agent any\n \n environment {\n GOOGLE_API_KEY = credentials('google-api-key')\n OPENAI_API_KEY = credentials('openai-api-key') # Alternative\n ANTHROPIC_API_KEY = credentials('anthropic-api-key') # Alternative\n }\n \n stages {\n stage('Application Build') {\n steps {\n sh 'make build > build.log 2>&1'\n }\n post {\n failure {\n // Only run analyzer when build fails\n echo \"Build failed, analyzing logs...\"\n sh '''\n llm-log-analyzer -P unity --output-dir ./analysis/ build.log\n \n # Check if analysis found failures\n if [ $? -eq 1 ]; then\n echo \"Build failures detected and analyzed\"\n fi\n '''\n \n // Archive analysis results\n archiveArtifacts artifacts: 'analysis/*', allowEmptyArchive: true\n \n // Publish results to Slack/Teams\n script {\n if (fileExists('analysis/analysis.md')) {\n def analysis = readFile('analysis/analysis.md')\n slackSend(\n channel: '#builds',\n color: 'danger',\n message: \"\ud83d\udea8 Build Failed - Analysis Results:\\n```${analysis}```\"\n )\n }\n }\n }\n always {\n // Archive build log for reference\n archiveArtifacts artifacts: 'build.log', allowEmptyArchive: true\n archiveArtifacts artifacts: 'analysis.md', allowEmptyArchive: true\n }\n }\n }\n }\n}\n```\n\n### GitLab CI\n\n```yaml\n# .gitlab-ci.yml\nvariables:\n GOOGLE_API_KEY: $GOOGLE_API_KEY\n OPENAI_API_KEY: $OPENAI_API_KEY # Alternative\n ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY # Alternative\n\nstages:\n - build\n - analyze\n\nbuild_app:\n stage: build\n script:\n - make build > build.log 2>&1\n artifacts:\n when: always\n paths:\n - build.log\n expire_in: 1 day\n\nlog_analysis:\n stage: analyze\n dependencies:\n - build_app\n script:\n ... install llm-log-analyzer ...\n - llm-log-analyzer build.log --output-dir analysis/ -P unity\n - |\n if [ -f analysis/analysis.md ]; then\n echo \"## \ud83d\udea8 Build Failed - Log Analysis Results\" >> analysis_comment.md\n cat analysis/analysis.md >> analysis_comment.md\n \n # Optional: Post to merge request if available\n if [ -n \"$CI_MERGE_REQUEST_IID\" ]; then\n curl -X POST \\\n -H \"PRIVATE-TOKEN: $GITLAB_TOKEN\" \\\n -F \"body=@analysis_comment.md\" \\\n \"$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes\"\n fi\n fi\n artifacts:\n when: always\n paths:\n - analysis/\n expire_in: 1 week\n when: on_failure\n```\n\n## Customization\n\nThe analyzer is highly configurable and can be adapted for different log types, environments, and specific project needs.\n\n### Configuration for Different Log Types\n\n#### Generic Application Logs (Default)\nBy default, the analyzer uses the generic preset suitable for any application logs:\n\n```bash\nllm-log-analyzer app.log # Uses generic preset by default\nllm-log-analyzer app.log -P generic # Explicitly specify generic preset\n```\n\n#### Unity Build Logs\nFor Unity build logs, use the Unity preset with game-specific patterns and prompts:\n\n```bash\nllm-log-analyzer build.log -P unity # Uses Unity-specific patterns and prompts\n```\n\n#### Custom Log Types\nCreate your own patterns and prompts for specific applications:\n\n1. **Create custom patterns file** (`custom_patterns.txt`):\n```text\n# Custom error patterns for MyApp\nMyApp ERROR:\nFATAL:\nApplication crashed\nDatabase connection failed\n```\n\n2. **Create custom prompt file** (`custom_prompt.txt`):\n```text\nYou are an iOS specialist investigating errors in a Xcode build log...\n```\n\n3. **Use custom configuration**:\n```bash\n# Start with a preset and override specific parts\nllm-log-analyzer build.log -P generic --prompt \"You are a DevOps expert analyzing Docker container logs. Look for ...\"\n\nllm-log-analyzer xcode.log -P generic --prompt \"You are an iOS Developer investigating a crash...\"\n\n# Use completely custom files\nllm-log-analyzer myapp.log --patterns-file custom_patterns.txt --prompt-file custom_prompt.txt\n\n# Mix preset patterns with custom prompt\nllm-log-analyzer build.log -P unity --prompt \"Focus specifically on IL2CPP compilation issues...\"\n```\n\n### Additional Context for Known Issues\n\nYou can provide additional context via a file to help the analyzer understand known issues and solutions specific to your project or CI environment. This is particularly useful for:\n\n- Documenting recurring build failures and their solutions\n- Providing project-specific troubleshooting information \n- Adding context about infrastructure-specific issues\n- Including known workarounds for common problems\n\n**Creating a Context File:**\n\nCreate a text file (e.g., `context.txt`) with your known issues and solutions, example:\n\n```text\n# Unity Build Context\nKnown Issues:\n- Unity 2021.3.5f1 has memory issues on Jenkins agents with <8GB RAM\n- Android builds fail on Gradle 7.x due to dependency conflicts with com.google.firebase\n- Network timeouts during package resolution in corporate networks\n\nCommon Solutions:\n- Memory issues: Use agents with more memory or reduce build parallelism with --max-workers 2\n- Gradle conflicts: Use Gradle 6.8 or update Firebase to v31.0.0+\n- Unity license activation fails on new runners: requires manual activation or check license server connectivity\n\nBuild Environment Notes:\n- Using GitLab CI with Docker containers\n- Jenkins agents have variable memory (4-16GB)\n- Corporate firewall may block some package repositories\n...\n```\n\n**Usage:**\n\n```bash\n# Basic usage with context file\nllm-log-analyzer build.log -P unity --additional-context-file context.txt\n\n# Different context files for different environments\nllm-log-analyzer unity-build.log -P unity --additional-context-file contexts/unity-context.txt\nllm-log-analyzer server.log --additional-context-file contexts/server-context.txt\n\n# Combine with other options\nllm-log-analyzer build.log --additional-context-file team-knowledge.txt --verbose --debug --output-dir results/\n```\n\n**Best Practices for Context Files:**\n\n- Keep context files versioned with your project\n- Update context as you discover new issues and solutions\n- Use clear headers and bullet points for readability\n- Include environment-specific details (OS, versions, infrastructure)\n- Document both problems AND their solutions\n\n### Model Selection\n\nEach provider uses optimized models for different tasks:\n\n**OpenAI:**\n- Chunk analysis: `gpt-4o-mini`\n- Final aggregation: `gpt-4o-mini`\n\n**Gemini:**\n- Chunk analysis: `gemini-1.5-flash-latest`\n- Final aggregation: `gemini-2.5-pro`\n\n**Claude:** (directly via Anthropic API or AWS Bedrock)\n- Chunk analysis: `claude-3-5-haiku-20241022`\n- Final aggregation: `claude-3-5-sonnet-20241022`\n\nYou can customize these by using the parameters `--aggregation-model` and `--chunk-model`.\n\n## Troubleshooting\n\n### Common Issues\n\n**API Rate Limits**\n- The analyzer includes automatic retry with exponential backoff\n- Consider using other models for chunk analysis to reduce costs\n- Adjust `chunk-size` to reduce API calls\n- Limit the number of chunks with `max-chunks`\n- Fine tune your filters\n\n**Memory Issues with Large Logs**\n- The analyzer uses streaming processing to avoid loading entire logs\n- Reduce tail-lines if needed\n- Fine tune your filters\n\n**Poor Analysis Quality**\n- Ensure your filtered log contains actual error information\n- Fine tune your error patterns to reduce noise\n- Try increasing tail-lines to capture more context\n- Run with debug option and check that error keywords are being detected properly by analyzing the `filtered_log.txt`\n- Run with debug option and analyze the final output prompts\n\n**Network/Connectivity**\n- Set up proper proxy configuration if behind corporate firewall\n- Verify API keys are correctly set\n- Check if your network allows HTTPS connections to Anthropic/Gemini API\n\n**JSON Parsing Errors (Gemini)**\n- Error: `Invalid control character at: line X column Y`\n- **Cause**: Gemini sometimes includes unescaped control characters in JSON responses\n- **Solution**: The analyzer now automatically sanitizes JSON responses\n- **Workaround**: Use a different provider if Gemini consistently fails: `--list-providers`\n\n### Debug Mode\n\nEnable debug mode (`-d`) and/or verbose logging (`-v`) to diagnose issues:\n\n```bash\nllm-log-analyzer -P unity Editor.log --debug\n```\n\nThis will output debug files (filtered logs, prompt and model responses).\n\nYou can additionally run in verbose mode to show API request/response information and details about execution.\n\n```bash\nllm-log-analyzer -P unity Editor.log --verbose\n```\n\n## Optimization\n\n- **Aggressive Filtering** \u2013 Irrelevant noise is stripped out automatically, keeping only error-related lines and context. This minimizes token usage while preserving diagnostic value.\n\n- **Chunked Processing** \u2013 If the filtered log is still too large, it is split into smaller chunks. Each chunk is analyzed individually, and results are aggregated into a single root cause report.\n\n- **Tail Limit** \u2013 Analysis prioritizes the most recent section of the log, where failures are most likely to occur, reducing cost and improving accuracy.\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n\n---\n\nMade with \u2764\ufe0f for Unity developers tired of manually debugging build failures.\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered log analyzer for CI environments using LLMs",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://github.com/renatoaf/llm-log-analyzer#readme",
"Homepage": "https://github.com/renatoaf/llm-log-analyzer",
"Issues": "https://github.com/renatoaf/llm-log-analyzer/issues",
"Repository": "https://github.com/renatoaf/llm-log-analyzer"
},
"split_keywords": [
"unity",
" build",
" log",
" analyzer",
" ci",
" automation",
" ai",
" llm",
" root-cause-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "de16acd12f6b0d7dc04fb89b132687c24b768f8b9569f86308c443cd2a1159d7",
"md5": "71ed206d0bdf2bba5202ee6c914dfed5",
"sha256": "7e09344c4f5719522d1cafeceb591e5c61f9dbded8490ad15d5676adfe767851"
},
"downloads": -1,
"filename": "llm_log_analyzer-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71ed206d0bdf2bba5202ee6c914dfed5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 39171,
"upload_time": "2025-10-22T19:16:02",
"upload_time_iso_8601": "2025-10-22T19:16:02.875926Z",
"url": "https://files.pythonhosted.org/packages/de/16/acd12f6b0d7dc04fb89b132687c24b768f8b9569f86308c443cd2a1159d7/llm_log_analyzer-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "467f74bc27fc9ba363eb2b6db9c5e5c0f374e7021968142271e43fafc3d8b41d",
"md5": "bfde241bfc67aec870427fb45532c56a",
"sha256": "7f952a5325a1c666254f8a5055b8cdc77c7d6cc0b136207739b8f0bcca0b7103"
},
"downloads": -1,
"filename": "llm_log_analyzer-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "bfde241bfc67aec870427fb45532c56a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 38097,
"upload_time": "2025-10-22T19:16:03",
"upload_time_iso_8601": "2025-10-22T19:16:03.997373Z",
"url": "https://files.pythonhosted.org/packages/46/7f/74bc27fc9ba363eb2b6db9c5e5c0f374e7021968142271e43fafc3d8b41d/llm_log_analyzer-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 19:16:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "renatoaf",
"github_project": "llm-log-analyzer#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "anthropic",
"specs": [
[
">=",
"0.34.0"
]
]
},
{
"name": "google-generativeai",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "boto3",
"specs": [
[
">=",
"1.28.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "tiktoken",
"specs": [
[
">=",
"0.5.0"
]
]
},
{
"name": "langchain-text-splitters",
"specs": [
[
">=",
"0.2.0"
]
]
}
],
"lcname": "llm-log-analyzer"
}
JSON
