Effortless Build Failure Analysis: A Guide to Using Log Detective with Packit
Introduction
If you work with Fedora packages and use Packit to integrate upstream projects with downstream distributions, you've likely encountered build failures that require sifting through long log files. Starting this month, Log Detective is now integrated with Packit to automatically analyze failed Koji scratch builds triggered by dist-git pull requests. The best part? You don't need to do anything extra—the analysis happens automatically when a build fails. This guide walks you through what you need, the workflow, and how to interpret the results.
What You Need
- An active Fedora Account System (FAS) account
- A dist-git repository configured with Packit (via
.packit.yamlor Fedora's central Packit configuration) - A pull request against the dist-git repository (or you can create one for testing)
- No additional setup for Log Detective—it works out of the box with existing Packit installations
Step-by-Step Guide
Step 1: Set Up Packit for Your Dist-Git Repository
Before Log Detective can help, Packit must be enabled for your dist-git repository. If you haven't done this yet, follow the Packit configuration docs to set up your .packit.yaml file. Ensure that Koji builds are enabled for pull requests—this is the trigger for Log Detective.
Step 2: Submit a Pull Request to Dist-Git
Create a pull request against your dist-git repository. This could be a change to a specfile, a patch, or any modification that triggers a build. Packit will automatically detect the PR and start a scratch Koji build.
Step 3: Wait for the Koji Build
After the PR is submitted, Packit initiates a scratch Koji build. You can monitor its progress in the Packit dashboard or via Fedora Messaging if you subscribe to notifications. If the build succeeds, no further action is needed. But if it fails, Log Detective steps in.
Step 4: Log Detective Automatic Analysis
When a build fails, Packit automatically sends a request to the Log Detective interface server—a lightweight containerized service. This server passes all build logs and artifacts to the Log Detective agent (based on the BeeAI Framework version 4.0). The agent uses the Drain template mining algorithm to extract meaningful snippets from the logs, discarding noise. These snippets are then fed to a general-purpose language model that produces a clear explanation of what went wrong and, optionally, a suggested fix. The result is posted back to the Fedora Messaging bus, where Packit collects it and links it to your PR.
Step 5: View the Analysis Result in Packit Dashboard
Open your pull request in the Packit dashboard (or in the dist-git PR page if Packit checks are displayed). You'll see a new entry from Log Detective. The analysis includes:
- What went wrong – a plain‑language statement of the failure cause (e.g., missing build dependency, syntax error, RPM macro issue)
- Solution suggestion – a recommendation for fixing the issue (if the model can determine one)
Note: The analysis is based only on build logs; it does not access external sources like Bugzilla or package history.
Step 6: Apply the Fix
Use the provided suggestion as a starting point. If you're new to packaging, the analysis can save hours of log reading. Experienced maintainers may use it to quickly confirm their own diagnosis. After making changes, update the PR to trigger a new build, and repeat the process until the build succeeds.
Tips for Getting the Most Out of Log Detective
- It's a tool, not a replacement for experience. Log Detective uses a general‑purpose model and limited context (only build logs). For obscure or complex failures, rely on your own expertise or consult the Fedora community.
- Ideal for newcomers. If you're unfamiliar with RPM packaging or Fedora build processes, the analysis provides a helpful starting point and teaches you common failure patterns.
- Check the Packit dashboard regularly. Results appear automatically; you don't need to request analysis manually (unlike Copr, where you click an “Ask AI” button).
- Future improvements are on the way. The Log Detective team plans to integrate additional data sources (e.g., specfile diffs, bug trackers) and refine the analysis model. Stay tuned for updates.
- No extra configuration needed. You don't need to select logs, craft prompts, or set up anything special—Log Detective handles everything automatically.
With Log Detective now part of Packit, failing Koji builds become less mysterious. Follow the steps above, and let the AI do the heavy lifting of log parsing.