PYTHON-5404 - Add docs for profiling execution

CONTRIBUTING.md

@@ -460,3 +460,17 @@ partially-converted asynchronous version of the same name to the `test/asynchron
 Use this generated file as a starting point for the completed conversion.
 
 The script is used like so: `python tools/convert_test_to_async.py [test_file.py]`
+
+## Generating a flame graph using py-spy
+To profile a test script and generate a flame graph, follow these steps:
+1. Install `py-spy` if you haven't already:
+   ```bash
+   pip install py-spy
+   ```
+2. Inside your test script, perform any required setup and then loop over the code you want to profile for improved sampling
+3. Run the `flamegraph` justfile target to generate a `.svg` file containing the flame graph:
+  ```bash
+  just flamegraph <output_name=profile> <sample_rate=2000> <path/to/script>
+  ```
+4. If you need to include native code (for example the C extensions), profiling should be done on a Linux system, as macOS and Windows do not support the `--native` option of `py-spy`.
+   Creating an ubuntu Evergreen spawn host and using `scp` to copy the flamegraph `.svg` file back to your local machine is the best way to do this.

justfile

@@ -68,6 +68,9 @@ setup-tests *args="":
 teardown-tests:
     bash .evergreen/scripts/teardown-tests.sh
 
+flamegraph *args:
+    bash tools/generate_flamegraph.sh {{args}}
+
 [group('server')]
 run-server *args="":
     bash .evergreen/scripts/run-server.sh {{args}}

tools/generate_flamegraph.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate a flamegraph of a given Python script.")
+
+    parser.add_argument(
+        "--output",
+        default="profile",
+        help="Output filename (default: 'profile')",
+    )
+    parser.add_argument(
+        "--sampling_rate",
+        default="2000",
+        help="Sampling rate in samples/sec (default: 2000)",
+    )
+    parser.add_argument(
+        "--native",
+        default=False,
+        action=argparse.BooleanOptionalAction,
+        help="Whether to profile native extensions (default: False)",
+    )
+    parser.add_argument(
+        "--script_path",
+        required=True,
+        help="Path to the Python script to be profiled (required)",
+    )
+
+    args = parser.parse_args()
+
+    bash_command = [
+        "py-spy",
+        "record",
+        "-o",
+        f"{args.output}.svg",
+        "-r",
+        f"{args.sampling_rate}",
+        "--",
+        "python",
+        f"{args.script_path}",
+    ]
+
+    if args.native:
+        # Insert --native option at the correct position
+        bash_command.insert(6, "--native")
+
+    try:
+        subprocess.run(bash_command, check=True)  # noqa: S603
+    except Exception:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()