Improve debug logging in Cabal/cabal-install
- Dominant language
- Haskell
- Stars
- 1.7k
- Forks
- 750
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 28
Description
I spent some time with debug logging in other console applications and it gave me some thoughts about how I would go about improving debug logging in Cabal/cabal-install. One big thing about working in this space is that it is very feasible for someone new to the project to make a big difference here (this is compared to adding new features to the Cabal file format, which require much more rigor--easy to YOLO debug loggin changes!) Some thoughts here:
**Design intentional output formats for internal data structures.** In #6835 @danidiaz spent a lot of time going through the internal representations to look for where things "went wrong", and had to make modifications to get out the information they needed (e.g., https://github.com/haskell/cabal/issues/6835#issuecomment-850966939). This shouldn't be necessary. We should aim for:
* **Completeness.** At a high enough debug level, it should be possible to view ALL information from the data structures, including all intermediate stages of the elaboration process. In many cases, no outputting mechanism exists for this, and you have to manually add print information. Making matters worse is when data structures have no way of printing themselves in complete form.
* **Selectivity.** But complete logs can be a punishingly large amount of information, so there should be clear mechanisms for *selectively* saying what you want the to turn the hose for, and omit everything you don't want. Cabal's integer verbosity levels do a poor job at this; for example, `-v3` triggers verbose GHC output, which is rarely what you want if you're only debugging Cabal.
* **Relevance.** Orthogonal to completeness is giving relevant information. The default higher log levels should be designed to give you information that is likely to help you solve whatever Cabal problem you are looking at. For example, currently InstallPlan printing prints out information about all packages, both those from Hackage and those that are inplace. But you're likely to only care about the inplace packages (as those are the ones that are likely to have caused the bugs); a lower verbosity install plan view should tell you only about inplace packages. Similarly, you may not want to print out every field of an elaborated plan package; maybe only some of the fields are relevant most of the time; there should be another output format which is abridged. What to keep and what to toss out is a difficult question, and should be driven by actual bugfixes in Cabal (what would have been helpful to see to solve a bug?)
**Make the log output more indexable.** In many cases, debug output dumps out some data structure without any information about what the output is about. This makes it difficult to grep logs to find the debug output associated with. It should be easy to tell what code in Cabal produced any given log line. (This is made more difficult by the fact that a lot of output in the logs are multi-lined).
**Add a rage mechanism.** If you don't know what rage is, read my blog post http://blog.ezyang.com/2021/04/rage-bug-reporting/ When people submit bug reports, if we can make it as easy as possible for them to report verbose debug logs, even if they hadn't initially run the command with `-v`.
Contributor guide
Research direction
The issue names no files, tests, or entry points; start by reviewing the debugging work discussed in #6835 and the proposed rage mechanism. Define a focused plan for complete, selective, relevant, and indexable Cabal/cabal-install logs. Done should include an agreed implementation scope covering debug output and easy verbose bug reports.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- haskell
- Domain
- build-system, cli, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100