Developer Guide: Generating the Service Call Graph

This document describes the robust, thread-safe method for generating a visual Call Graph of the long-running aura_engine.py. We use the yappi profiler (for multi-threading support) and gprof2dot for visualization.

Prerequisites

Ensure you have the necessary tools installed globally or in your virtual environment:

# Required Python libraries for profiling
pip install yappi gprof2dot

# Required system library for visualization
# Linux: sudo apt install graphviz

Step 1: Modifying the Service for Profiling

The aura_engine.py script must be modified to manually start the yappi profiler and gracefully save the profiling data upon interruption (Ctrl+C).

Key Changes in aura_engine.py:

  1. Imports and Signal Handler: Import yappi and define the generate_graph_on_interrupt function (as implemented previously) to call yappi.stop() and stats.save(...).

  2. Start/Stop: Add yappi.start() and signal.signal(signal.SIGINT, ...) within the if __name__ == "__main__": block to wrap the execution of main(...).

Step 2: Running the Service and Collecting Data

Run the modified script directly and allow it to process data for a sufficient time (e.g., 10-20 seconds) to ensure all core functions, including threaded ones (like LanguageTool correction), are called.

# Execute the service directly (do NOT use the pycallgraph wrapper)
python3 aura_engine.py

Press Ctrl+C once to trigger the signal handler. This will stop the profiler and save the raw data to:

\mathbf{yappi\_profile\_data.prof

Step 3: Generating and Filtering the Visual Graph

We use gprof2dot to convert the raw pstats data into the SVG format. Since advanced filtering options like --include and --threshold may not be supported by our specific environment, we use the basic --strip filter to clean up path information and reduce clutter from system internals.

Execute the visualization command:

python3 -m gprof2dot -f pstats yappi_profile_data.prof --strip | dot -Tsvg -o yappi_call_graph_stripped.svg

Step 4: Documentation (Manual Crop)

The resulting yappi_call_graph_stripped.svg (or .png) file will be large, but it accurately contains the full execution flow, including all threads.

For documentation purposes, manually crop the image to focus on the central logic (the 10-20 core nodes and their connections) to create a focused and readable Call Graph for the repository documentation.

Archiving

The modified configuration file and the final Call Graph visualization should be archived in the documentation source directory:

Artifact

Location

Modified Service File

doc_sources/profiling/aura_engine_profiling_base.py

Final Cropped Image

doc_sources/profiling/core_logic_call_graph.svg

Raw Profiling Data

(Optional: Should be excluded from final repository documentation)

yappi_call_graph