Release v0.7.0 (#28)

See ChangeLog for more details.
P403n1x87 · Jul 28, 2019 · 8bea939 · 8bea939
1 parent f8a2d53
commit 8bea939
Show file tree

Hide file tree

Showing 29 changed files with 1,537 additions and 554 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,8 +1,3 @@
-os:
-  - windows
-  - linux
-  - osx
-
 language: c
 
 compiler:
@@ -14,35 +9,43 @@ git:
 osx_image: xcode10
 
 sudo: required
-
-addons:
-  apt:
-    sources:
-    - sourceline: 'ppa:deadsnakes/ppa'
-    - sourceline: 'ppa:duggan/bats'
-    packages:
-    - bats
-    - valgrind
-
-    - python2.3
-    - python2.4
-    - python2.5
-    - python2.6
-    - python2.7
-
-    - python3.3
-    - python3.4
-    - python3.5
-    - python3.6
-    - python3.7
+dist: bionic
+
+matrix:
+  include:
+    # Linux
+    - env: TARGET=arm-unknown-linux-gnueabi
+    - env: TARGET=armv7-unknown-linux-gnueabihf
+    - env: TARGET=i686-unknown-linux-gnu
+    - env: TARGET=x86_64-unknown-linux-gnu
+
+    # OSX
+    - env: TARGET=i686-apple-darwin
+      os: osx
+    - env: TARGET=x86_64-apple-darwin
+      os: osx
+
+    # Windows
+    - env: TARGET=x86_64-pc-windows-gnu
+      os: windows
 
 before_script:
+  # Linux Dependencies
+  if [[ "$TRAVIS_OS_NAME" == "linux" ]];
+  then
+    sudo add-apt-repository ppa:deadsnakes/ppa -y;
+    sudo add-apt-repository ppa:duggan/bats -y;
+
+    sudo apt install bats valgrind python2.{3..7} python3.{3..7} -y;
+  fi
+
   if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then autoreconf --install; fi
 
 script:
-  - if [[ "$TRAVIS_OS_NAME" == "linux"   ]]; then ./configure && make && sudo make check; fi
-  - if [[ "$TRAVIS_OS_NAME" == "osx"     ]]; then gcc -s -Wall -O3 -o src/austin src/*.c; fi
-  - if [[ "$TRAVIS_OS_NAME" == "windows" ]]; then gcc -s -Wall -O3 -o src/austin src/*.c; fi
+  - echo $TRAVIS_OS_NAME -- $TARGET
+  - if [[ "$TRAVIS_OS_NAME" == "linux"   ]]; then ./configure && make && sudo make check;         fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx"     ]]; then gcc -s -Wall -O3 -o src/austin src/*.c;         fi
+  - if [[ "$TRAVIS_OS_NAME" == "windows" ]]; then gcc -s -Wall -O3 -o src/austin src/*.c -lpsapi; fi
 
 after_success:
   ./src/austin --usage
@@ -56,9 +59,9 @@ before_deploy:
   - export TRAVIS_TAG=v$VERSION
   - echo "==== Preparing to create GitHub Release for version $VERSION ===="
 
-  - if [[ "$TRAVIS_OS_NAME" == "linux"   ]]; then export ZIP_CMD="tar -Jcf"   && export ZIP_SUFFIX="linux-amd64.tar.xz" && export AUSTIN_EXE=austin;     fi
-  - if [[ "$TRAVIS_OS_NAME" == "osx"     ]]; then export ZIP_CMD="zip -r"     && export ZIP_SUFFIX="mac-x86_64.zip"     && export AUSTIN_EXE=austin;     fi
-  - if [[ "$TRAVIS_OS_NAME" == "windows" ]]; then export ZIP_CMD="7z a -tzip" && export ZIP_SUFFIX="win64.zip"          && export AUSTIN_EXE=austin.exe; fi
+  - if [[ "$TRAVIS_OS_NAME" == "linux"   ]]; then export ZIP_CMD="tar -Jcf"   && export ZIP_SUFFIX="linux-${TARGET%-*}.tar.xz" && export AUSTIN_EXE=austin;     fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx"     ]]; then export ZIP_CMD="zip -r"     && export ZIP_SUFFIX="mac-${TARGET%-*}.zip"      && export AUSTIN_EXE=austin;     fi
+  - if [[ "$TRAVIS_OS_NAME" == "windows" ]]; then export ZIP_CMD="7z a -tzip" && export ZIP_SUFFIX="win-${TARGET%-*}.zip"      && export AUSTIN_EXE=austin.exe; fi
   - export ARTEFACT="austin-${VERSION}-${ZIP_SUFFIX}"
   - echo " - Using command $ZIP_CMD to create artefact $ARTEFACT"
 

diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,24 @@
+2019-07-28 v0.7.0
+
+  Austin can now profile memory usage and output samples to a file.
+
+  Added new command line options:
+
+    - --memory, -m:
+
+        Switch to memory profling mode
+
+    - --full, -f:
+
+        Generate samples with a full set of metrics, which include timing and
+        memory prifiling information. Note that the output from this mode needs
+        to be processed before it can be used with FlameGraph.
+
+    - --output, -o:
+
+        Designate an output file for the collected samples.
+
+
 2018-10-15 v0.6.0-beta
 
   Introduced native support for MacOS and Windows.

diff --git a/README.md b/README.md
@@ -23,8 +23,8 @@
     <img src="https://build.snapcraft.io/badge/P403n1x87/austin.svg"
          alt="Snap Status">
   </a>
-  <img src="https://img.shields.io/badge/version-0.6.1--beta-blue.svg"
-       alt="Version 0.6.1-beta">
+  <img src="https://img.shields.io/badge/version-0.7.0-blue.svg"
+       alt="Version 0.7.0">
   <a href="https://github.com/P403n1x87/austin/blob/master/LICENSE.md">
     <img src="https://img.shields.io/badge/license-GPLv3-ff69b4.svg"
          alt="LICENSE">
@@ -43,7 +43,18 @@
   <a href="#usage"><b>Usage</b></a>&nbsp;&bull;
   <a href="#compatibility"><b>Compatibility</b></a>&nbsp;&bull;
   <a href="#why--austin"><b>Why <img src="art/austin_logo.svg" height="20px" /> Austin</b></a>&nbsp;&bull;
-  <a href="#examples"><b>Examples</b></a>
+  <a href="#examples"><b>Examples</b></a>&nbsp;&bull;
+  <a href="#contribute"><b>Contribute</b></a>
+</p>
+
+<p align="center">
+  <a href="https://www.patreon.com/bePatron?u=19221563">
+    <img src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.herokuapp.com%2FP403n1x87&style=for-the-badge" />
+  </a><br/>
+
+  <a href="https://www.buymeacoffee.com/Q9C1Hnm28" target="_blank">
+    <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" />
+  </a>
 </p>
 
 <!--
@@ -52,7 +63,7 @@
 
 <h3 align="center">A frame stack sampler for CPython</h3>
 
-[![Build Status](https://travis-ci.org/P403n1x87/austin.svg?branch=master)](https://travis-ci.org/P403n1x87/austin) ![Version](https://img.shields.io/badge/version-0.6.1--beta-blue.svg) [![License](https://img.shields.io/badge/license-GPLv3-ff69b4.svg)](https://github.com/P403n1x87/austin/blob/master/LICENSE.md)
+[![Build Status](https://travis-ci.org/P403n1x87/austin.svg?branch=master)](https://travis-ci.org/P403n1x87/austin) ![Version](https://img.shields.io/badge/version-0.7.0-blue.svg) [![License](https://img.shields.io/badge/license-GPLv3-ff69b4.svg)](https://github.com/P403n1x87/austin/blob/master/LICENSE.md)
 
 -->
 
@@ -64,6 +75,12 @@ samples the stack traces of a Python application so that they can be visualised
 and analysed. As such, it serves the basis for building powerful profilers for
 Python.
 
+Key features are:
+- no instrumentation required;
+- minimal impact on the performance of the profiling target;
+- fast and lightweight;
+- time and memory profiling modes.
+
 The most interesting use of Austin is probably in conjunction with
 [FlameGraph](https://github.com/brendangregg/FlameGraph) to profile Python
 applications while they are running, without the need of instrumentation. This
@@ -82,9 +99,15 @@ spirit to [py-spy](https://github.com/benfred/py-spy).
 
 # Installation
 
-Austin can be installed using `autotools` or as a snap from the Snap Store. The
+Austin is available from the major software repositories of the most popular platforms.
+
+On Linux, it can be installed using `autotools` or as a snap from the Snap Store. The
 latter will automatically perform the steps of the `autotools` method with a
-single command.
+single command. On distributions derived from Debian, Austin can be installed from the official repositores with Aptitude.
+
+On Windows, Austin can be easily installed from the command line from the Chocolatey repositories.
+
+For any other platform, compiling Austin from sources is as easy as cloning the repository and running the C compiler.
 
 ## With `autotools`
 
@@ -118,7 +141,7 @@ or `%TEMP%/austin.log` on Windows.
 Austin can be installed from the Snap Store with the following command
 
 ~~~ bash
-sudo snap install austin --beta --classic
+sudo snap install austin --classic
 ~~~
 
 [![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-white.svg)](https://snapcraft.io/austin)
@@ -130,20 +153,60 @@ On March 30 2019, Austin has been accepted into the official Debian
 repositories and can therefore be installed with `apt`. The first Ubuntu
 release to include Austin is 19.10.
 
+## From Chocolatey
+
+To install [Austin](https://chocolatey.org/packages/austin) from
+[Chocolatey](https://chocolatey.org/), run the following command from the
+command line or from PowerShell
+
+~~~ shell
+choco install austin
+~~~
+
+To upgrade run the following command from the command line or from PowerShell:
+
+~~~ shell
+choco upgrade austin
+~~~
+
+
+## From sources
+
+To install Austin from sources using the GNU C compiler, without `autotools`, clone the repository with
+
+~~~ bash
+git clone --depth=1 https://github.com/P403n1x87/austin.git
+~~~
+
+and then run
+
+~~~ bash
+gcc -s -Wall -O3 -o src/austin src/*.c
+~~~
+
+An extra flag is required on Windows, so the command to use in this case is
+
+~~~ bash
+gcc -s -Wall -O3 -o src/austin src/*.c -lpsapi
+~~~
+
 
 # Usage
 
 ~~~
 Usage: austin [OPTION...] command [ARG...]
 Austin -- A frame stack sampler for Python.
 
-  -a, --alt-format           alternative collapsed stack sample format.
-  -e, --exclude-empty        do not output samples of threads with no frame
+  -a, --alt-format           Alternative collapsed stack sample format.
+  -e, --exclude-empty        Do not output samples of threads with no frame
                              stacks.
+  -f, --full                 Produce the full set of metrics (time +mem -mem).
   -i, --interval=n_us        Sampling interval (default is 500us).
+  -m, --memory               Profile memory usage.
+  -o, --output=FILE          Specify an output file for the collected samples.
   -p, --pid=PID              The the ID of the process to which Austin should
                              attach.
-  -s, --sleepless            suppress idle samples.
+  -s, --sleepless            Suppress idle samples.
   -t, --timeout=n_ms         Approximate start up wait time. Increase on slow
                              machines (default is 100ms).
   -?, --help                 Give this help list
@@ -160,7 +223,9 @@ the collapsed one that is recognised by
 to `flamegraph.pl` in order to produce flame graphs, or redirected to a file for
 some further processing.
 
-Each line has the structure
+## Normal mode
+
+By default, each line has the following structure:
 
 ~~~
 Thread [tid];[func] ([mod]);#[line no];[func] ...;L[line no] [usec]
@@ -177,6 +242,20 @@ format
 Thread [tid];[func] ([mod]:[line no]);#[line no];[func] ... ([mod]:[line no]) [usec]
 ~~~
 
+## Memory and Full modes
+
+When profiling in memory mode with the `-m` or `--memory` switch, the metric
+value at the end of each line is the memory delta between samples, measured in
+KB. In full mode (`-f` or `--full` switches), the last three values on each line
+are the time delta, any positive memory delta (memory allocations) or zero and
+any negative memory delta (memory releases) or zero, i.e.
+
+~~~
+Thread [tid];[func] ([mod]:[line no]);#[line no];[func] ... ([mod]:[line no]) [usec] [+KB] [-KB]
+~~~
+
+## Logging
+
 Austin uses `syslog` on Linux and Mac OS, and `%TEMP%\austin.log` on Windows
 for log messages so make sure to watch these to get execution details and
 statistics. _Bad_ frames are output together with the other frames. In general,
@@ -206,7 +285,7 @@ otherwise specified).
 - Python 3.4 (3.4.9+) on Ubuntu 18.04.1
 - Python 3.5 (3.5.2) on Ubuntu 18.04.1
 - Python 3.6 (3.6.5, 3.6.6, 3.6.7) on Ubuntu 18.04.x
-- Python 3.7 (3.7.0, 3.7.1) on Ubuntu 18.04.1
+- Python 3.7 (3.7.0, 3.7.1, 3.7.3, 3.7.4) on Ubuntu 18.04.x
 
 
 ## <img src="https://upload.wikimedia.org/wikipedia/commons/f/fa/Apple_logo_black.svg" height="24px" /> Mac OS
@@ -417,7 +496,32 @@ serves on `WEBAUSTIN_HOST` if set or on `localhost` otherwise. The port can be
 controlled with the `WEBAUSTIN_PORT` environment variable. If it is not set,
 Web Austin will use an ephemeral port.
 
-<p align="center"><img src="art/web-austin.gif" /></p
+<p align="center"><img src="art/web-austin.gif" /></p>
+
+
+# Contribute
+
+If you like Austin and you find it useful, there are ways for you to contribute.
+
+If you want to help with the development, then have a look at the open issues
+and have a look at the [contributing guidelines](CONTRIBUTING.md) before you
+open a pull request.
+
+You can also contribute to the development of Austin by either [becoming a
+Patron](https://www.patreon.com/bePatron?u=19221563) on Patreon
+
+<a href="https://www.patreon.com/bePatron?u=19221563">
+  <img src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.herokuapp.com%2FP403n1x87&style=for-the-badge" />
+</a><br/>
+
+by [buying me a coffee](https://www.buymeacoffee.com/Q9C1Hnm28) on BMC
+
+<a href="https://www.buymeacoffee.com/Q9C1Hnm28" target="_blank">
+  <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" />
+</a>
+
+or by chipping in a few pennies on
+[PayPal.Me](https://www.paypal.me/gtornetta/1).
 
 ----
 

diff --git a/configure.ac b/configure.ac
@@ -2,7 +2,7 @@
 # Process this file with autoconf to produce a configure script.
 
 AC_PREREQ([2.69])
-AC_INIT([austin], [0.6.1-beta], [https://github.com/p403n1x87/austin/issues])
+AC_INIT([austin], [0.7.0], [https://github.com/p403n1x87/austin/issues])
 AC_CONFIG_SRCDIR([config.h.in])
 AC_CONFIG_HEADERS([config.h])
 AM_INIT_AUTOMAKE

diff --git a/debian/austin.1 b/debian/austin.1
@@ -1,5 +1,5 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.6.
-.TH AUSTIN "1" "January 2019" "austin 0.6.1-beta" "User Commands"
+.TH AUSTIN "1" "July 2019" "austin 0.7.0" "User Commands"
 .SH NAME
 austin \- Frame stack sampler for CPython (MANUAL)
 .SH SYNOPSIS
@@ -9,21 +9,30 @@ austin \- Frame stack sampler for CPython (MANUAL)
 Austin \fB\-\-\fR Frame stack sampler for CPython.
 .TP
 \fB\-a\fR, \fB\-\-alt\-format\fR
-alternative collapsed stack sample format.
+Alternative collapsed stack sample format.
 .TP
 \fB\-e\fR, \fB\-\-exclude\-empty\fR
-do not output samples of threads with no frame
+Do not output samples of threads with no frame
 stacks.
 .TP
+\fB\-f\fR, \fB\-\-full\fR
+Produce the full set of metrics (time +mem \fB\-mem\fR).
+.TP
 \fB\-i\fR, \fB\-\-interval\fR=\fI\,n_us\/\fR
 Sampling interval (default is 500us).
 .TP
+\fB\-m\fR, \fB\-\-memory\fR
+Profile memory usage.
+.TP
+\fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
+Specify an output file for the collected samples.
+.TP
 \fB\-p\fR, \fB\-\-pid\fR=\fI\,PID\/\fR
 The the ID of the process to which Austin should
 attach.
 .TP
 \fB\-s\fR, \fB\-\-sleepless\fR
-suppress idle samples.
+Suppress idle samples.
 .TP
 \fB\-t\fR, \fB\-\-timeout\fR=\fI\,n_ms\/\fR
 Approximate start up wait time. Increase on slow

diff --git a/debian/changelog b/debian/changelog
@@ -1,3 +1,10 @@
+austin (0.7.0-1) unstable; urgency=medium
+
+  * Austin can now profile memory usage and output samples to a file.
+
+ -- Gabriele N. Tornetta <[email protected]>  Sun, 28 Jul 2019 12:55:00 +0100
+
+
 austin (0.6.1~beta-1) unstable; urgency=medium
 
   * Initial release (Closes: #918518)