What You Need
- A Packit service configured for your dist-git repository (see the Setup Guide).
- A pull request that triggers a Packit scratch Koji build.
- A failed build (Log Detective only analyzes failures).
- Access to the Packit Dashboard (no additional account required).
- Internet connection to view results.
Step-by-Step Guide
Step 1: Configure Packit for Your Repository
If you haven’t already, set up Packit to automatically trigger scratch Koji builds on pull requests. This is done by adding a .packit.yaml configuration file to your repository. For detailed instructions, refer to the official Packit documentation. No additional setup is required for Log Detective—it works out of the box once Packit is configured.
Step 2: Create a Pull Request with a Build Trigger
Open a new pull request against your dist-git repository. Ensure that your pull request includes changes that will initiate a Koji scratch build. Typical triggers include modifying spec files, patches, or source archives. Packit will automatically queue a build.
Step 3: Wait for the Build to Complete (and Hopefully Fail)
Allow the Koji build process to run. Log Detective specifically analyzes failed builds. If the build succeeds, no analysis is generated. To test the feature, you may intentionally introduce a common error—such as a missing dependency or incorrect macro—to simulate a failure.
Step 4: Let Log Detective Work Automatically
Once a build fails, Packit automatically sends a request to the Log Detective interface server. You do not need to click any buttons or select log files. The service:
- Receives all build logs and artifacts.
- Uses the Drain template mining algorithm to extract meaningful snippets.
- Analyzes these snippets with a BeeAI agent (version 4.0+).
- Posts the results to the Fedora Messaging bus, where Packit collects them.
This entire process is invisible to you. Typically, analysis completes within a few seconds to a minute, depending on log size.
Step 5: View the Analysis on the Packit Dashboard
Navigate to the Packit Dashboard and locate the pull request you created. Log Detective results are linked directly to the PR. Look for a section labeled “Log Detective Analysis” or similar. The dashboard displays:
- A statement of what went wrong during the build.
- An optional suggestion for a fix.
Note that the analysis uses only build logs—no external sources—so it stays focused on the error.
Step 6: Interpret the Results
Read the analysis carefully. It may highlight a specific error message, such as a missing file, a syntax error, or a failed dependency. The suggestion might be something like “install package foo-devel” or “fix the URL in Source0.” Remember that Log Detective uses a general-purpose language model, so it is not infallible. Treat it as a starting point, not a definitive answer.
Step 7: Apply the Fix (If Suggested)
If the analysis includes a solution, test it by updating your pull request. Commit the necessary changes and push to the branch. Packit will automatically trigger a new build, and Log Detective will analyze the new failure if it still occurs.
Step 8: Provide Feedback (Optional)
Log Detective is continuously evolving. If you find an analysis particularly helpful or unhelpful, consider reporting it to the Packit team. Future improvements may include integration with additional data sources and better models.
Tips for Getting the Most Out of Log Detective
- Understand its purpose: Log Detective is designed for newcomers to Fedora package maintenance. Experienced packagers may find it less valuable. Use it as a learning tool to understand common build patterns.
- Combine with manual debugging: If the suggestion seems off, trust your own experience or consult logs directly. Log Detective is a helper, not a replacement for expertise.
- Try the Copr equivalent: In Copr builds, you can manually request analysis by clicking the “Ask AI” button. This is useful if you want to analyze a successful build or a different failure scenario.
- Check for updates: Log Detective’s capabilities will expand over time. Keep an eye on the Packit blog for announcements about new features.
- Remember the limitations: The tool lacks access to external information (e.g., bug trackers, documentation). It cannot replace years of Fedora-specific experience, but it can accelerate learning.
By following these steps, you can automatically leverage AI to diagnose failed builds in your Packit workflow—no extra configuration required. Happy building!