Understanding Log Detective in Packit: A Comprehensive Guide

Overview

Log Detective has recently been integrated into Packit, the service that bridges upstream projects with downstream distributions like Fedora. This guide explains how Log Detective automatically analyzes failed Koji builds triggered by Packit on dist-git pull requests, helping developers understand build failures without manual log inspection.

Understanding Log Detective in Packit: A Comprehensive Guide — Source: fedoramagazine.org

Starting this month, whenever a scratch Koji build initiated by Packit fails, a Log Detective analysis is automatically requested. The service parses build logs, extracts relevant snippets using the Drain template mining algorithm, and provides a summary of the issue along with possible solutions. Best of all, no configuration is needed—the analysis happens behind the scenes and results appear in the Packit dashboard.

Prerequisites

Before you can benefit from Log Detective in Packit, ensure you have the following:

A project hosted on a dist-git repository (e.g., src.fedoraproject.org) that uses Packit for integration.
Packit service enabled for your repository (instructions available at packit.dev).
Koji builds configured to run as part of your Packit workflow (e.g., on pull requests).
No additional setup is required for Log Detective—it works automatically with any Packit-triggered Koji build failure.

Note: Log Detective only analyzes failed builds; successful builds are not processed.

Step-by-Step Instructions

1. Configure Packit for Your Dist-Git Repository

If you haven't already, set up Packit to handle Koji builds on pull requests. Create a .packit.yaml file in your repository with the following minimal configuration:

# .packit.yaml
specfile: my-package.spec
files_to_sync:
  - my-package.spec
github_actions:
  pull_request:
    jobs:
      - job: copr_build
        trigger: pull_request
        targets: [fedora-rawhide-x86_64]

  # Add a Koji build job
  - job: koji_build
    trigger: pull_request
    targets: [fedora-rawhide-x86_64]

This configuration triggers a scratch Koji build every time a pull request is created or updated. Refer to Packit configuration docs for details.

2. Submit a Pull Request to Trigger a Build

Make changes to your package (e.g., patch a spec file) and open a pull request against your dist-git repository. Packit will automatically start a Koji build. You can monitor the build status in the Packit dashboard.

3. Wait for Build Failure (if Any)

If the Koji build fails, Packit will send a request to the Log Detective interface server. The analysis process begins immediately:

Log Detective receives all build logs and artifacts.
It uses the Drain algorithm (and other tools) to extract tiny, meaningful snippets from the logs—typically less than 1% of the original log size.
These snippets are then fed to a language model for analysis.
The model outputs a statement describing what went wrong and optionally suggests a fix.

Note: The analysis is performed asynchronously. Results may take a few minutes to appear.

4. View the Analysis Results

Once ready, Log Detective posts the analysis via the Fedora Messaging bus, and Packit picks it up. The result appears as a link on the pull request page in the Packit dashboard. Click the link to see:

Statement of the issue: e.g., "Build failed because dependency 'foo-devel' is missing."
Suggested solution: e.g., "Add 'BuildRequires: foo-devel' to your spec file."

Currently, Log Detective only uses the build logs themselves—it does not consult external sources like Bugzilla or the spec file’s history.

Common Mistakes

Mistake: Expecting Analysis for Successful Builds

Log Detective is triggered only on failed Koji builds. If your build succeeds, no analysis will appear. This is intentional to avoid unnecessary token usage and focus on problem areas.

Mistake: Not Having Packit Properly Configured

If you haven't set up Koji build jobs in your .packit.yaml, no builds will be triggered on pull requests, and therefore no analysis will ever occur. Double-check your configuration and ensure the build actually runs.

Mistake: Assuming Log Detective Can Replace Expert Knowledge

Log Detective uses a general-purpose language model and has limited context. It cannot replicate years of Fedora packaging experience. For complex issues (e.g., architecture-specific failures, intricate build macros), the analysis may be incomplete or misleading. Use it as a starting point, not a final authority.

Mistake: Expecting Immediate Results

The analysis process takes time—log parsing, snippet extraction, and model inference all add latency. If you don't see results within a few minutes, check the dashboard again later. Also note that the analysis is performed once per failure; subsequent updates to the same PR may trigger a new analysis.

Summary

Log Detective brings AI-powered log analysis to Packit, simplifying the debugging of failed Koji builds for newcomers and experienced packagers alike. By automatically extracting relevant snippets from build logs and using a language model to interpret them, it provides concise explanations and solutions without any manual effort. The integration requires no additional setup—just enable Packit with Koji builds on your dist-git pull requests. While it is not a substitute for deep Fedora packaging experience, it lowers the barrier for those less familiar with the ecosystem. As development continues, expect improvements in accuracy, speed, and possibly integration with additional data sources.

Tags: