Python: CG trace: Updated README

Author: RasmusWL

python/tools/recorded-call-graph-metrics/README.md

@@ -4,18 +4,28 @@ also known as _call graph tracing_.
 
 Execute a python program and for each call being made, record the call and callee. This allows us to compare call graph resolution from static analysis with actual data -- that is, can we statically determine the target of each actual call correctly.
 
-## How do I give it a spin?
+Using the call graph tracer does incur heave toll on the performance. Expect 10x longer to execute program.
 
-After following setup instructions below, you should be able to reproduce the example trace by running
+Number of calls recorded vary a little from run to run. I have not been able to pinpoint why.
 
-```
-cg-trace --xml example/simple.xml example/simple.py
+## Running against real projects
+
+Currently it's possible to gather metrics from traced runs against two projects (defined in [projects.json](./projects.json)): `youtube-dl` and `wcwidth`.
+
+To run against all projects, use
+
+```bash
+$ ./helper.sh all $(./helper.sh projects)
 ```
 
-You can also run traces for all tests and build a database by running `tests/create-test-db.sh`. Then run the queries inside the `ql/` directory.
+To view the results, use
+```
+$ head -n 100 projects/*/Metrics.txt
+```
 
+## Local development
 
-## Setup
+### Setup
 
 1. Ensure you have at least Python 3.7
 
@@ -47,9 +57,22 @@ You can also run traces for all tests and build a database by running `tests/cre
 
 6. Enjoy writing code, and being able to run `cg-trace` on your command line :tada:
 
+### Using it
+
+After following setup instructions above, you should be able to reproduce the example trace by running
+
+```
+cg-trace --xml example/simple.xml example/simple.py
+```
+
+You can also run traces for all tests and build a database by running `tests/create-test-db.sh`. Then run the queries inside the `ql/` directory.
 
 ## Tracing Limitations
 
+### Multi-threading
+
+Should be possible by using [`threading.setprofile`](https://docs.python.org/3.8/library/threading.html#threading.setprofile), but that hasn't been done yet.
+
 ### Code that uses `sys.setprofile`
 
 Since that is our mechanism for recording calls, any code that uses `sys.setprofile` will not work together with the call-graph tracer.