Overview
Log Detective is a newly integrated analysis service that automatically examines failed Koji builds triggered by Packit on dist-git pull requests. Starting this month, whenever a scratch build fails, Packit sends the relevant logs to Log Detective, which returns a concise explanation of what went wrong and often suggests a fix. The process requires no manual configuration—no selecting logs or crafting prompts—and the results are presented directly in the Packit dashboard. This guide walks you through how Log Detective works, what it expects, and how to interpret its output. Whether you’re new to Fedora package maintenance or a seasoned packager, understanding this tool can save time and reduce guesswork.
Prerequisites
Before Log Detective can analyze a build failure, you need:
- A working Packit configuration for your project (typically a
.packit.yamlfile in your dist-git repository). - Access to a Fedora dist-git repository where Packit-triggered Koji builds run on pull requests.
- A failed build event – Log Detective only analyzes failures, not successful builds.
That’s it. Because the analysis is fully automatic, there is no additional setup or API key required. The integration works out of the box once Packit is configured for your repository.
Step-by-Step Instructions
1. Triggering a Build Failure
Log Detective’s analysis is triggered automatically when a Packit-triggered scratch Koji build fails on a dist-git pull request. To see it in action, simply create a pull request with code that causes a build error—for example, a syntax mistake in a spec file, a missing dependency, or a compilation error. Packit will launch the Koji build as usual, and if it fails, the Log Detective analysis request is fired off without any intervention from you.
2. Understanding the Analysis Request
When a build fails, the Packit service sends a request to the Log Detective interface server. This server is a lightweight, containerized component that acts as a bridge between Packit and the Log Detective AI agent. It receives all build artifacts—logs, metadata, and other files—and forwards them for processing. The request is asynchronous; the server does not wait for the analysis to finish but instead publishes the result on the Fedora Messaging bus once it’s ready.
Key point: You don’t need to manually send logs or worry about file sizes. Packit handles the aggregation and transmission.
3. How Log Detective Processes Logs
Starting with version 4.0, Log Detective uses an agent built on the BeeAI Framework. The agent receives the full set of build logs and artifacts. Rather than feeding the entire log to an AI model—which would be costly and slow—Log Detective first extracts meaningful snippets using a set of tools based on the Drain template mining algorithm.
Drain looks for repeated patterns and anomalies in log lines, compressing the information into a small set of significant snippets. These snippets represent only a fraction of the original log size, which reduces token usage and limits useless context in the AI model. This approach allows the system to use relatively small models while still achieving accurate results.
4. Retrieving Results
Once the analysis is complete, the interface server posts the result to the Fedora Messaging bus. Packit picks up the message and links the Log Detective analysis to the corresponding pull request in the Packit dashboard. You can view the analysis by navigating to the PR in the dashboard—look for a new section or link labeled "Log Detective" or "Build Analysis". There you’ll find:
- A statement of the likely root cause of the failure.
- Optionally, a suggested solution.
The analysis is derived solely from the build logs; it does not reference external sources or your project history.
5. Interpreting the Analysis Statement
Log Detective’s output is a short, plain-English explanation. For example: “Build failed due to a missing dependency: python3-foo is not installed” or “Compile error in source.c at line 42: undefined reference to 'bar'.” If a solution is provided, it might be something like “Add BuildRequires: python3-foo to the spec file.”
Remember that Log Detective uses a general-purpose AI model and has no access to your repository’s history or the Fedora package collection. Therefore, treat its suggestions as a starting point rather than definitive fixes. For experienced packagers, the analysis may seem basic, but for newcomers it can illuminate the cause of a failure quickly.
Common Mistakes
Expecting Analysis for Successful Builds
Log Detective only triggers on failed builds. If your build succeeds, you will not see any analysis output. There is no way to manually request analysis for a successful build.
Over-Reliance Without Context
Because Log Detective does not consult external databases or Fedora-specific knowledge, its suggestions may be incomplete or occasionally off-target. For instance, it might propose a fix that works in a generic Linux environment but violates Fedora packaging guidelines. Always verify suggestions against official documentation or your own experience.
Misunderstanding Limitations
The tool is designed to assist newcomers, not to replace years of Fedora packaging expertise. Do not expect it to diagnose complex multi-package dependencies or obscure configuration errors. If you have been building packages for a while, you may find the analysis trivial—that’s by design.
Missing the Dashboard Result
After a failure, check the Packit dashboard on the pull request page. The analysis may take a minute or two to appear. If it doesn’t show up, ensure your Packit integration is active and that the build was indeed triggered by Packit (not by another CI system).
Summary
Log Detective brings automatic, AI-powered build failure analysis to Packit. It’s fully automatic—no setup, no prompts, no log selection. For new contributors, it demystifies why a Koji build failed and points toward a fix. For veterans, it can be a quick sanity check. The integration is seamless: failures trigger requests, snippets are extracted using the Drain algorithm, and results appear in the dashboard within minutes. While not a replacement for deep system knowledge, Log Detective lowers the barrier for anyone diving into Fedora package maintenance.