memray
v1.15.0
Memray هو ملف تعريف الذاكرة لـ Python. يمكنه تتبع عمليات تخصيص الذاكرة في كود Python، وفي وحدات الامتداد الأصلية، وفي مترجم Python نفسه. يمكنه إنشاء عدة أنواع مختلفة من التقارير لمساعدتك في تحليل بيانات استخدام الذاكرة الملتقطة. على الرغم من استخدامه بشكل شائع كأداة واجهة سطر الأوامر (CLI)، إلا أنه يمكن استخدامه أيضًا كمكتبة لأداء المزيد من مهام ملفات التعريف الدقيقة.
الميزات البارزة:
يمكن لـ Memray المساعدة في حل المشكلات التالية:
ملاحظة: يعمل Memray فقط على نظامي Linux وMacOS، ولا يمكن تثبيته على أنظمة أساسية أخرى.
نحن نبحث باستمرار عن التعليقات من مجتمعنا الرائع ❤️. إذا كنت قد استخدمت Memray لحل مشكلة ما، أو إنشاء ملف تعريف لتطبيق، أو العثور على تسرب للذاكرة أو أي شيء آخر، فيرجى إخبارنا بذلك! نود أن نسمع عن تجربتك وكيف ساعدتك Memray.
من فضلك، فكر في كتابة قصتك في صفحة مناقشة قصص النجاح.
انها حقا تحدث فرقا!
يتطلب Memray إصدار Python 3.7+ ويمكن تثبيته بسهولة باستخدام أدوات تعبئة Python الأكثر شيوعًا. نوصي بتثبيت أحدث إصدار ثابت من PyPI باستخدام النقطة:
python3 -m pip install memrayلاحظ أن Memray يحتوي على امتداد C لذلك يتم توزيع الإصدارات كعجلات ثنائية بالإضافة إلى الكود المصدري. إذا لم تكن العجلة الثنائية متاحة لنظامك (Linux x86/x64 أو macOS)، فستحتاج إلى التأكد من استيفاء جميع التبعيات على النظام الذي تجري فيه التثبيت.
إذا كنت ترغب في إنشاء Memray من المصدر، فأنت بحاجة إلى التبعيات الثنائية التالية في نظامك:
تحقق من مدير الحزم الخاص بك لمعرفة كيفية تثبيت هذه التبعيات (على سبيل المثال apt-get install build-essential python3-dev libdebuginfod-dev libunwind-dev liblz4-dev في الأنظمة المستندة إلى Debian أو brew install lz4 في MacOS). لاحظ أنك قد تحتاج إلى تعليم المترجم مكان العثور على ملفات الرأس والمكتبة الخاصة بالتبعيات. على سبيل المثال، في نظام التشغيل MacOS مع brew ، قد تحتاج إلى تشغيل:
export CFLAGS= " -I $( brew --prefix lz4 ) /include " LDFLAGS= " -L $( brew --prefix lz4 ) /lib -Wl,-rpath, $( brew --prefix lz4 ) /lib " قبل تثبيت memray . تحقق من وثائق مدير الحزم لديك لمعرفة موقع ملفات الرأس والمكتبة للحصول على معلومات أكثر تفصيلاً.
إذا كنت تقوم بالإنشاء على نظام MacOS، فستحتاج أيضًا إلى تعيين هدف النشر.
export MACOSX_DEPLOYMENT_TARGET=10.14بمجرد تثبيت التبعيات الثنائية، يمكنك استنساخ المستودع ومتابعة عملية البناء العادية:
git clone [email protected]:bloomberg/memray.git memray
cd memray
python3 -m venv ../memray-env/ # just an example, put this wherever you want
source ../memray-env/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e . -r requirements-test.txt -r requirements-extra.txt سيؤدي هذا إلى تثبيت Memray في البيئة الافتراضية في وضع التطوير (الأمر -e الخاص pip install الأخيرة).
إذا كنت تخطط للمساهمة مرة أخرى، فيجب عليك تثبيت خطافات الالتزام المسبق:
pre-commit installسيضمن ذلك اجتياز مساهمتك لفحوصات الفحص الخاصة بنا.
يمكنك العثور على أحدث الوثائق المتاحة هنا.
هناك طرق عديدة لاستخدام Memray. أسهل طريقة هي استخدامه كأداة سطر أوامر لتشغيل البرنامج النصي أو التطبيق أو المكتبة.
usage: memray [-h] [-v] {run,flamegraph,table,live,tree,parse,summary,stats} ...
Memory profiler for Python applications
Run `memray run` to generate a memory profile report, then use a reporter command
such as `memray flamegraph` or `memray table` to convert the results into HTML.
Example:
$ python3 -m memray run -o output.bin my_script.py
$ python3 -m memray flamegraph output.bin
positional arguments:
{run,flamegraph,table,live,tree,parse,summary,stats}
Mode of operation
run Run the specified application and track memory usage
flamegraph Generate an HTML flame graph for peak memory usage
table Generate an HTML table with all records in the peak memory usage
live Remotely monitor allocations in a text-based interface
tree Generate a tree view in the terminal for peak memory usage
parse Debug a results file by parsing and printing each record in it
summary Generate a terminal-based summary report of the functions that allocate most memory
stats Generate high level stats of the memory usage in the terminal
optional arguments:
-h, --help Show this help message and exit
-v, --verbose Increase verbosity. Option is additive and can be specified up to 3 times
-V, --version Displays the current version of Memray
Please submit feedback, ideas, and bug reports by filing a new issue at https://github.com/bloomberg/memray/issues
لاستخدام Memray عبر برنامج نصي أو ملف python واحد، يمكنك استخدام:
python3 -m memray run my_script.py إذا كنت تقوم عادةً بتشغيل تطبيقك باستخدام python3 -m my_module ، فيمكنك استخدام العلامة -m مع memray run :
python3 -m memray run -m my_module يمكنك أيضًا استدعاء Memray كأداة لسطر الأوامر دون الحاجة إلى استخدام -m لاستدعائه كوحدة نمطية:
memray run my_script.py
memray run -m my_module سيكون الناتج عبارة عن ملف ثنائي (مثل memray-my_script.2369.bin ) يمكنك تحليله بطرق مختلفة. إحدى الطرق هي استخدام أمر memray flamegraph لإنشاء رسم بياني لهب:
memray flamegraph my_script.2369.binسيؤدي هذا إلى إنتاج ملف HTML مع رسم بياني ملتهب لاستخدام الذاكرة والذي يمكنك فحصه باستخدام متصفحك المفضل. هناك العديد من التقارير الأخرى التي يمكنك استخدامها لإنشاء أنواع أخرى من التقارير، بعضها يقوم بإنشاء مخرجات تعتمد على المحطة الطرفية والبعض الآخر يقوم بإنشاء ملفات HTML. فيما يلي مثال على مخطط اللهب Memray:
إذا كنت تريد طريقة سهلة ومريحة لاستخدام memray في مجموعة الاختبار الخاصة بك، فيمكنك التفكير في استخدام pytest-memray. بمجرد التثبيت، يتيح لك ملحق pytest إضافة --memray إلى استدعاء سطر الأوامر ببساطة:
pytest --memray tests/وسوف تحصل تلقائيًا على تقرير مثل هذا:
python3 -m pytest tests --memray
=============================================================================================================================== test session starts ================================================================================================================================
platform linux -- Python 3.8.10, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
rootdir: /mypackage, configfile: pytest.ini
plugins: cov-2.12.0, memray-0.1.0
collected 21 items
tests/test_package.py ..................... [100%]
================================================================================================================================= MEMRAY REPORT ==================================================================================================================================
Allocations results for tests/test_package.py::some_test_that_allocates
? Total memory allocated: 24.4MiB
? Total allocations: 33929
Histogram of allocation sizes: |▂ █ |
? Biggest allocating functions:
- parse:/opt/bb/lib/python3.8/ast.py:47 -> 3.0MiB
- parse:/opt/bb/lib/python3.8/ast.py:47 -> 2.3MiB
- _visit:/opt/bb/lib/python3.8/site-packages/astroid/transforms.py:62 -> 576.0KiB
- parse:/opt/bb/lib/python3.8/ast.py:47 -> 517.6KiB
- __init__:/opt/bb/lib/python3.8/site-packages/astroid/node_classes.py:1353 -> 512.0KiB
يمكنك أيضًا استخدام بعض العلامات المضمنة لفشل الاختبارات إذا كان تنفيذ الاختبار المذكور يخصص ذاكرة أكبر من المسموح بها:
@ pytest . mark . limit_memory ( "24 MB" )
def test_foobar ():
# do some stuff that allocates memoryلمعرفة المزيد حول كيفية استخدام المكون الإضافي وتكوينه، راجع وثائق البرنامج المساعد.
يدعم Memray تتبع وظائف C/C++ الأصلية بالإضافة إلى وظائف Python. يمكن أن يكون هذا مفيدًا بشكل خاص عند إنشاء ملفات تعريف للتطبيقات التي تحتوي على امتدادات C (مثل numpy أو pandas ) لأن هذا يعطي رؤية شاملة لمقدار الذاكرة المخصصة بواسطة الامتداد ومقدار الذاكرة المخصصة بواسطة Python نفسها.
لتنشيط التتبع الأصلي، تحتاج إلى توفير الوسيطة --native عند استخدام الأمر الفرعي run :
memray run --native my_script.pyسيؤدي هذا تلقائيًا إلى إضافة معلومات أصلية إلى ملف النتائج وسيتم استخدامها تلقائيًا من قبل أي مراسل (مثل مخطط اللهب أو مراسلي الجدول). هذا يعني أنه بدلاً من رؤية ذلك في مخططات اللهب:
ستتمكن الآن من رؤية ما يحدث داخل مكالمات بايثون:
يعرض المراسلون إطارات أصلية بلون مختلف عن إطارات بايثون. يمكن أيضًا تمييزها من خلال النظر إلى موقع الملف في الإطار (سيتم إنشاء إطارات بايثون عمومًا من ملفات ذات امتداد .py بينما سيتم إنشاء الإطارات الأصلية من ملفات ذات امتدادات مثل .c أو .cpp أو .h).
يعمل الوضع المباشر لـ Memray على تشغيل برنامج نصي أو وحدة نمطية في واجهة طرفية تسمح لك بفحص استخدام الذاكرة بشكل تفاعلي أثناء تشغيلها. يعد هذا مفيدًا لتصحيح أخطاء البرامج النصية أو الوحدات النمطية التي تستغرق وقتًا طويلاً للتشغيل أو التي تعرض أنماط ذاكرة معقدة متعددة. يمكنك استخدام خيار --live لتشغيل البرنامج النصي أو الوحدة النمطية في الوضع المباشر:
memray run --live my_script.pyأو إذا كنت تريد تنفيذ وحدة:
memray run --live -m my_moduleسيُظهر هذا واجهة TUI التالية في جهازك الطرفي:
يتم عرض النتائج بترتيب تنازلي لإجمالي الذاكرة المخصصة بواسطة إحدى الوظائف والوظائف الفرعية التي تستدعيها. يمكنك تغيير الترتيب باستخدام اختصارات لوحة المفاتيح التالية:
t (افتراضي): فرز حسب إجمالي الذاكرة
o: فرز حسب الذاكرة الخاصة
ج: فرز حسب عدد التخصيص
في معظم المحطات، يمكنك أيضًا النقر فوق الأزرار "فرز حسب الإجمالي" و"فرز حسب الخاص" و"فرز حسب المخصصات" الموجودة في التذييل.
يتم وضع خط تحت عنوان العمود الذي تم فرزه.
افتراضيًا، سيعرض الأمر المباشر الموضوع الرئيسي للبرنامج. يمكنك الاطلاع على المواضيع المختلفة للبرنامج بالضغط على مفتاحي أكبر من وأقل من، < و > . في معظم المحطات، يمكنك أيضًا النقر فوق زري "الموضوع السابق" و"الموضوع التالي" الموجودين في التذييل.
بالإضافة إلى تتبع عمليات بايثون من واجهة سطر الأوامر (CLI) باستخدام memray run ، فمن الممكن أيضًا تمكين التتبع برمجيًا ضمن برنامج بايثون قيد التشغيل.
import memray
with memray . Tracker ( "output_file.bin" ):
print ( "Allocations will be tracked until the with block ends" )للحصول على التفاصيل، راجع وثائق API.
Memray حاصل على ترخيص Apache-2.0، كما هو موجود في ملف الترخيص.
اعتمد هذا المشروع مدونة قواعد السلوك. إذا كانت لديك أية مخاوف بشأن القواعد أو السلوك الذي واجهته في المشروع، فيرجى الاتصال بنا على [email protected].
إذا كنت تعتقد أنك حددت ثغرة أمنية في هذا المشروع، فيرجى إرسال بريد إلكتروني إلى فريق المشروع على [email protected]، مع ذكر تفاصيل المشكلة المشتبه فيها وأي طرق وجدتها لإعادة إنتاجها.
يرجى عدم فتح مشكلة في مستودع GitHub، لأننا نفضل الحفاظ على خصوصية تقارير الثغرات الأمنية حتى تتاح لنا الفرصة لمراجعتها ومعالجتها.
نحن نرحب بمساهماتكم لمساعدتنا على تحسين وتوسيع هذا المشروع!
ستجد أدناه بعض الخطوات الأساسية المطلوبة لتتمكن من المساهمة في المشروع. إذا كانت لديك أي أسئلة حول هذه العملية أو أي جانب آخر من جوانب المساهمة في مشروع Bloomberg مفتوح المصدر، فلا تتردد في إرسال بريد إلكتروني إلى [email protected] وسنقوم بالإجابة على أسئلتك في أسرع وقت ممكن.
وبما أن هذا المشروع يتم توزيعه بموجب شروط ترخيص مفتوح المصدر، فإن المساهمات التي تقدمها يتم ترخيصها بموجب نفس الشروط. لكي نتمكن من قبول مساهماتك، سنحتاج إلى تأكيد صريح منك بأنك قادر وراغب في تقديمها بموجب هذه الشروط، وتسمى الآلية التي نستخدمها للقيام بذلك بشهادة المنشأ للمطور (DCO). . وهذا مشابه جدًا للعملية التي تستخدمها Linux kernel وSamba والعديد من المشاريع الكبرى الأخرى مفتوحة المصدر.
للمشاركة بموجب هذه الشروط، كل ما عليك فعله هو تضمين سطر مثل ما يلي باعتباره السطر الأخير من رسالة الالتزام لكل التزام في مساهمتك:
Signed-Off-By: Random J. Developer <[email protected]>
إن أبسط طريقة لتحقيق ذلك هي إضافة -s أو --signoff إلى أمر git commit .
يجب عليك استخدام اسمك الحقيقي (عذرًا، ممنوع استخدام أسماء مستعارة، ولا مساهمات مجهولة المصدر).
