You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d84537f
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+79-15Lines changed: 79 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,37 +1,97 @@
1
1
# VMProf Python package
2
2
3
-
[](https://travis-ci.org/vmprof/vmprof-python)
4
-
[/statusIcon.svg)](https://teamcity.jetbrains.com/project.html?projectId=VMprofPython)
[](https://vmprof.readthedocs.org/en/latest/)
6
-
[](https://ci.appveyor.com/project/planrich/vmprof-python)
7
6
7
+
**VMProf** is a lightweight statistical profiler for CPython and PyPy. It samples
8
+
the call stack of a running program and writes a profile file you can open in
9
+
several viewers.
8
10
9
11
Head over to https://vmprof.readthedocs.org for more info!
10
12
11
13
## Installation
12
14
13
15
```console
14
16
pip install vmprof
15
-
python -m vmprof <your program> <your program args>
16
17
```
17
18
18
-
Our build system ships wheels to PyPI (Linux, Mac OS X). If you build from source you need
19
-
to install CPython development headers and libunwind headers (on Linux only).
20
-
On Windows this means you need Microsoft Visual C++ Compiler for your Python version.
19
+
VMProf 0.6 supports CPython 3.10 through 3.14 and PyPy, on Linux, Mac OS X and
20
+
Windows. Native profiling is available on Linux and Mac OS X.
21
+
22
+
Wheels are published to PyPI for all three platforms with libunwind bundled in.
23
+
If you build from source you need the CPython development headers, and on Linux
24
+
the libunwind headers as well — on Debian or Ubuntu, `python3-dev` and
25
+
`libunwind-dev`. On Windows you need the Microsoft Visual C++ Compiler for your
26
+
Python version.
27
+
28
+
## Quick start
29
+
30
+
Record a profile:
31
+
32
+
```console
33
+
$ python -m vmprof -o profile.prof <your program><your program args>
34
+
```
35
+
36
+
Then open `profile.prof` in whichever viewer fits the question you're asking:
37
+
38
+
| Viewer | Good for | How |
39
+
| --- | --- | --- |
40
+
|`vmprofshow`| a quick look, no extra installs |`vmprofshow profile.prof tree`|
VMProf consists of several projects working together:
5
-
6
-
* `vmprof-python`_: The PyPI package providing the command line interface to enable vmprof.
7
-
* `vmprof-server`_: Webservice hosted at `vmprof.com`_. Hosts and visualizes data uploaded by `vmprof-python`_ package.
8
-
* `vmprof-integration`_: Test suite for pulling together all different projects and ensuring that all play together nicely.
9
-
* `PyPy`_: A virtual machine for the Python programming language. Most notably it contains an implementation for the logging facility `vmprof-server`_ can display.
10
-
11
-
The following description helps you to set up a development environment on Linux. For Windows
12
-
and MacOSX the instructions might be similar.
4
+
vmprof is made up of a Python package and a C extension, built with
5
+
`meson-python`_. The `PyPy`_ side of the JIT log support lives in PyPy itself.
This is a very important test suite to ensure that all packages work together. It is automatically run every day by travis. You can run them locally. If you happen not to run a Debian base distribution, you can provide the following shell variable to prevent the tests from downloading a Debian PyPy::
Copy file name to clipboardExpand all lines: docs/faq.rst
+10-8Lines changed: 10 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,22 +9,24 @@ Frequently Asked Questions
9
9
10
10
* **Is it possible to just profile a part of my program?**: Yes here an example how you could do just that::
11
11
12
-
with open('test.prof', 'w+b') as fd:
12
+
with open('profile.prof', 'w+b') as fd:
13
13
vmprof.enable(fd.fileno())
14
14
my_function_or_program()
15
15
vmprof.disable()
16
16
17
-
Upload it later to vmprof.com if you choose to inspect it further::
17
+
Then open ``profile.prof`` in any of the viewers described in
18
+
:doc:`viewers`.
18
19
19
-
$ python -m vmprof.upload test.prof
20
-
21
-
22
-
23
-
* **What do the colors on vmprof.com mean?**: For plain CPython there is no particular meaning, we might change
24
-
that in the future. For PyPy we have a color coding to show at which state the VM sampled (e.g. JIT, Warmup, ...).
20
+
* **Which viewer should I use?**: ``vmprofshow`` is bundled and needs nothing
21
+
installed, the Firefox Profiler gives you a flame graph and a timeline, and
22
+
kcachegrind gives you caller and callee lists and a call graph. See
23
+
:doc:`viewers`.
25
24
26
25
* **My Windows profile is malformed?**: Please ensure that you open the file in binary mode. Otherwise Windows
27
26
will transform ``\n`` to ``\r\n``.
28
27
29
28
* **Do I need to install libunwind?**: Usually not. We ship python wheels that bundle libunwind shared objects. If you install vmprof from source, then you need to install the development headers of your distribution. OSX ships libunwind per default. If your pip version is really old it does not pull wheels and it will end up compiling from source.
30
29
30
+
* **Why are the call counts in kcachegrind all 1?**: Because vmprof samples
31
+
the stack rather than instrumenting calls, so it never sees an individual
0 commit comments