Debugging the action graph is really hard

[lf-]

There's several questions I want to ask about the action graph that are currently really hard to answer.

Why does $build work and $build' not work? or miss cache?

Often I am making some change and I want to know what it did to the build graph. Something like nix-diff would be helpful. I think that target determinator does something like this, kind of, but it's not really the same at all.

A major use case for this is "why did this build not hit cache?": I want to be able to get the action digest before and after for each action in the build of some target and diff those trees, ideally aligned with the buck2 level graphs. It is acceptable that this is a file export from each one that is then passed to another command.

What args did the compiler get?

aquery doesn't necessarily materialize arg files, so you have to, I guess, use buck log what-ran, except if it hit cache and didn't actually run.

It's hard to directly ask for the args of the exact action you want, which is partially because actions aren't nameable. It's also not really possible to request that said action be built in isolation with a single command line that I know of.

What Starlark or build command produced this aberrant output?

A problem I have pretty often is that I have some path like so: buck-out/v2/gen/root/200212f73efcd57d/__app_settings__/haskell_stubs_shared.argsfile, and I would like to know without extensive source code inspection where it came from in Starlark or at least what action args produced it.

I would also like to know what its dependencies are. An example type of problem necessitating this was that our haskell_link actions had a bug in them where they were missing some cmd_args dependencies, and we had to stare at the Starlark code in question to figure out where it came from and what deps were listed there.

Imaginary syntax:

$ buck aquery buck-out/v2/gen/root/200212f73efcd57d/__app_settings__/haskell_stubs_shared.argsfile

What deps did my action have recorded for it?

It's very easy to e.g. hit #1151 or similar and not be able to debug it easily. There is theroretically a way of exporting a graphviz graph, but it's not interactive (and seems to be mutually exclusive with showing the action details with -A), so it's not especially helpful IMO.

Even the verbose -A output doesn't mention the dependencies of each action in the list, so even if I did do a lot of ctrl-F, the info is just not there. I also can't look up more details after looking at the graph visually somehow, because actions aren't nameable.

There is --output-format html but there is some unclear-to-me Meta reason that's not released: #973.

The problem that I think exists here is that actions aren't nameable (not entirely true! their output paths are named! but you can't look anything up by output path), so it's not possible to first find the problem action and then examine it more closely. If this were Nix, I would be able to very easily do this:

$ nix path-info -r nixpkgs#curl
/nix/store/03h6z5vq721fxwk991qb4g63d4vp1pfj-nghttp2-1.67.1-lib
[...]
/nix/store/d9is3dlvm6bv8qhzfypk1yvhp9k9v3yq-libidn2-2.3.8
/nix/store/ibr3m7g0lzbhvm2ly0y7v7hcgbshlpph-publicsuffix-list-0-unstable-2025-12-28
[...]
/nix/store/qncd2qavd8nj797izhqzyzz5q9cr5bwx-curl-8.17.0-bin

$ nix derivation show /nix/store/d9is3dlvm6bv8qhzfypk1yvhp9k9v3yq-libidn2-2.3.8
{
  "/nix/store/8j0jazq1ia338gnc18gy32yzsl9akaix-libidn2-2.3.8.drv": {
    "args": [
      "-e",
      "/nix/store/l622p70vy8k5sh7y5wizi5f2mic6ynpg-source-stdenv.sh",
      "/nix/store/shkw4qm9qcw5sc5n1k5jznc83ny02r39-default-builder.sh"
    ],
    "builder": "/nix/store/vlfjhc9730i65q1xhzf51kzh58s9kxnp-bash-5.3p9/bin/bash",
    "env": {
      "NIX_MAIN_PROGRAM": "idn2",
      "__darwinAllowLocalNetworking": "",
      "__impureHostDeps": "/bin/sh /usr/lib/libSystem.B.dylib /usr/lib/system/libunc.dylib /dev/zero /dev/random /dev/urandom /bin/sh",
      "__propagatedImpureHostDeps": "",
      "__propagatedSandboxProfile": "",
      "__sandboxProfile": "",
      "__structuredAttrs": "",
      "bin": "/nix/store/cr86mrwhqhj4lb4mgjs4zky5hd9d0drw-libidn2-2.3.8-bin",
.....

In fact, a buried lede in this Nix example is that I also looked the Nix actions (derivations) up by output path!

For example, this doesn't work:

$ buck aquery 'deps(root//local-packages/mercury-icalendar:spec.binary, 0)'
(target: `root//local-packages/mercury-icalendar:spec.binary (prelude//platforms:default#200212f73efcd57d)_2`, id: `2`)
root//local-packages/mercury-icalendar:spec.binary (prelude//platforms:default#200212f73efcd57d)

$ buck aquery '(target: `root//local-packages/mercury-icalendar:spec.binary (prelude//platforms:default#200212f73efcd57d)_2`, id: `2
`)'                     
0: at line 1:
(target: `root//local-packages/mercury-icalendar:spec.binary (prelude//platforms:default#200212f73efcd57d)_2`, id: `2`)
         ^
expected ')', found `

1: at line 1, in expression:
(target: `root//local-packages/mercury-icalendar:spec.binary (prelude//platforms:default#200212f73efcd57d)_2`, id: `2`)
^

Build ID: b1246145-c29e-432a-b5d8-a1d6ae3eb826
Command: aquery.                                                                                                                           
Time elapsed: 0.0s

Solutions

Make actions nameable

A whole bunch of interactivity problems are caused by added information in the action graph being all-or-nothing since you can't directly ask about the thing you're interested in. One fix to this is probably to be able to reference a specific action at a specific configuration hash via the CLI.

This would allow buck2 build of actions.

Allow exporting the RE representation of actions

I would like to be able to see what would be sent to a RE server for a given action, which would include the args and dependencies.
This is basically nix derivation show for buck2.

From this, one could build a buck-diff using similar techniques to nix-diff (which will directly tell you your target rebuilt because an environment variable of such and such dependency changed).

Allow reverse lookup of action info from output paths, if present in DICE

This makes it much easier to go from "aberrant output" to an action- or Starlark-level understanding. I don't actually mind if this involves re-querying a lot of stuff; the appropriate target and configuration is in the file path.

Release the HTML viewer

I don't mind doing some build engineering to convince it to work, but I need the code. #973.

Show dependencies in aquery -A output somewhere

This would immediately make wrong-deps problems much easier to debug as they don't require separately generating a graph to reference manually and search inconsistent-format identifiers in.

Show RE action hash in aquery -A output somewhere

This would allow inspecting the troublesome actions with either buck2 or external tools like buildbuddy CLI.