Automated Build Failure Diagnosis: A Step-by-Step Guide Using Log Detective with Packit

Introduction

Starting this month, Log Detective enhances Packit by automatically analyzing failed scratch Koji builds triggered on dist-git pull requests. This integration simplifies troubleshooting for newcomers to Fedora package maintenance. Instead of manually sifting through build logs, you get a clear statement of what went wrong and a suggested fix. The analysis requires no additional setup—just let Packit and Log Detective work together. This guide walks you through the process step by step, from triggering a build to interpreting the AI-generated insights.

What You Need

• A Packit-enabled upstream project integrated with Fedora downstream distributions.
• A dist-git pull request that triggers a Packit scratch Koji build.
• Access to the Packit dashboard (the analysis results appear there).
• No additional software or configuration—the integration works automatically once Packit is set up.

Step-by-Step Process

1. Step 1: Submit a dist-git pull request

   Create or update a pull request in your project’s dist-git repository. This triggers a Packit workflow, which automatically starts a scratch Koji build to test your changes. No manual action is required beyond the PR itself.

2. Step 2: Let the build fail

   Wait for the Koji build to complete. If the build fails, Packit detects the failure. Only failed builds trigger Log Detective analysis. Successful builds proceed without any AI intervention.

3. Step 3: Packit sends a request to Log Detective

   Upon detecting the failure, Packit automatically forwards the build logs and related artifacts to the Log Detective interface server—a lightweight containerized service. This happens behind the scenes; you don’t need to select logs or tune any prompts.

4. Step 4: Log Detective processes the logs

   Log Detective, built on the BeeAI Framework (version 4.0), receives the full log set. It uses the Drain template mining algorithm to extract meaningful snippets—small fractions of the original log size. This token-saving approach allows even relatively small AI models to deliver accurate results quickly.

5. Step 5: Results are posted to Fedora Messaging

   Once the analysis is complete, the interface server publishes the findings to the Fedora Messaging bus. Packit, which subscribes to this bus, collects the results automatically. The entire communication is handled asynchronously, so you don’t have to wait idly.

   

6. Step 6: View the analysis on the Packit dashboard

   Navigate to the Packit dashboard. You’ll find a new entry linked to your PR. The analysis includes a concise explanation of what went wrong during the build, and optionally, a suggested solution. Currently, Log Detective relies solely on the build logs—it does not consult other sources.

7. Step 7: Interpret the analysis

   Read the AI-generated statement. It might highlight missing dependencies, syntax errors, or configuration issues. The suggested fix, when provided, offers a starting point for your investigation. Remember that Log Detective uses a general-purpose model, so its advice should be verified against your experience.

Tips for Maximum Benefit

• Understand the limitations: Log Detective is not a substitute for deep Fedora packaging expertise. It’s designed to assist those with less experience or as a first-pass triage tool. Seasoned maintainers may find the insights basic.
• Combine with manual review: Always cross-check the AI’s conclusions with your own knowledge. The diagnosis is based only on logs and may miss context from the broader ecosystem.
• Watch for future updates: The Log Detective team plans to expand capabilities—for example, integrating additional data sources and refining the analysis model. Keep an eye on announcements for new features.
• No setup needed: Because the integration is fully automatic, you can start using it immediately. Just ensure Packit is configured correctly for your project, and build failures will trigger analysis without extra effort.

By following these steps, you can leverage Log Detective to diagnose build failures faster, making your contribution workflow smoother whether you’re a Fedora newcomer or a veteran looking for a quick sanity check.