python-docs-id/howto/perf_profiling.po at 3.14 · python/python-docs-id

446 lines (390 loc) · 16.1 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
# Translators:
# python-doc bot, 2025
"Project-Id-Version: Python 3.15\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-05-27 16:58+0000\n"
"PO-Revision-Date: 2025-09-16 00:00+0000\n"
"Last-Translator: python-doc bot, 2025\n"
"Language-Team: Indonesian (https://app.transifex.com/python-doc/teams/5390/"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Language: id\n"
"Plural-Forms: nplurals=1; plural=0;\n"
msgid "Python support for the ``perf map`` compatible profilers"
msgid "author"
msgstr "penulis"
msgid "Pablo Galindo"
"`The Linux perf profiler <https://perf.wiki.kernel.org>`_ and `samply "
"<https://github.com/mstange/samply>`_ are powerful tools that allow you to "
"profile and obtain information about the performance of your application. "
"Both tools have vibrant ecosystems that aid with the analysis of the data "
"they produce."
"The main problem with using these profilers with Python applications is that "
"they only get information about native symbols, that is, the names of "
"functions and procedures written in C. This means that the names and file "
"names of Python functions in your code will not appear in the profiler "
"Since Python 3.12, the interpreter can run in a special mode that allows "
"Python functions to appear in the output of compatible profilers. When this "
"mode is enabled, the interpreter will interpose a small piece of code "
"compiled on the fly before the execution of every Python function and it "
"will teach the profiler the relationship between this piece of code and the "
"associated Python function using :doc:`perf map files <../c-api/perfmaps>`."
"Support for profiling is available on Linux and macOS on select "
"architectures. Perf is available on Linux, while samply can be used on both "
"Linux and macOS. samply support on macOS is available starting from Python "
"3.15. Check the output of the ``configure`` build step or check the output "
"of ``python -m sysconfig | grep HAVE_PERF_TRAMPOLINE`` to see if your system "
"is supported."
msgid "For example, consider the following script:"
"def foo(n):\n"
"    result = 0\n"
"    for _ in range(n):\n"
"        result += 1\n"
"    return result\n"
"def bar(n):\n"
"    foo(n)\n"
"def baz(n):\n"
"    bar(n)\n"
"if __name__ == \"__main__\":\n"
"    baz(1000000)"
msgid "We can run ``perf`` to sample CPU stack traces at 9999 hertz::"
msgid "$ perf record -F 9999 -g -o perf.data python my_script.py"
msgid "Then we can use ``perf report`` to analyze the data:"
"$ perf report --stdio -n -g\n"
"# Children      Self       Samples  Command     Shared Object       Symbol\n"
"# ........  ........  ............  ..........  ..................  ..........................................\n"
"    91.08%     0.00%             0  python.exe  python.exe          [.] "
"            |\n"
"            ---_start\n"
"            |\n"
"                --90.71%--__libc_start_main\n"
"                        Py_BytesMain\n"
"                        |--56.88%--pymain_run_python.constprop.0\n"
"                        |          |--56.13%--_PyRun_AnyFileObject\n"
"                        |          |          _PyRun_SimpleFileObject\n"
"                        |          |          |--55.02%--run_mod\n"
"PyEval_EvalCode\n"
"_PyEval_EvalFrameDefault\n"
"PyObject_Vectorcall\n"
"_PyEval_Vector\n"
"_PyEval_EvalFrameDefault\n"
"PyObject_Vectorcall\n"
"_PyEval_Vector\n"
"_PyEval_EvalFrameDefault\n"
"PyObject_Vectorcall\n"
"_PyEval_Vector\n"
"|--51.67%--_PyEval_EvalFrameDefault\n"
"|          |\n"
"|          |--11.52%--_PyCompactLong_Add\n"
"|          |          |\n"
"|          |          |--2.97%--_PyObject_Malloc\n"
"As you can see, the Python functions are not shown in the output, only "
"``_PyEval_EvalFrameDefault`` (the function that evaluates the Python "
"bytecode) shows up. Unfortunately that's not very useful because all Python "
"functions use the same C function to evaluate bytecode so we cannot know "
"which Python function corresponds to which bytecode-evaluating function."
"Instead, if we run the same experiment with ``perf`` support enabled we get:"
"$ perf report --stdio -n -g\n"
"# Children      Self       Samples  Command     Shared Object       Symbol\n"
"# ........  ........  ............  ..........  ..................  .....................................................................\n"
"    90.58%     0.36%             1  python.exe  python.exe          [.] "
"            |\n"
"            ---_start\n"
"            |\n"
"                --89.86%--__libc_start_main\n"
"                        Py_BytesMain\n"
"                        |--55.43%--pymain_run_python.constprop.0\n"
"                        |          |--54.71%--_PyRun_AnyFileObject\n"
"                        |          |          _PyRun_SimpleFileObject\n"
"                        |          |          |--53.62%--run_mod\n"
"PyEval_EvalCode\n"
"<module>:/src/script.py\n"
"_PyEval_EvalFrameDefault\n"
"PyObject_Vectorcall\n"
"_PyEval_Vector\n"
"src/script.py\n"
"_PyEval_EvalFrameDefault\n"
"PyObject_Vectorcall\n"
"_PyEval_Vector\n"
"src/script.py\n"
"_PyEval_EvalFrameDefault\n"
"PyObject_Vectorcall\n"
"_PyEval_Vector\n"
"src/script.py\n"
"|--51.81%--_PyEval_EvalFrameDefault\n"
"|          |\n"
"|          |--13.77%--_PyCompactLong_Add\n"
"|          |          |\n"
"|          |          |--3.26%--_PyObject_Malloc"
msgid "Using the samply profiler"
"samply is a modern profiler that can be used as an alternative to perf. It "
"uses the same perf map files that Python generates, making it compatible "
"with Python's profiling support. samply is particularly useful on macOS "
"where perf is not available."
"To use samply with Python, first install it following the instructions at "
"https://github.com/mstange/samply, then run::"
msgid "$ samply record PYTHONPERFSUPPORT=1 python my_script.py"
"This will open a web interface where you can analyze the profiling data "
"interactively. The advantage of samply is that it provides a modern web-"
"based interface for analyzing profiling data and works on both Linux and "
"On macOS, samply support requires Python 3.15 or later. Also on macOS, "
"samply can't profile signed Python executables due to restrictions by macOS. "
"You can profile with Python binaries that you've compiled yourself, or which "
"are unsigned or locally-signed (such as anything installed by Homebrew). In "
"order to attach to running processes on macOS, run ``samply setup`` once "
"(and every time samply is updated) to self-sign the samply binary."
msgid "How to enable ``perf`` profiling support"
"``perf`` profiling support can be enabled either from the start using the "
"environment variable :envvar:`PYTHONPERFSUPPORT` or the :option:`-X perf <-"
"X>` option, or dynamically using :func:`sys.activate_stack_trampoline` and :"
"func:`sys.deactivate_stack_trampoline`."
"The :mod:`!sys` functions take precedence over the :option:`!-X` option, "
"the :option:`!-X` option takes precedence over the environment variable."
msgid "Example, using the environment variable::"
"$ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python my_script."
"$ perf report -g -i perf.data"
msgid "Example, using the :option:`!-X` option::"
"$ perf record -F 9999 -g -o perf.data python -X perf my_script.py\n"
"$ perf report -g -i perf.data"
msgid "Example, using the :mod:`sys` APIs in file :file:`example.py`:"
"import sys\n"
"sys.activate_stack_trampoline(\"perf\")\n"
"do_profiled_stuff()\n"
"sys.deactivate_stack_trampoline()\n"
"non_profiled_stuff()"
msgid "...then::"
"$ perf record -F 9999 -g -o perf.data python ./example.py\n"
"$ perf report -g -i perf.data"
msgid "How to obtain the best results"
"For best results, keep frame pointers enabled. On supported GCC-compatible "
"toolchains, CPython builds itself with ``-fno-omit-frame-pointer`` and "
"similar flags (see :option:`--without-frame-pointers` for details). These "
"flags allow profilers to unwind using only the frame pointer and not on "
"DWARF debug information. This is because as the code that is interposed to "
"allow ``perf`` support is dynamically generated it doesn't have any DWARF "
"debugging information available."
"You can check if your system has been compiled with this flag by running::"
msgid "$ python -m sysconfig | grep 'no-omit-frame-pointer'"
"If you don't see any output it means that your interpreter has not been "
"compiled with frame pointers and therefore it may not be able to show Python "
"functions in the output of ``perf``."
msgid "How to work without frame pointers"
"If you are working with a Python interpreter that has been compiled without "
"frame pointers, you can still use the ``perf`` profiler, but the overhead "
"will be a bit higher because Python needs to generate unwinding information "
"for every Python function call on the fly. Additionally, ``perf`` will take "
"more time to process the data because it will need to use the DWARF "
"debugging information to unwind the stack and this is a slow process."
"To enable this mode, you can use the environment variable :envvar:"
"`PYTHON_PERF_JIT_SUPPORT` or the :option:`-X perf_jit <-X>` option, which "
"will enable the JIT mode for the ``perf`` profiler."
"Due to a bug in the ``perf`` tool, only ``perf`` versions higher than v6.8 "
"will work with the JIT mode.  The fix was also backported to the v6.7.2 "
"version of the tool."
"Note that when checking the version of the ``perf`` tool (which can be done "
"by running ``perf version``) you must take into account that some distros "
"add some custom version numbers including a ``-`` character.  This means "
"that ``perf 6.7-3`` is not necessarily ``perf 6.7.3``."
"When using the perf JIT mode, you need an extra step before you can run "
"``perf report``. You need to call the ``perf inject`` command to inject the "
"JIT information into the ``perf.data`` file.::"
"$ perf record -F 9999 -g -k 1 --call-graph dwarf -o perf.data python -"
"Xperf_jit my_script.py\n"
"$ perf inject -i perf.data --jit --output perf.jit.data\n"
"$ perf report -g -i perf.jit.data"
msgid "or using the environment variable::"
"$ PYTHON_PERF_JIT_SUPPORT=1 perf record -F 9999 -g --call-graph dwarf -o "
"perf.data python my_script.py\n"
"$ perf inject -i perf.data --jit --output perf.jit.data\n"
"$ perf report -g -i perf.jit.data"
"``perf inject --jit`` command will read ``perf.data``, automatically pick up "
"the perf dump file that Python creates (in ``/tmp/perf-$PID.dump``), and "
"then create ``perf.jit.data`` which merges all the JIT information together. "
"It should also create a lot of ``jitted-XXXX-N.so`` files in the current "
"directory which are ELF images for all the JIT trampolines that were created "
"by Python."
"When using ``--call-graph dwarf``, the ``perf`` tool will take snapshots of "
"the stack of the process being profiled and save the information in the "
"``perf.data`` file. By default, the size of the stack dump is 8192 bytes, "
"but you can change the size by passing it after a comma like ``--call-graph "
"dwarf,16384``."
"The size of the stack dump is important because if the size is too small "
"``perf`` will not be able to unwind the stack and the output will be "
"incomplete. On the other hand, if the size is too big, then ``perf`` won't "
"be able to sample the process as frequently as it would like as the overhead "
"will be higher."
"The stack size is particularly important when profiling Python code compiled "
"with low optimization levels (like ``-O0``), as these builds tend to have "
"larger stack frames. If you are compiling Python with ``-O0`` and not seeing "
"Python functions in your profiling output, try increasing the stack dump "
"size to 65528 bytes (the maximum)::"
"$ perf record -F 9999 -g -k 1 --call-graph dwarf,65528 -o perf.data python -"
"Xperf_jit my_script.py"
msgid "Different compilation flags can significantly impact stack sizes:"
"Builds with ``-O0`` typically have much larger stack frames than those with "
"``-O1`` or higher"
"Adding optimizations (``-O1``, ``-O2``, etc.) typically reduces stack size"
"Frame pointers (``-fno-omit-frame-pointer``) generally provide more reliable "
"stack unwinding"
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

perf_profiling.po

Latest commit

History

perf_profiling.po

File metadata and controls
