دليل المطور: إنشاء الرسم البياني لاستدعاء الخدمة

يصف هذا المستند الطريقة القوية والآمنة لإنشاء رسم بياني للاتصال المرئي لـ “aura_engine.py” الذي يعمل لفترة طويلة. نستخدم ملف التعريف yappi (لدعم الخيوط المتعددة) وgprof2dot للتصور.

                                  ### المتطلبات الأساسية

تأكد من تثبيت الأدوات اللازمة عالميًا أو في بيئتك الافتراضية:

# Required Python libraries for profiling
pip install yappi gprof2dot

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

### الخطوة 1: تعديل الخدمة الخاصة بالتوصيف

يجب تعديل البرنامج النصي aura_engine.py لبدء تشغيل ملف تعريف yappi يدويًا وحفظ بيانات ملفات التعريف بأمان عند المقاطعة (Ctrl+C).

           **التغييرات الرئيسية في `aura_engine.py`:**

  1. ** معالج الواردات والإشارة: ** قم باستيراد yappi وحدد وظيفة generate_graph_on_interrupt (كما تم تنفيذها سابقًا) لاستدعاء yappi.stop() وstats.save(...).

  2. Start/Stop: أضف yappi.start() وsignal.signal(signal.SIGINT, ...) داخل الكتلة if __name__ == "__main__": لتغليف تنفيذ main(...).

الخطوة الثانية: تشغيل الخدمة وجمع البيانات

قم بتشغيل البرنامج النصي المعدل مباشرة واسمح له بمعالجة البيانات لفترة كافية (على سبيل المثال، 10-20 ثانية) لضمان استدعاء جميع الوظائف الأساسية، بما في ذلك الوظائف المترابطة (مثل تصحيح LanguageTool).

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

اضغط على Ctrl+C مرة واحدة لتشغيل معالج الإشارة. سيؤدي هذا إلى إيقاف ملف التعريف وحفظ البيانات الأولية في:

                                      `\mathbf{yappi\_profile\_data.prof`

الخطوة 3: إنشاء الرسم البياني المرئي وتصفيته

نستخدم “gprof2dot” لتحويل بيانات “pstats” الأولية إلى تنسيق SVG. نظرًا لأن خيارات التصفية المتقدمة مثل --include و--threshold قد لا تكون مدعومة من قبل بيئتنا المحددة، فإننا نستخدم مرشح --strip الأساسي لتنظيف معلومات المسار وتقليل الفوضى من الأجزاء الداخلية للنظام.

                                      **تنفيذ أمر التصور:**

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

                       ### الخطوة 4: التوثيق (قص يدوي)

سيكون الملف الناتج yappi_call_graph_stripped.svg (أو .png) كبيرًا، ولكنه يحتوي بدقة على تدفق التنفيذ الكامل، بما في ذلك جميع سلاسل الرسائل.

لأغراض التوثيق، قم بقص الصورة يدويًا للتركيز على المنطق المركزي (العقد الأساسية 10-20 واتصالاتها) لإنشاء رسم بياني مركز وقابل للقراءة لوثائق المستودع.

                                                       ### الأرشفة

يجب أرشفة ملف التكوين المعدل والتصور النهائي لـ Call Graph في دليل مصدر الوثائق:

                                   | قطعة أثرية | الموقع |
                                                          | :--- | :--- |

| ملف الخدمة المعدل | doc_sources/profiling/aura_engine_profiling_base.py | | الصورة النهائية التي تم اقتصاصها | doc_sources/profiling/core_logic_call_graph.svg | | بيانات ملفات التعريف الأولية | (اختياري: يجب استبعاده من وثائق المستودع النهائية) |

                                                                ![yappi_call_graph](../yappi_call_graph_stripped.svg_20251024_010459.png "yappi_call_graph_stripped.svg_20251024_010459.png")