Add unified pysa_dump_* debugging triggers for Pysa and Pyrefly

Summary: This adds a unified `pysa_dump_*` family of debugging/logging triggers for Pysa and Pyrefly. Each phase can be triggered two ways (OR'd together): an in-source `pysa_dump_<phase>()` function call, or a `PYSA_DUMP_<PHASE>=<exact qualified name>` environment variable. `pysa_dump()` / `PYSA_DUMP` is the master switch that enables all phases for a function. This avoids having to edit analyzed source code to insert dump calls, and avoids threading CLI flags through multiple programs. It also cleans up and unifies the previously inconsistent logging logic (e.g. `pysa_dump` worked in pyrefly but not pysa).

Reviewed By: tianhan0

Differential Revision: D108298619

fbshipit-source-id: 584002fb9c6be4bf79ab6f79888e1c8e83b804ac

Author: arthaud

documentation/website/docs/pysa_tips.md

@@ -121,18 +121,31 @@ of square brackets to access a dictionary.
 
 ## Debugging Tools
 
-### `pyre_dump()`
-
-You can insert a call to the (non-existent) `pyre_dump()` function in your code
-to enable verbose logging of the call graph, forward and backward analysis of
-the current function or method. This can be useful as a starting point to figure
-out why something is/isn't happening. This will produce _very_ verbose output.
-
-### `pyre_dump_call_graph`
-
-You can insert a call to `pyre_dump_call_graph` (no import needed) in a function
-or method to enable logging of the call graph building. This will produce
-verbose output.
+### `pysa_dump()`
+
+You can insert a call to the `pysa_dump()` function (no imported needed) in your code
+to enable verbose logging of every Pysa analysis phase (call graph, higher order
+call graph, forward and backward taint analysis) of the current function or
+method. This is the master switch and can be useful as a starting point to
+figure out why something is/isn't happening. This will produce _very_ verbose
+output.
+
+Every trigger below has two equivalent forms that are OR'd together: an
+in-source magic call (e.g. `pysa_dump_taint()`) that targets the function or
+method it appears in, and an environment variable (e.g. `PYSA_DUMP_TAINT`) whose
+value is matched _exactly_ against the fully-qualified name of the callable being
+analyzed (e.g. `my.module.MyClass.my_method`). The master `pysa_dump()` /
+`PYSA_DUMP` enables all of the phases below.
+
+| In-source call                            | Environment variable                      | Effect                                                     |
+| ----------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
+| `pysa_dump()`                             | `PYSA_DUMP`                               | Enables every phase below                                  |
+| `pysa_dump_call_graph()`                  | `PYSA_DUMP_CALL_GRAPH`                    | First-order call graph build logs                          |
+| `pysa_dump_higher_order_call_graph()`     | `PYSA_DUMP_HIGHER_ORDER_CALL_GRAPH`       | Higher order call graph build logs                         |
+| `pysa_dump_taint()`                       | `PYSA_DUMP_TAINT`                         | Taint forward/backward analysis and call graph dump        |
+| `pysa_dump_cfg()`                         | `PYSA_DUMP_CFG`                           | Dump the control flow graph at the start of taint analysis |
+| `pysa_dump_perf()`                        | `PYSA_DUMP_PERF`                          | Taint perf profiling (spawns `perf`, see below)            |
+| `pysa_dump_perf_higher_order_call_graph()` | `PYSA_DUMP_PERF_HIGHER_ORDER_CALL_GRAPH` | Higher order call graph perf profiling (in-memory only)    |
 
 ### `reveal_type(YOUR_VARIABLE)`
 
@@ -151,11 +164,17 @@ analyzes the function (which could be many times) it will update it's
 understanding of the taint flowing into the function and output the current
 state. The final output will be the most complete.
 
-### `pyre_dump_perf()`
+### `pysa_dump_perf()`
+
+You can insert a call to `pysa_dump_perf` (no import needed) in a function or
+method, or set the `PYSA_DUMP_PERF` environment variable to its fully-qualified
+name, to profile the taint analysis on that function or method and dump the
+results on stdout. This spawns a real `perf` process.
 
-You can insert a call to `pyre_dump_perf` (no import needed) in a function or
-method to profile the current analysis on that function or method, and dump the
-results on stdout.
+The related `pysa_dump_perf_higher_order_call_graph()` /
+`PYSA_DUMP_PERF_HIGHER_ORDER_CALL_GRAPH` profiles the higher order call graph
+build. Unlike `pysa_dump_perf`, this profiling is in-memory only and does not
+spawn a `perf` process.
 
 ### `results.json`
 

source/analysis/scope.ml

@@ -685,6 +685,13 @@ module Builtins = struct
     (* Builtins recognized by Pyre itself *)
     | "BoundMethod"
     | "pyre_dump"
+    | "pysa_dump"
+    | "pysa_dump_call_graph"
+    | "pysa_dump_higher_order_call_graph"
+    | "pysa_dump_perf_higher_order_call_graph"
+    | "pysa_dump_perf"
+    | "pysa_dump_taint"
+    | "pysa_dump_cfg"
     | "reveal_type"
     | "reveal_locals"
     (* Builtins recognized by Python *)

source/ast/statement.ml

@@ -652,13 +652,19 @@ and Define : sig
 
   val dump_locations : t -> bool
 
-  val dump_call_graph : t -> bool
+  val pysa_dump : t -> bool
 
-  val dump_higher_order_call_graph : t -> bool
+  val pysa_dump_call_graph : t -> bool
 
-  val dump_perf_higher_order_call_graph : t -> bool
+  val pysa_dump_higher_order_call_graph : t -> bool
 
-  val dump_perf : t -> bool
+  val pysa_dump_perf_higher_order_call_graph : t -> bool
+
+  val pysa_dump_perf : t -> bool
+
+  val pysa_dump_taint : t -> bool
+
+  val pysa_dump_cfg : t -> bool
 
   val show_json : t -> string
 
@@ -1085,15 +1091,23 @@ end = struct
 
   let dump_locations define = contains_call define "pyre_dump_locations"
 
-  let dump_call_graph define = contains_call define "pyre_dump_call_graph"
+  let pysa_dump define = contains_call define "pysa_dump"
+
+  let pysa_dump_call_graph define = contains_call define "pysa_dump_call_graph"
+
+  let pysa_dump_higher_order_call_graph define =
+    contains_call define "pysa_dump_higher_order_call_graph"
+
+
+  let pysa_dump_perf_higher_order_call_graph define =
+    contains_call define "pysa_dump_perf_higher_order_call_graph"
 
-  let dump_higher_order_call_graph define = contains_call define "pyre_dump_higher_order_call_graph"
 
-  let dump_perf_higher_order_call_graph define =
-    contains_call define "pyre_dump_perf_higher_order_call_graph"
+  let pysa_dump_perf define = contains_call define "pysa_dump_perf"
 
+  let pysa_dump_taint define = contains_call define "pysa_dump_taint"
 
-  let dump_perf define = contains_call define "pyre_dump_perf"
+  let pysa_dump_cfg define = contains_call define "pysa_dump_cfg"
 
   let show_json define = define |> to_yojson |> Yojson.Safe.pretty_to_string
 

source/ast/statement.mli

@@ -318,13 +318,19 @@ and Define : sig
 
   val dump_locations : t -> bool
 
-  val dump_call_graph : t -> bool
+  val pysa_dump : t -> bool
 
-  val dump_higher_order_call_graph : t -> bool
+  val pysa_dump_call_graph : t -> bool
 
-  val dump_perf_higher_order_call_graph : t -> bool
+  val pysa_dump_higher_order_call_graph : t -> bool
 
-  val dump_perf : t -> bool
+  val pysa_dump_perf_higher_order_call_graph : t -> bool
+
+  val pysa_dump_perf : t -> bool
+
+  val pysa_dump_taint : t -> bool
+
+  val pysa_dump_cfg : t -> bool
 
   val show_json : t -> string
 

source/interprocedural/callGraphBuilder.ml

@@ -4536,12 +4536,6 @@ module HigherOrderCallGraph = struct
   end
 end
 
-let debug_higher_order_call_graph define =
-  Ast.Statement.Define.dump define
-  || Ast.Statement.Define.dump_call_graph define
-  || Ast.Statement.Define.dump_higher_order_call_graph define
-
-
 let higher_order_call_graph_of_define
     ~define_call_graph
     ~pyre_api
@@ -4568,7 +4562,7 @@ let higher_order_call_graph_of_define
 
     let get_callee_model = get_callee_model
 
-    let debug = debug_higher_order_call_graph (Node.value define)
+    let debug = PysaDump.should_dump_higher_order_call_graph ~define:(Node.value define) ~callable
 
     let module_qualifier = qualifier
 
@@ -4693,9 +4687,7 @@ let call_graph_of_define
            Some { MissingFlowTypeAnalysis.caller = callable }
         else
           None);
-      debug =
-        Ast.Statement.Define.dump (Node.value define)
-        || Ast.Statement.Define.dump_call_graph (Node.value define);
+      debug = PysaDump.should_dump_call_graph ~define:(Node.value define) ~callable;
       override_graph;
       attribute_targets;
       skip_call_higher_order_functions;
@@ -5686,9 +5678,7 @@ let build_whole_program_call_graph_for_pyrefly
       | AstResult.Some
           ({ CallablesSharedMemory.DefineAndQualifier.define = { Node.value = define; _ }; _ } as
           define_and_qualifier) ->
-          let debug =
-            Ast.Statement.Define.dump define || Ast.Statement.Define.dump_call_graph define
-          in
+          let debug = PysaDump.should_dump_call_graph ~define ~callable in
           debug, Some define_and_qualifier
       | _ -> false, None
     in

source/interprocedural/callGraphBuilder.mli

@@ -132,8 +132,6 @@ end
 
 val default_scheduler_policy : Scheduler.Policy.t
 
-val debug_higher_order_call_graph : Ast.Statement.Define.t -> bool
-
 val higher_order_call_graph_of_define
   :  define_call_graph:CallGraph.DefineCallGraph.t ->
   pyre_api:PyrePysaApi.ReadOnly.t ->

source/interprocedural/callGraphFixpoint.ml

@@ -136,7 +136,11 @@ module CallGraphAnalysis = struct
              ~message:(Format.asprintf "Missing call graph for `%a`" Target.pp callable)
       in
       let profiler =
-        if Ast.Statement.Define.dump_perf_higher_order_call_graph (Ast.Node.value define) then
+        if
+          PysaDump.should_dump_perf_higher_order_call_graph
+            ~define:(Ast.Node.value define)
+            ~callable
+        then (* Higher order call graph perf profiling is kept in-memory only. *)
           CallGraphProfiler.start ~enable_perf:false ~callable ()
         else
           CallGraphProfiler.disabled
@@ -190,7 +194,7 @@ module CallGraphAnalysis = struct
                |> Option.value ~default:true
                |> not)
       in
-      if CallGraphBuilder.debug_higher_order_call_graph (Ast.Node.value define) then (
+      if PysaDump.should_dump_higher_order_call_graph ~define:(Ast.Node.value define) ~callable then (
         Log.dump
           "Returned callables for `%a`: `%a`"
           Target.pp_pretty_with_kind

source/interprocedural/interprocedural.ml

@@ -34,3 +34,4 @@ module IntraproceduralProfiler = IntraproceduralProfiler
 module CallGraphProfiler = CallGraphProfiler
 module TypeOfExpressionSharedMemory = TypeOfExpressionSharedMemory
 module ExpressionIdentifier = ExpressionIdentifier
+module PysaDump = PysaDump

source/interprocedural/pysaDump.ml

@@ -0,0 +1,85 @@
+(*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *)
+
+open Core
+
+let pysa_dump_env = lazy (Sys.getenv "PYSA_DUMP")
+
+let pysa_dump_call_graph_env = lazy (Sys.getenv "PYSA_DUMP_CALL_GRAPH")
+
+let pysa_dump_higher_order_call_graph_env = lazy (Sys.getenv "PYSA_DUMP_HIGHER_ORDER_CALL_GRAPH")
+
+let pysa_dump_taint_env = lazy (Sys.getenv "PYSA_DUMP_TAINT")
+
+let pysa_dump_cfg_env = lazy (Sys.getenv "PYSA_DUMP_CFG")
+
+let pysa_dump_perf_env = lazy (Sys.getenv "PYSA_DUMP_PERF")
+
+let perf_higher_order_call_graph_env = lazy (Sys.getenv "PYSA_DUMP_PERF_HIGHER_ORDER_CALL_GRAPH")
+
+(* A phase fires when the master switch is on (in-source `pysa_dump()` or `PYSA_DUMP` matching the
+   fully-qualified name), or when the phase-specific in-source call or environment variable
+   matches. *)
+let should_dump ~define ~callable ~in_source_phase ~phase_env =
+  let qualified_name = Ast.Reference.show (Target.define_name_exn callable) in
+  let matches_env env =
+    match Lazy.force env with
+    | Some value -> String.equal value qualified_name
+    | None -> false
+  in
+  Ast.Statement.Define.pysa_dump define
+  || in_source_phase define
+  || matches_env pysa_dump_env
+  || matches_env phase_env
+
+
+let should_dump_call_graph ~define ~callable =
+  should_dump
+    ~define
+    ~callable
+    ~in_source_phase:Ast.Statement.Define.pysa_dump_call_graph
+    ~phase_env:pysa_dump_call_graph_env
+
+
+let should_dump_higher_order_call_graph ~define ~callable =
+  should_dump
+    ~define
+    ~callable
+    ~in_source_phase:Ast.Statement.Define.pysa_dump_higher_order_call_graph
+    ~phase_env:pysa_dump_higher_order_call_graph_env
+
+
+let should_dump_taint ~define ~callable =
+  should_dump
+    ~define
+    ~callable
+    ~in_source_phase:Ast.Statement.Define.pysa_dump_taint
+    ~phase_env:pysa_dump_taint_env
+
+
+let should_dump_cfg ~define ~callable =
+  should_dump
+    ~define
+    ~callable
+    ~in_source_phase:Ast.Statement.Define.pysa_dump_cfg
+    ~phase_env:pysa_dump_cfg_env
+
+
+let should_dump_perf ~define ~callable =
+  should_dump
+    ~define
+    ~callable
+    ~in_source_phase:Ast.Statement.Define.pysa_dump_perf
+    ~phase_env:pysa_dump_perf_env
+
+
+let should_dump_perf_higher_order_call_graph ~define ~callable =
+  should_dump
+    ~define
+    ~callable
+    ~in_source_phase:Ast.Statement.Define.pysa_dump_perf_higher_order_call_graph
+    ~phase_env:perf_higher_order_call_graph_env

source/interprocedural/pysaDump.mli

@@ -0,0 +1,24 @@
+(*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *)
+
+(* Decides whether verbose "magic dump" logging is enabled for a given callable during a Pysa
+   analysis phase. *)
+
+val should_dump_call_graph : define:Ast.Statement.Define.t -> callable:Target.t -> bool
+
+val should_dump_higher_order_call_graph : define:Ast.Statement.Define.t -> callable:Target.t -> bool
+
+val should_dump_taint : define:Ast.Statement.Define.t -> callable:Target.t -> bool
+
+val should_dump_cfg : define:Ast.Statement.Define.t -> callable:Target.t -> bool
+
+val should_dump_perf : define:Ast.Statement.Define.t -> callable:Target.t -> bool
+
+val should_dump_perf_higher_order_call_graph
+  :  define:Ast.Statement.Define.t ->
+  callable:Target.t ->
+  bool