diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..6e23020 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,22 @@ +# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.154.2/containers/python-3/.devcontainer/base.Dockerfile + +# [Choice] Python version: 3, 3.9, 3.8, 3.7, 3.6 +ARG VARIANT="3" +FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT} + +# [Option] Install Node.js +ARG INSTALL_NODE="true" +ARG NODE_VERSION="lts/*" +RUN if [ "${INSTALL_NODE}" = "true" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi + +# [Optional] If your pip requirements rarely change, uncomment this section to add them to the image. +# COPY requirements.txt /tmp/pip-tmp/ +# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \ +# && rm -rf /tmp/pip-tmp + +# [Optional] Uncomment this section to install additional OS packages. +RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ + && apt-get -y install --no-install-recommends strace perl + +# [Optional] Uncomment this line to install global node packages. +# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g " 2>&1 \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..525a1ec --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,48 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containers/tree/v0.154.2/containers/python-3 +{ + "name": "Python 3", + "build": { + "dockerfile": "Dockerfile", + "context": "..", + "args": { + // Update 'VARIANT' to pick a Python version: 3, 3.6, 3.7, 3.8, 3.9 + "VARIANT": "3", + // Options + "INSTALL_NODE": "true", + "NODE_VERSION": "lts/*" + } + }, + // Set *default* container specific settings.json values on container create. + "settings": { + "terminal.integrated.shell.linux": "/bin/bash", + "python.pythonPath": "/usr/local/bin/python", + "python.linting.enabled": true, + "python.linting.pylintEnabled": true, + "python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8", + "python.formatting.blackPath": "/usr/local/py-utils/bin/black", + "python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf", + "python.linting.banditPath": "/usr/local/py-utils/bin/bandit", + "python.linting.flake8Path": "/usr/local/py-utils/bin/flake8", + "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy", + "python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle", + "python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle", + "python.linting.pylintPath": "/usr/local/py-utils/bin/pylint" + }, + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "ms-python.python", + "bungcip.better-toml", + "bodil.prettier-toml", + "ms-python.vscode-pylance", + "lextudio.restructuredtext", + "stkb.rewrap", + "github.vscode-pull-request-github" + ], + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "python -m venv venv && venv/bin/pip install -r requirements.txt", + // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + "remoteUser": "vscode" +} \ No newline at end of file diff --git a/.flake8 b/.flake8 new file mode 100644 index 0000000..ede241f --- /dev/null +++ b/.flake8 @@ -0,0 +1,3 @@ +[flake8] +ignore = E203 +exclude = .git,__pycache__,doc/conf.py,build,dist,venv,.tox \ No newline at end of file diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 4fd3d3d..2974d10 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -26,14 +26,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - python -m pip install flake8 pytest - if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - - name: Lint with flake8 + python -m pip install tox tox-gh-actions + - name: Test with tox run: | - # stop the build if there are Python syntax errors or undefined names - flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics - # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide - flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - - name: Test with pytest - run: | - pytest + tox diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..79e44b4 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,3 @@ +version: 2 +sphinx: + configuration: doc/conf.py \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..0bed933 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,17 @@ +{ + "python.linting.flake8Enabled": true, + "python.formatting.provider": "black", + "editor.formatOnSave": true, + "python.pythonPath": "venv/bin/python", + "python.testing.unittestArgs": [ + "-v", + "-s", + "./src/tests", + "-p", + "test_*.py" + ], + "python.testing.pytestEnabled": false, + "python.testing.nosetestsEnabled": false, + "python.testing.unittestEnabled": true, + "restructuredtext.confPath": "${workspaceFolder}/doc" +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..56d61bd --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,34 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "test", + "type": "shell", + "command": "venv/bin/tox -e py39", + "group": { + "kind": "test", + "isDefault": true + } + }, + { + "label": "build docs", + "type": "shell", + "command": "venv/bin/tox -e docs", + "group": "build" + }, + { + "label": "serve docs", + "type": "shell", + "dependsOn": [ + "build docs" + ], + "command": "cd .tox/docs_out && python -m http.server", + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..41e90c6 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1 @@ +include src/flametrace/perl/*.pl \ No newline at end of file diff --git a/README.md b/README.md index 29b6252..0fa6587 100644 --- a/README.md +++ b/README.md @@ -1 +1,23 @@ -# flametrace \ No newline at end of file +# flametrace + +Build flamegraph charts for process trees, based on strace. + +If you’ve ever wanted to know why a command is slow, flametrace can help! Run +your command under flametrace and get a chart showing what else it ran inside +itself. + +## Installing + +``` +pip install flametrace +``` + +## Usage + +``` +flametrace COMMAND +``` + +## License + +[BSD 3-clause](./LICENSE) \ No newline at end of file diff --git a/doc/_static/trace.svg b/doc/_static/trace.svg new file mode 100644 index 0000000..60d27ae --- /dev/null +++ b/doc/_static/trace.svg @@ -0,0 +1,440 @@ + + + + + + + + + + + + + + +Flame Chart + +Reset Zoom +Search +ic + + + +/workspaces/flametrace/.tox/flake8/bin/python(4634) ['/workspaces/flametrace/.tox/flake8/bin/python', '/workspaces/flametrace/venv/lib/python3.9/site-packages/tox/helper/get_version.py'] (130,777 us, 1.16%) + + + +/usr/bin/lsb_release(4640) ['lsb_release', '-a'] (136,736 us, 1.21%) + + + +/workspaces/flametrace/.tox/flake8/bin/python(4711) ['/workspaces/flametrace/.tox/flake8/bin/python', '/workspaces/flametrace/.tox/flake8/lib/python3.9/site-packages/pip/_vendor/pep517/_in_process.py', 'build_wheel', '/tmp/tmpy2g0_fgd'] (795,223 us, 7.04%) +/workspaces/f.. + + +/usr/bin/lsb_release(4644) ['lsb_release', '-a'] (113,184 us, 1.00%) + + + +/workspaces/flametrace/.tox/flake8/bin/python(4709) ['/workspaces/flametrace/.tox/flake8/bin/python', '/workspaces/flametrace/.tox/flake8/lib/python3.9/site-packages/pip/_vendor/pep517/_in_process.py', 'prepare_metadata_for_build_wheel', '/tmp/tmphgp76vn1'] (663,394 us, 5.88%) +/workspaces.. + + +/workspaces/flametrace/.tox/flake8/bin/flake8(4718) ['/workspaces/flametrace/.tox/flake8/bin/flake8'] (668,608 us, 5.92%) +/workspaces.. + + +/workspaces/flametrace/.tox/flake8/bin/python(4635) ['/workspaces/flametrace/.tox/flake8/bin/python', '-m', 'pip', 'install', '--no-deps', '-U', '.tox/.tmp/package/1/flametrace-0.1.0.zip'] (8,001,314 us, 70.87%) +/workspaces/flametrace/.tox/flake8/bin/python(4635) ['/workspaces/flametrace/.tox/flake8/bin/python', '-m', 'pip', 'install', '--no-deps', '-U', '.tox/.tmp/.. + + +/bin/uname(4645) ['uname', '-rs'] (8,407 us, 0.07%) + + + +/workspaces/flametrace/venv/bin/python(4625) ['/workspaces/flametrace/venv/bin/python', '/workspaces/flametrace/venv/lib/python3.9/site-packages/tox/helper/get_version.py'] (168,884 us, 1.50%) +/.. + + +/workspaces/flametrace/.tox/flake8/bin/python(4716) ['/workspaces/flametrace/.tox/flake8/bin/python', '-m', 'pip', 'freeze'] (793,799 us, 7.03%) +/workspaces/f.. + + +/workspaces/flametrace/.tox/flake8/bin/python(4692) ['/workspaces/flametrace/.tox/flake8/bin/python', '/workspaces/flametrace/.tox/flake8/lib/python3.9/site-packages/pip/_vendor/pep517/_in_process.py', 'get_requires_for_build_wheel', '/tmp/tmpxhv82s5u'] (750,303 us, 6.65%) +/workspaces/.. + + +/bin/uname(4641) ['uname', '-rs'] (9,927 us, 0.09%) + + + +/workspaces/flametrace/venv/bin/tox(4613) ['tox', '-e', 'flake8'] (11,289,400 us, 100.00%) +/workspaces/flametrace/venv/bin/tox(4613) ['tox', '-e', 'flake8'] + + +all (11,289,400 us, 100%) + + + +/workspaces/flametrace/venv/bin/python(4620) ['/workspaces/flametrace/venv/bin/python', 'setup.py', 'sdist', '--formats=zip', '--dist-dir', '.tox/dist'] (954,144 us, 8.45%) +/workspaces/flam.. + + +/workspaces/flametrace/.tox/flake8/bin/python(4642) ['/workspaces/flametrace/.tox/flake8/bin/python', '/workspaces/flametrace/.tox/flake8/lib/python3.9/site-packages/pip', 'install', '--ignore-installed', '--no-user', '--prefix', '/tmp/pip-build-env-a7_a31r6/overlay', '--no-warn-script-location', '--no-binary', ':none:', '--only-binary', ':none:', '-i', 'https://pypi.org/simple', '--', 'setuptools', 'wheel'] (4,147,735 us, 36.74%) +/workspaces/flametrace/.tox/flake8/bin/python(4642) ['/workspaces/flametrace/.t.. + + + diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..4e4fcd0 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,352 @@ +# -*- coding: utf-8 -*- +# +# flametrace documentation build configuration file, created by +# sphinx-quickstart on Thu Apr 6 10:22:33 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import flametrace + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx_click.ext", + "sphinx_rtd_theme", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = [] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "flametrace" +author = "Leif Walsh" + +orig_year = 2021 +years = orig_year +copyright = u"%s Leif Walsh" % years + +rev = flametrace.__version__ +version = ".".join(rev.split(".")[:2]) +release = rev + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = {"collapse_navigation": True, "sticky_navigation": True} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +html_title = u"flametrace documentation" + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = "flametracedoc" + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, + "flametrace.tex", + u"flametrace Documentation", + "Leif Walsh", + "manual", + ), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# +# latex_use_parts = False + +# If true, show page references after internal links. +# +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# If false, no module index is generated. +# +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, "flametrace", u"flametrace Documentation", [author], 1) +] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "flametrace", + u"flametrace Documentation", + author, + "flametrace", + "One line description of project.", + "Miscellaneous", + ), +] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..3ffb8f9 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,49 @@ +.. highlight:: bash + +flametrace +========== + +Build flamegraph_ charts for process trees, based on strace. + +.. _flamegraph: http://www.brendangregg.com/flamegraphs.html + +If you've ever wanted to know why a command is slow, flametrace can help! Run +your command under :command:`flametrace` and get a chart showing what else it +ran inside itself. + +.. contents:: + +Quickstart +---------- + +Using flametrace is easy, just run any command under :command:`flametrace`:: + + $ flametrace tox -e flake8 + ... + Ran "tox -e flake8" in 10.14s + strace: /tmp/tox-20210110_213825_852532.strace + folded: /tmp/tox-20210110_213825_852532.folded + chart: /tmp/tox-20210110_213825_852532.svg + +This will print an svg filename you can open to diagnose your process. + +For example, here is flametrace's output on its own lint process. Use "Right +click > Open image in new tab" to interactively explore the chart. + +.. image:: _static/trace.svg + +Interpretation +-------------- + +The chart produced by flametrace shows you how much process time was spent +running each command, with its ancestors. Since commands might be spawned in +parallel, some commands might appear in the chart to take more time than they +really do. You can click into a child process to expand its children in the +chart. + +CLI +=== + +.. click:: flametrace.main:cli + :prog: flametrace + :show-nested: diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..f2e9a73 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,6 @@ +[build-system] +requires = ["setuptools", "wheel"] +build-backend = "setuptools.build_meta:__legacy__" + +[tool.black] +line-length = 79 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..2b10048 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,7 @@ +click +tox +sphinx +sphinx_click +sphinx_rtd_theme +rstcheck +snooty \ No newline at end of file diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..6d384e9 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,30 @@ +[metadata] +name = flametrace +version = attr: flametrace.__version__ +description = Build flamegraph charts for process trees, based on strace. +long_description = file: README.md, LICENSE +license = BSD 3-Clause License +classifiers = + License :: OSI Approved :: BSD License + Programming Language :: Python :: 3 + Development Status :: 4 - Beta + Operating System :: POSIX :: Linux + Topic :: System :: Benchmark + +[options] +package_dir= + =src +packages=find: +include_package_data = True +install_requires = + click + +[options.packages.find] +where=src + +[options.package_data] +flametrace = perl/flamegraph.pl + +[options.entry_points] +console_scripts= + flametrace = flametrace.main:cli \ No newline at end of file diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..4158613 --- /dev/null +++ b/setup.py @@ -0,0 +1,31 @@ +# Copyright (c) 2021, Leif Walsh +# All Rights Reserved +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of the nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY +# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. + +from setuptools import setup + + +if __name__ == "__main__": + setup() diff --git a/src/flametrace/__init__.py b/src/flametrace/__init__.py new file mode 100644 index 0000000..bbc0b81 --- /dev/null +++ b/src/flametrace/__init__.py @@ -0,0 +1,27 @@ +# Copyright (c) 2021, Leif Walsh +# All Rights Reserved +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of the nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY +# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. + +__version__ = "0.1.0" diff --git a/src/flametrace/core.py b/src/flametrace/core.py new file mode 100644 index 0000000..3dcec52 --- /dev/null +++ b/src/flametrace/core.py @@ -0,0 +1,333 @@ +# Copyright (c) 2021, Leif Walsh +# All Rights Reserved +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of the nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY +# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. + +"""Process strace output for flamegraph.""" + +from collections import defaultdict, namedtuple +import copy +from datetime import datetime, timedelta +import sys + + +Call = namedtuple("Call", "pid ts func args retcode status elapsed") + + +class StraceParser(object): + """Parse strace output into Call objects.""" + + def __init__(self): # noqa: D107 + self.pending = {} + + def parse_call(self, call): + """Parse a single line of strace output.""" + if call.startswith("+++ exited with "): + retcode = int(call[len("+++ exited with ") :].split()[0]) + return "atexit", None, retcode, None, None + elif call.startswith("--- "): + rest = call[len("--- ") :] + signal, rest = rest.split(" ", 1) + assert rest.endswith(" ---") + return "interrupt", signal, rest[:-4], None, None + else: + call, rest = call.rsplit(" = ", 1) + rest = rest.split(" ", 1) + try: + retcode = int(rest[0]) + except ValueError: + retcode = rest[0] + if len(rest) > 1: + rest = rest[1].rsplit(" ", 1) + if len(rest) > 1: + status, elapsed = rest + else: + status = None + elapsed = rest[0] + assert elapsed.startswith("<") + assert elapsed.endswith(">") + elapsed = timedelta(seconds=float(elapsed[1:-1])) + else: + status = None + elapsed = timedelta(0) + func = call.split("(")[0] + args = call[len(func) + 1 :].rsplit(")", 1)[0] + return func, args, retcode, status, elapsed + + def parse_line(self, line): + """Parse a line of strace output, collapsing "unfinished" traces.""" + s = line.split(None, 2) + pid = int(s[0]) + ts = datetime.utcfromtimestamp(float(s[1])) + if s[2].endswith(" "): + assert pid not in self.pending + self.pending[pid] = s[2][: -len(" ")] + elif s[2].startswith("<... "): + to_parse = self.pending.pop(pid) + rest = s[2][len("<... ") :] + expect_func, rest = rest.split(" ", 1) + assert rest.startswith("resumed>") + rest = rest[len("resumed>") :] + rest = rest.lstrip() + to_parse += rest + func, args, retcode, status, elapsed = self.parse_call(to_parse) + assert func == expect_func + return Call( + pid=pid, + ts=ts, + func=func, + args=args, + retcode=retcode, + status=status, + elapsed=elapsed, + ) + else: + func, args, retcode, status, elapsed = self.parse_call(s[2]) + return Call( + pid=pid, + ts=ts, + func=func, + args=args, + retcode=retcode, + status=status, + elapsed=elapsed, + ) + + def parse(self, f): + """Parse a file containing strace output.""" + for line in f: + result = self.parse_line(line.strip()) + if result is not None: + yield result + + +class SyscallCounter(object): + """Measure the time spent during a counted number of syscalls.""" + + def __init__(self): # noqa: D107 + self.calls = 0 + self.elapsed = timedelta(0) + + def __add__(self, other): # noqa: D105 + self.calls += 1 + self.elapsed += other + + +class Process(object): + """Representation of a process. + + This class is tightly coupled with Collapser, which manipulates it + and adds new fields as it processes. + + """ + + def __init__(self, pid, parent, begin): # noqa: D107 + self.args = None + self.pid = pid + self.parent = parent + self.begin = begin + self.end = None + self.child_samples = timedelta(0) + if parent is not None: + # Attribute any of a child's syscalls to its parent. + self.syscalls = parent.syscalls + else: + self.syscalls = defaultdict(SyscallCounter) + + def execve(self, args, ts): + """When a process execs, detach it from the parent. + + Consider this a new process on its own, with its own syscall + tracking. + + Returns the Process entry for the process that led up to this + exec, for tracking. + + """ + oldproc = copy.copy(self) + oldproc.end = ts + self.begin = ts + self.end = None + self.args = args + self.child_samples = timedelta(0) + self.syscalls = defaultdict(SyscallCounter) + return oldproc + + @property + def elapsed(self): # noqa: D102 + end = self.end if self.end is not None else datetime.now() + sumcalls = sum( + (counter.elapsed for counter in self.syscalls.values()), + timedelta(0), + ) + return (end - self.begin) - self.child_samples - sumcalls + + def __str__(self): # noqa: D105 + if self.parent is not None: + s = str(self.parent) + else: + s = "" + # Many processes (like /bin/bash) aren't interesting just by process + # name, so we include some information about its args in its frame. + if self.args is not None: + arg0, argv = self.args.split(",", 1) + arg0 = eval(arg0) + argv = argv.lstrip() + if argv.startswith("["): + # argv is a list, let's try to process it like one. + argv = argv[: argv.rindex("]") + 1] + if argv[-4:] == "...]": + # Last argument truncated, let's make this eval-able. + argv = argv[:-4] + ', "..."]' + try: + argv = eval(argv) + except Exception: + # Couldn't eval, just take some content to identify it. + argv = argv[:32] + # Must replace semicolons with something (since they're + # flamegraph's separator), may as well choose 'z'. + me = f"{arg0}({self.pid}) {argv}".replace(";", "z") + if s: + return s + ";" + me + else: + return me + else: + return s + + +class Collapser(object): + """Collapse strace output calls into a flamegraph input. + + Our strace handling records process begin and end times, but + flamegraph understands "samples", as if we had sampled the stack + and had a number of observations. We approximate the sampling input + by recording an output row for each unique stack we saw, and + pretend we saw one sample per millisecond while it was executing. + + This explains why we remove the "self time" a child process records + from its parent's total time recorded. + + """ + + SYSCALLS = ( + "open", + "openat", + "link", + "unlink", + "unlinkat", + "getcwd", + "chdir", + "mkdir", + "access", + "faccessat", + "lstat", + "stat", + "newfstatat", + "statfs", + "readlink", + "mount", + "read", + "write", + "connect", + "socket", + "bind", + "setsockopt", + "getsockopt", + "getsockname", + "getpeername", + "sendmmsg", + "recvmsg", + "recvfrom", + "sendto", + ) + + def __init__(self): # noqa: D107 + self.pmap = {} + self.finished = [] + + def process(self, pid): + """Get a Process if we know about it.""" + return self.pmap.get(pid) + + def record_finished(self, proc): + """Account for a process which is done.""" + if proc.args is None: + # Processes without their own args are still threads in their + # parent thread group, we can skip counting them, since their + # syscalls are attributed to their parent and their elapsed time + # is too. + return + selftime = proc.elapsed + current = proc.parent + while current is not None: + current.child_samples += selftime + current = current.parent + self.finished.append(proc) + + def handle_call(self, call): + """Consume strace calls into the process map.""" + if call.func == "clone": + # We've seen a process get created, and assume we'll see it + # exec something later (in execve). + self.pmap[call.retcode] = Process( + call.retcode, self.process(call.pid), call.ts + ) + elif call.func == "execve": + if call.retcode != 0: + # Ignore failed execs + return + proc = self.process(call.pid) + if proc is None: + # The first process in the tree won't have been cloned + # from anything, so create one to hold its information. + proc = self.pmap[call.pid] = Process(call.pid, None, call.ts) + proc.args = call.args + else: + oldproc = proc.execve(call.args, call.ts) + self.record_finished(oldproc) + elif call.func == "atexit": + # When a process exits, record the time it consumed, and + # subtract that self time from its parent processes to avoid + # double-counting samples. + proc = self.pmap.pop(call.pid) + proc.retcode = call.retcode + proc.end = call.ts + self.record_finished(proc) + elif call.func in self.SYSCALLS: + if call.func == "read" and call.args[1:7] == " nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY +# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. + +"""Render a flamegraph based on stracing a process tree.""" + +from datetime import datetime +import functools +import os +import os.path +import pkg_resources +import shlex +import subprocess +import sys +import tempfile +import time + +import click + +from . import core + + +FLAMEGRAPH = pkg_resources.resource_filename( + "flametrace", "perl/flamegraph.pl" +) +STRACE = "strace" + + +@functools.lru_cache() +def _strace_version(): + output = subprocess.check_output([STRACE, "-V"], text=True) + line = next(iter(output.splitlines())) + return pkg_resources.parse_version(line.split()[-1]) + + +def _run_strace(mode, argv, output): + version = _strace_version() + modes = { + "process": "trace=%process", + "io": "trace=%process,%network,%file,read,write", + } + + strace_args = [] + if version >= pkg_resources.parse_version("5.3"): + strace_args.append("--seccomp-bpf") + strace_args.extend( + [ + "-tttyfT", + "-e", + modes[mode], + "-s", + "128", + "-o", + output, + ] + ) + return subprocess.call([STRACE, *strace_args, "--", *argv]) + + +def _collapse_stacks(strace_output, folded_output): + parser = core.StraceParser() + collapser = core.Collapser() + with open(strace_output, "r") as f: + for call in parser.parse(f): + collapser.handle_call(call) + with open(folded_output, "w") as f: + collapser.render(f) + + +@click.command(context_settings=dict(ignore_unknown_options=True)) +@click.option( + "--output-base", + "output", + help="output basename (OUTPUT.strace, OUTPUT.folded, OUTPUT.svg)", +) +@click.option( + "--flamegraph-options", + help="additional flamegraph options (e.g. --inverted)", +) +@click.option( + "--mode", + type=click.Choice(["process", "io"]), + default="process", + help="what operations to trace (io is slower but more detailed)", +) +@click.argument("command", nargs=-1) +def cli(output, flamegraph_options, mode, command): + """Run a command and render a flamegraph based on its process tree.""" + if not output: + now = datetime.now() + argv0 = os.path.basename(command[0]) + basename = f"{argv0}-{now:%Y%m%d_%H%M%S_%f}" + dest_dir = tempfile.gettempdir() + output = os.path.join(dest_dir, basename) + + strace_output = f"{output}.strace" + folded_output = f"{output}.folded" + svg_output = f"{output}.svg" + + t0 = time.perf_counter() + retcode = _run_strace(mode, command, strace_output) + t1 = time.perf_counter() + + cmd = " ".join(command) + click.echo(f'Ran "{cmd}" in {t1 - t0:.2f}s') + + _collapse_stacks(strace_output, folded_output) + flamegraph_cmd = [ + FLAMEGRAPH, + "--flamechart", + "--countname", + "us", + "--nametype", + "Frame:", + "--colors", + "aqua", + "--width", + "1600", + ] + if flamegraph_options: + flamegraph_cmd.extend(shlex.split(flamegraph_options)) + flamegraph_cmd.append(folded_output) + subprocess.check_call(flamegraph_cmd, stdout=open(svg_output, "w")) + + click.echo(f"strace: {strace_output}") + click.echo(f"folded: {folded_output}") + click.echo(f"chart: {svg_output}") + sys.exit(retcode) diff --git a/src/flametrace/perl/flamegraph.pl b/src/flametrace/perl/flamegraph.pl new file mode 100755 index 0000000..715f965 --- /dev/null +++ b/src/flametrace/perl/flamegraph.pl @@ -0,0 +1,1191 @@ +#!/usr/bin/perl -w +# +# flamegraph.pl flame stack grapher. +# +# This takes stack samples and renders a call graph, allowing hot functions +# and codepaths to be quickly identified. Stack samples can be generated using +# tools such as DTrace, perf, SystemTap, and Instruments. +# +# USAGE: ./flamegraph.pl [options] input.txt > graph.svg +# +# grep funcA input.txt | ./flamegraph.pl [options] > graph.svg +# +# Then open the resulting .svg in a web browser, for interactivity: mouse-over +# frames for info, click to zoom, and ctrl-F to search. +# +# Options are listed in the usage message (--help). +# +# The input is stack frames and sample counts formatted as single lines. Each +# frame in the stack is semicolon separated, with a space and count at the end +# of the line. These can be generated for Linux perf script output using +# stackcollapse-perf.pl, for DTrace using stackcollapse.pl, and for other tools +# using the other stackcollapse programs. Example input: +# +# swapper;start_kernel;rest_init;cpu_idle;default_idle;native_safe_halt 1 +# +# An optional extra column of counts can be provided to generate a differential +# flame graph of the counts, colored red for more, and blue for less. This +# can be useful when using flame graphs for non-regression testing. +# See the header comment in the difffolded.pl program for instructions. +# +# The input functions can optionally have annotations at the end of each +# function name, following a precedent by some tools (Linux perf's _[k]): +# _[k] for kernel +# _[i] for inlined +# _[j] for jit +# _[w] for waker +# Some of the stackcollapse programs support adding these annotations, eg, +# stackcollapse-perf.pl --kernel --jit. They are used merely for colors by +# some palettes, eg, flamegraph.pl --color=java. +# +# The output flame graph shows relative presence of functions in stack samples. +# The ordering on the x-axis has no meaning; since the data is samples, time +# order of events is not known. The order used sorts function names +# alphabetically. +# +# While intended to process stack samples, this can also process stack traces. +# For example, tracing stacks for memory allocation, or resource usage. You +# can use --title to set the title to reflect the content, and --countname +# to change "samples" to "bytes" etc. +# +# There are a few different palettes, selectable using --color. By default, +# the colors are selected at random (except for differentials). Functions +# called "-" will be printed gray, which can be used for stack separators (eg, +# between user and kernel stacks). +# +# HISTORY +# +# This was inspired by Neelakanth Nadgir's excellent function_call_graph.rb +# program, which visualized function entry and return trace events. As Neel +# wrote: "The output displayed is inspired by Roch's CallStackAnalyzer which +# was in turn inspired by the work on vftrace by Jan Boerhout". See: +# https://blogs.oracle.com/realneel/entry/visualizing_callstacks_via_dtrace_and +# +# Copyright 2016 Netflix, Inc. +# Copyright 2011 Joyent, Inc. All rights reserved. +# Copyright 2011 Brendan Gregg. All rights reserved. +# +# CDDL HEADER START +# +# The contents of this file are subject to the terms of the +# Common Development and Distribution License (the "License"). +# You may not use this file except in compliance with the License. +# +# You can obtain a copy of the license at docs/cddl1.txt or +# http://opensource.org/licenses/CDDL-1.0. +# See the License for the specific language governing permissions +# and limitations under the License. +# +# When distributing Covered Code, include this CDDL HEADER in each +# file and include the License file at docs/cddl1.txt. +# If applicable, add the following below this CDDL HEADER, with the +# fields enclosed by brackets "[]" replaced with your own identifying +# information: Portions Copyright [yyyy] [name of copyright owner] +# +# CDDL HEADER END +# +# 11-Oct-2014 Adrien Mahieux Added zoom. +# 21-Nov-2013 Shawn Sterling Added consistent palette file option +# 17-Mar-2013 Tim Bunce Added options and more tunables. +# 15-Dec-2011 Dave Pacheco Support for frames with whitespace. +# 10-Sep-2011 Brendan Gregg Created this. + +use strict; + +use Getopt::Long; + +use open qw(:std :utf8); + +# tunables +my $encoding; +my $fonttype = "Verdana"; +my $imagewidth = 1200; # max width, pixels +my $frameheight = 16; # max height is dynamic +my $fontsize = 12; # base text size +my $fontwidth = 0.59; # avg width relative to fontsize +my $minwidth = 0.1; # min function width, pixels +my $nametype = "Function:"; # what are the names in the data? +my $countname = "samples"; # what are the counts in the data? +my $colors = "hot"; # color theme +my $bgcolors = ""; # background color theme +my $nameattrfile; # file holding function attributes +my $timemax; # (override the) sum of the counts +my $factor = 1; # factor to scale counts by +my $hash = 0; # color by function name +my $palette = 0; # if we use consistent palettes (default off) +my %palette_map; # palette map hash +my $pal_file = "palette.map"; # palette map file name +my $stackreverse = 0; # reverse stack order, switching merge end +my $inverted = 0; # icicle graph +my $flamechart = 0; # produce a flame chart (sort by time, do not merge stacks) +my $negate = 0; # switch differential hues +my $titletext = ""; # centered heading +my $titledefault = "Flame Graph"; # overwritten by --title +my $titleinverted = "Icicle Graph"; # " " +my $searchcolor = "rgb(230,0,230)"; # color for search highlighting +my $notestext = ""; # embedded notes in SVG +my $subtitletext = ""; # second level title (optional) +my $help = 0; + +sub usage { + die < outfile.svg\n + --title TEXT # change title text + --subtitle TEXT # second level title (optional) + --width NUM # width of image (default 1200) + --height NUM # height of each frame (default 16) + --minwidth NUM # omit smaller functions (default 0.1 pixels) + --fonttype FONT # font type (default "Verdana") + --fontsize NUM # font size (default 12) + --countname TEXT # count type label (default "samples") + --nametype TEXT # name type label (default "Function:") + --colors PALETTE # set color palette. choices are: hot (default), mem, + # io, wakeup, chain, java, js, perl, red, green, blue, + # aqua, yellow, purple, orange + --bgcolors COLOR # set background colors. gradient choices are yellow + # (default), blue, green, grey; flat colors use "#rrggbb" + --hash # colors are keyed by function name hash + --cp # use consistent palette (palette.map) + --reverse # generate stack-reversed flame graph + --inverted # icicle graph + --flamechart # produce a flame chart (sort by time, do not merge stacks) + --negate # switch differential hues (blue<->red) + --notes TEXT # add notes comment in SVG (for debugging) + --help # this message + + eg, + $0 --title="Flame Graph: malloc()" trace.txt > graph.svg +USAGE_END +} + +GetOptions( + 'fonttype=s' => \$fonttype, + 'width=i' => \$imagewidth, + 'height=i' => \$frameheight, + 'encoding=s' => \$encoding, + 'fontsize=f' => \$fontsize, + 'fontwidth=f' => \$fontwidth, + 'minwidth=f' => \$minwidth, + 'title=s' => \$titletext, + 'subtitle=s' => \$subtitletext, + 'nametype=s' => \$nametype, + 'countname=s' => \$countname, + 'nameattr=s' => \$nameattrfile, + 'total=s' => \$timemax, + 'factor=f' => \$factor, + 'colors=s' => \$colors, + 'bgcolors=s' => \$bgcolors, + 'hash' => \$hash, + 'cp' => \$palette, + 'reverse' => \$stackreverse, + 'inverted' => \$inverted, + 'flamechart' => \$flamechart, + 'negate' => \$negate, + 'notes=s' => \$notestext, + 'help' => \$help, +) or usage(); +$help && usage(); + +# internals +my $ypad1 = $fontsize * 3; # pad top, include title +my $ypad2 = $fontsize * 2 + 10; # pad bottom, include labels +my $ypad3 = $fontsize * 2; # pad top, include subtitle (optional) +my $xpad = 10; # pad lefm and right +my $framepad = 1; # vertical padding for frames +my $depthmax = 0; +my %Events; +my %nameattr; + +if ($flamechart && $titletext eq "") { + $titletext = "Flame Chart"; +} + +if ($titletext eq "") { + unless ($inverted) { + $titletext = $titledefault; + } else { + $titletext = $titleinverted; + } +} + +if ($nameattrfile) { + # The name-attribute file format is a function name followed by a tab then + # a sequence of tab separated name=value pairs. + open my $attrfh, $nameattrfile or die "Can't read $nameattrfile: $!\n"; + while (<$attrfh>) { + chomp; + my ($funcname, $attrstr) = split /\t/, $_, 2; + die "Invalid format in $nameattrfile" unless defined $attrstr; + $nameattr{$funcname} = { map { split /=/, $_, 2 } split /\t/, $attrstr }; + } +} + +if ($notestext =~ /[<>]/) { + die "Notes string can't contain < or >" +} + +# background colors: +# - yellow gradient: default (hot, java, js, perl) +# - green gradient: mem +# - blue gradient: io, wakeup, chain +# - gray gradient: flat colors (red, green, blue, ...) +if ($bgcolors eq "") { + # choose a default + if ($colors eq "mem") { + $bgcolors = "green"; + } elsif ($colors =~ /^(io|wakeup|chain)$/) { + $bgcolors = "blue"; + } elsif ($colors =~ /^(red|green|blue|aqua|yellow|purple|orange)$/) { + $bgcolors = "grey"; + } else { + $bgcolors = "yellow"; + } +} +my ($bgcolor1, $bgcolor2); +if ($bgcolors eq "yellow") { + $bgcolor1 = "#eeeeee"; # background color gradient start + $bgcolor2 = "#eeeeb0"; # background color gradient stop +} elsif ($bgcolors eq "blue") { + $bgcolor1 = "#eeeeee"; $bgcolor2 = "#e0e0ff"; +} elsif ($bgcolors eq "green") { + $bgcolor1 = "#eef2ee"; $bgcolor2 = "#e0ffe0"; +} elsif ($bgcolors eq "grey") { + $bgcolor1 = "#f8f8f8"; $bgcolor2 = "#e8e8e8"; +} elsif ($bgcolors =~ /^#......$/) { + $bgcolor1 = $bgcolor2 = $bgcolors; +} else { + die "Unrecognized bgcolor option \"$bgcolors\"" +} + +# SVG functions +{ package SVG; + sub new { + my $class = shift; + my $self = {}; + bless ($self, $class); + return $self; + } + + sub header { + my ($self, $w, $h) = @_; + my $enc_attr = ''; + if (defined $encoding) { + $enc_attr = qq{ encoding="$encoding"}; + } + $self->{svg} .= < + + + + +SVG + } + + sub include { + my ($self, $content) = @_; + $self->{svg} .= $content; + } + + sub colorAllocate { + my ($self, $r, $g, $b) = @_; + return "rgb($r,$g,$b)"; + } + + sub group_start { + my ($self, $attr) = @_; + + my @g_attr = map { + exists $attr->{$_} ? sprintf(qq/$_="%s"/, $attr->{$_}) : () + } qw(id class); + push @g_attr, $attr->{g_extra} if $attr->{g_extra}; + if ($attr->{href}) { + my @a_attr; + push @a_attr, sprintf qq/xlink:href="%s"/, $attr->{href} if $attr->{href}; + # default target=_top else links will open within SVG + push @a_attr, sprintf qq/target="%s"/, $attr->{target} || "_top"; + push @a_attr, $attr->{a_extra} if $attr->{a_extra}; + $self->{svg} .= sprintf qq/\n/, join(' ', (@a_attr, @g_attr)); + } else { + $self->{svg} .= sprintf qq/\n/, join(' ', @g_attr); + } + + $self->{svg} .= sprintf qq/%s<\/title>/, $attr->{title} + if $attr->{title}; # should be first element within g container + } + + sub group_end { + my ($self, $attr) = @_; + $self->{svg} .= $attr->{href} ? qq/<\/a>\n/ : qq/<\/g>\n/; + } + + sub filledRectangle { + my ($self, $x1, $y1, $x2, $y2, $fill, $extra) = @_; + $x1 = sprintf "%0.1f", $x1; + $x2 = sprintf "%0.1f", $x2; + my $w = sprintf "%0.1f", $x2 - $x1; + my $h = sprintf "%0.1f", $y2 - $y1; + $extra = defined $extra ? $extra : ""; + $self->{svg} .= qq/\n/; + } + + sub stringTTF { + my ($self, $id, $x, $y, $str, $extra) = @_; + $x = sprintf "%0.2f", $x; + $id = defined $id ? qq/id="$id"/ : ""; + $extra ||= ""; + $self->{svg} .= qq/$str<\/text>\n/; + } + + sub svg { + my $self = shift; + return "$self->{svg}\n"; + } + 1; +} + +sub namehash { + # Generate a vector hash for the name string, weighting early over + # later characters. We want to pick the same colors for function + # names across different flame graphs. + my $name = shift; + my $vector = 0; + my $weight = 1; + my $max = 1; + my $mod = 10; + # if module name present, trunc to 1st char + $name =~ s/.(.*?)`//; + foreach my $c (split //, $name) { + my $i = (ord $c) % $mod; + $vector += ($i / ($mod++ - 1)) * $weight; + $max += 1 * $weight; + $weight *= 0.70; + last if $mod > 12; + } + return (1 - $vector / $max) +} + +sub color { + my ($type, $hash, $name) = @_; + my ($v1, $v2, $v3); + + if ($hash) { + $v1 = namehash($name); + $v2 = $v3 = namehash(scalar reverse $name); + } else { + $v1 = rand(1); + $v2 = rand(1); + $v3 = rand(1); + } + + # theme palettes + if (defined $type and $type eq "hot") { + my $r = 205 + int(50 * $v3); + my $g = 0 + int(230 * $v1); + my $b = 0 + int(55 * $v2); + return "rgb($r,$g,$b)"; + } + if (defined $type and $type eq "mem") { + my $r = 0; + my $g = 190 + int(50 * $v2); + my $b = 0 + int(210 * $v1); + return "rgb($r,$g,$b)"; + } + if (defined $type and $type eq "io") { + my $r = 80 + int(60 * $v1); + my $g = $r; + my $b = 190 + int(55 * $v2); + return "rgb($r,$g,$b)"; + } + + # multi palettes + if (defined $type and $type eq "java") { + # Handle both annotations (_[j], _[i], ...; which are + # accurate), as well as input that lacks any annotations, as + # best as possible. Without annotations, we get a little hacky + # and match on java|org|com, etc. + if ($name =~ m:_\[j\]$:) { # jit annotation + $type = "green"; + } elsif ($name =~ m:_\[i\]$:) { # inline annotation + $type = "aqua"; + } elsif ($name =~ m:^L?(java|javax|jdk|net|org|com|io|sun)/:) { # Java + $type = "green"; + } elsif ($name =~ m:_\[k\]$:) { # kernel annotation + $type = "orange"; + } elsif ($name =~ /::/) { # C++ + $type = "yellow"; + } else { # system + $type = "red"; + } + # fall-through to color palettes + } + if (defined $type and $type eq "perl") { + if ($name =~ /::/) { # C++ + $type = "yellow"; + } elsif ($name =~ m:Perl: or $name =~ m:\.pl:) { # Perl + $type = "green"; + } elsif ($name =~ m:_\[k\]$:) { # kernel + $type = "orange"; + } else { # system + $type = "red"; + } + # fall-through to color palettes + } + if (defined $type and $type eq "js") { + # Handle both annotations (_[j], _[i], ...; which are + # accurate), as well as input that lacks any annotations, as + # best as possible. Without annotations, we get a little hacky, + # and match on a "/" with a ".js", etc. + if ($name =~ m:_\[j\]$:) { # jit annotation + if ($name =~ m:/:) { + $type = "green"; # source + } else { + $type = "aqua"; # builtin + } + } elsif ($name =~ /::/) { # C++ + $type = "yellow"; + } elsif ($name =~ m:/.*\.js:) { # JavaScript (match "/" in path) + $type = "green"; + } elsif ($name =~ m/:/) { # JavaScript (match ":" in builtin) + $type = "aqua"; + } elsif ($name =~ m/^ $/) { # Missing symbol + $type = "green"; + } elsif ($name =~ m:_\[k\]:) { # kernel + $type = "orange"; + } else { # system + $type = "red"; + } + # fall-through to color palettes + } + if (defined $type and $type eq "wakeup") { + $type = "aqua"; + # fall-through to color palettes + } + if (defined $type and $type eq "chain") { + if ($name =~ m:_\[w\]:) { # waker + $type = "aqua" + } else { # off-CPU + $type = "blue"; + } + # fall-through to color palettes + } + + # color palettes + if (defined $type and $type eq "red") { + my $r = 200 + int(55 * $v1); + my $x = 50 + int(80 * $v1); + return "rgb($r,$x,$x)"; + } + if (defined $type and $type eq "green") { + my $g = 200 + int(55 * $v1); + my $x = 50 + int(60 * $v1); + return "rgb($x,$g,$x)"; + } + if (defined $type and $type eq "blue") { + my $b = 205 + int(50 * $v1); + my $x = 80 + int(60 * $v1); + return "rgb($x,$x,$b)"; + } + if (defined $type and $type eq "yellow") { + my $x = 175 + int(55 * $v1); + my $b = 50 + int(20 * $v1); + return "rgb($x,$x,$b)"; + } + if (defined $type and $type eq "purple") { + my $x = 190 + int(65 * $v1); + my $g = 80 + int(60 * $v1); + return "rgb($x,$g,$x)"; + } + if (defined $type and $type eq "aqua") { + my $r = 50 + int(60 * $v1); + my $g = 165 + int(55 * $v1); + my $b = 165 + int(55 * $v1); + return "rgb($r,$g,$b)"; + } + if (defined $type and $type eq "orange") { + my $r = 190 + int(65 * $v1); + my $g = 90 + int(65 * $v1); + return "rgb($r,$g,0)"; + } + + return "rgb(0,0,0)"; +} + +sub color_scale { + my ($value, $max) = @_; + my ($r, $g, $b) = (255, 255, 255); + $value = -$value if $negate; + if ($value > 0) { + $g = $b = int(210 * ($max - $value) / $max); + } elsif ($value < 0) { + $r = $g = int(210 * ($max + $value) / $max); + } + return "rgb($r,$g,$b)"; +} + +sub color_map { + my ($colors, $func) = @_; + if (exists $palette_map{$func}) { + return $palette_map{$func}; + } else { + $palette_map{$func} = color($colors, $hash, $func); + return $palette_map{$func}; + } +} + +sub write_palette { + open(FILE, ">$pal_file"); + foreach my $key (sort keys %palette_map) { + print FILE $key."->".$palette_map{$key}."\n"; + } + close(FILE); +} + +sub read_palette { + if (-e $pal_file) { + open(FILE, $pal_file) or die "can't open file $pal_file: $!"; + while ( my $line = ) { + chomp($line); + (my $key, my $value) = split("->",$line); + $palette_map{$key}=$value; + } + close(FILE) + } +} + +my %Node; # Hash of merged frame data +my %Tmp; + +# flow() merges two stacks, storing the merged frames and value data in %Node. +sub flow { + my ($last, $this, $v, $d) = @_; + + my $len_a = @$last - 1; + my $len_b = @$this - 1; + + my $i = 0; + my $len_same; + for (; $i <= $len_a; $i++) { + last if $i > $len_b; + last if $last->[$i] ne $this->[$i]; + } + $len_same = $i; + + for ($i = $len_a; $i >= $len_same; $i--) { + my $k = "$last->[$i];$i"; + # a unique ID is constructed from "func;depth;etime"; + # func-depth isn't unique, it may be repeated later. + $Node{"$k;$v"}->{stime} = delete $Tmp{$k}->{stime}; + if (defined $Tmp{$k}->{delta}) { + $Node{"$k;$v"}->{delta} = delete $Tmp{$k}->{delta}; + } + delete $Tmp{$k}; + } + + for ($i = $len_same; $i <= $len_b; $i++) { + my $k = "$this->[$i];$i"; + $Tmp{$k}->{stime} = $v; + if (defined $d) { + $Tmp{$k}->{delta} += $i == $len_b ? $d : 0; + } + } + + return $this; +} + +# parse input +my @Data; +my @SortedData; +my $last = []; +my $time = 0; +my $delta = undef; +my $ignored = 0; +my $line; +my $maxdelta = 1; + +# reverse if needed +foreach (<>) { + chomp; + $line = $_; + if ($stackreverse) { + # there may be an extra samples column for differentials + # XXX todo: redo these REs as one. It's repeated below. + my($stack, $samples) = (/^(.*)\s+?(\d+(?:\.\d*)?)$/); + my $samples2 = undef; + if ($stack =~ /^(.*)\s+?(\d+(?:\.\d*)?)$/) { + $samples2 = $samples; + ($stack, $samples) = $stack =~ (/^(.*)\s+?(\d+(?:\.\d*)?)$/); + unshift @Data, join(";", reverse split(";", $stack)) . " $samples $samples2"; + } else { + unshift @Data, join(";", reverse split(";", $stack)) . " $samples"; + } + } else { + unshift @Data, $line; + } +} + +if ($flamechart) { + # In flame chart mode, just reverse the data so time moves from left to right. + @SortedData = reverse @Data; +} else { + @SortedData = sort @Data; +} + +# process and merge frames +foreach (@SortedData) { + chomp; + # process: folded_stack count + # eg: func_a;func_b;func_c 31 + my ($stack, $samples) = (/^(.*)\s+?(\d+(?:\.\d*)?)$/); + unless (defined $samples and defined $stack) { + ++$ignored; + next; + } + + # there may be an extra samples column for differentials: + my $samples2 = undef; + if ($stack =~ /^(.*)\s+?(\d+(?:\.\d*)?)$/) { + $samples2 = $samples; + ($stack, $samples) = $stack =~ (/^(.*)\s+?(\d+(?:\.\d*)?)$/); + } + $delta = undef; + if (defined $samples2) { + $delta = $samples2 - $samples; + $maxdelta = abs($delta) if abs($delta) > $maxdelta; + } + + # for chain graphs, annotate waker frames with "_[w]", for later + # coloring. This is a hack, but has a precedent ("_[k]" from perf). + if ($colors eq "chain") { + my @parts = split ";--;", $stack; + my @newparts = (); + $stack = shift @parts; + $stack .= ";--;"; + foreach my $part (@parts) { + $part =~ s/;/_[w];/g; + $part .= "_[w]"; + push @newparts, $part; + } + $stack .= join ";--;", @parts; + } + + # merge frames and populate %Node: + $last = flow($last, [ '', split ";", $stack ], $time, $delta); + + if (defined $samples2) { + $time += $samples2; + } else { + $time += $samples; + } +} +flow($last, [], $time, $delta); + +warn "Ignored $ignored lines with invalid format\n" if $ignored; +unless ($time) { + warn "ERROR: No stack counts found\n"; + my $im = SVG->new(); + # emit an error message SVG, for tools automating flamegraph use + my $imageheight = $fontsize * 5; + $im->header($imagewidth, $imageheight); + $im->stringTTF(undef, int($imagewidth / 2), $fontsize * 2, + "ERROR: No valid input provided to flamegraph.pl."); + print $im->svg; + exit 2; +} +if ($timemax and $timemax < $time) { + warn "Specified --total $timemax is less than actual total $time, so ignored\n" + if $timemax/$time > 0.02; # only warn is significant (e.g., not rounding etc) + undef $timemax; +} +$timemax ||= $time; + +my $widthpertime = ($imagewidth - 2 * $xpad) / $timemax; +my $minwidth_time = $minwidth / $widthpertime; + +# prune blocks that are too narrow and determine max depth +while (my ($id, $node) = each %Node) { + my ($func, $depth, $etime) = split ";", $id; + my $stime = $node->{stime}; + die "missing start for $id" if not defined $stime; + + if (($etime-$stime) < $minwidth_time) { + delete $Node{$id}; + next; + } + $depthmax = $depth if $depth > $depthmax; +} + +# draw canvas, and embed interactive JavaScript program +my $imageheight = (($depthmax + 1) * $frameheight) + $ypad1 + $ypad2; +$imageheight += $ypad3 if $subtitletext ne ""; +my $titlesize = $fontsize + 5; +my $im = SVG->new(); +my ($black, $vdgrey, $dgrey) = ( + $im->colorAllocate(0, 0, 0), + $im->colorAllocate(160, 160, 160), + $im->colorAllocate(200, 200, 200), + ); +$im->header($imagewidth, $imageheight); +my $inc = < + + + + + + + +INC +$im->include($inc); +$im->filledRectangle(0, 0, $imagewidth, $imageheight, 'url(#background)'); +$im->stringTTF("title", int($imagewidth / 2), $fontsize * 2, $titletext); +$im->stringTTF("subtitle", int($imagewidth / 2), $fontsize * 4, $subtitletext) if $subtitletext ne ""; +$im->stringTTF("details", $xpad, $imageheight - ($ypad2 / 2), " "); +$im->stringTTF("unzoom", $xpad, $fontsize * 2, "Reset Zoom", 'class="hide"'); +$im->stringTTF("search", $imagewidth - $xpad - 100, $fontsize * 2, "Search"); +$im->stringTTF("ignorecase", $imagewidth - $xpad - 16, $fontsize * 2, "ic"); +$im->stringTTF("matched", $imagewidth - $xpad - 100, $imageheight - ($ypad2 / 2), " "); + +if ($palette) { + read_palette(); +} + +# draw frames +$im->group_start({id => "frames"}); +while (my ($id, $node) = each %Node) { + my ($func, $depth, $etime) = split ";", $id; + my $stime = $node->{stime}; + my $delta = $node->{delta}; + + $etime = $timemax if $func eq "" and $depth == 0; + + my $x1 = $xpad + $stime * $widthpertime; + my $x2 = $xpad + $etime * $widthpertime; + my ($y1, $y2); + unless ($inverted) { + $y1 = $imageheight - $ypad2 - ($depth + 1) * $frameheight + $framepad; + $y2 = $imageheight - $ypad2 - $depth * $frameheight; + } else { + $y1 = $ypad1 + $depth * $frameheight; + $y2 = $ypad1 + ($depth + 1) * $frameheight - $framepad; + } + + my $samples = sprintf "%.0f", ($etime - $stime) * $factor; + (my $samples_txt = $samples) # add commas per perlfaq5 + =~ s/(^[-+]?\d+?(?=(?>(?:\d{3})+)(?!\d))|\G\d{3}(?=\d))/$1,/g; + + my $info; + if ($func eq "" and $depth == 0) { + $info = "all ($samples_txt $countname, 100%)"; + } else { + my $pct = sprintf "%.2f", ((100 * $samples) / ($timemax * $factor)); + my $escaped_func = $func; + # clean up SVG breaking characters: + $escaped_func =~ s/&/&/g; + $escaped_func =~ s//>/g; + $escaped_func =~ s/"/"/g; + $escaped_func =~ s/_\[[kwij]\]$//; # strip any annotation + unless (defined $delta) { + $info = "$escaped_func ($samples_txt $countname, $pct%)"; + } else { + my $d = $negate ? -$delta : $delta; + my $deltapct = sprintf "%.2f", ((100 * $d) / ($timemax * $factor)); + $deltapct = $d > 0 ? "+$deltapct" : $deltapct; + $info = "$escaped_func ($samples_txt $countname, $pct%; $deltapct%)"; + } + } + + my $nameattr = { %{ $nameattr{$func}||{} } }; # shallow clone + $nameattr->{title} ||= $info; + $im->group_start($nameattr); + + my $color; + if ($func eq "--") { + $color = $vdgrey; + } elsif ($func eq "-") { + $color = $dgrey; + } elsif (defined $delta) { + $color = color_scale($delta, $maxdelta); + } elsif ($palette) { + $color = color_map($colors, $func); + } else { + $color = color($colors, $hash, $func); + } + $im->filledRectangle($x1, $y1, $x2, $y2, $color, 'rx="2" ry="2"'); + + my $chars = int( ($x2 - $x1) / ($fontsize * $fontwidth)); + my $text = ""; + if ($chars >= 3) { # room for one char plus two dots + $func =~ s/_\[[kwij]\]$//; # strip any annotation + $text = substr $func, 0, $chars; + substr($text, -2, 2) = ".." if $chars < length $func; + $text =~ s/&/&/g; + $text =~ s//>/g; + } + $im->stringTTF(undef, $x1 + 3, 3 + ($y1 + $y2) / 2, $text); + + $im->group_end($nameattr); +} +$im->group_end(); + +print $im->svg; + +if ($palette) { + write_palette(); +} + +# vim: ts=8 sts=8 sw=8 noexpandtab \ No newline at end of file diff --git a/src/tests/__init__.py b/src/tests/__init__.py new file mode 100644 index 0000000..ccefa60 --- /dev/null +++ b/src/tests/__init__.py @@ -0,0 +1,25 @@ +# Copyright (c) 2021, Leif Walsh +# All Rights Reserved +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of the nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY +# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. diff --git a/src/tests/test_flametrace.py b/src/tests/test_flametrace.py new file mode 100644 index 0000000..fe32d58 --- /dev/null +++ b/src/tests/test_flametrace.py @@ -0,0 +1,63 @@ +# Copyright (c) 2021, Leif Walsh +# All Rights Reserved +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of the nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY +# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. + +from pathlib import Path +import subprocess +import tempfile +from unittest import TestCase + + +class FlametraceTestBase(TestCase): + + command = ... + + def setUp(self): + self.tmpdir = tempfile.TemporaryDirectory() + self.out_base = Path(self.tmpdir.name, "trace") + proc = subprocess.run( + ["flametrace", "--output-base", self.out_base, *self.command], + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + text=True, + ) + self.returncode = proc.returncode + self.stdout = proc.stdout + self.stderr = proc.stderr + + def tearDown(self): + self.tmpdir.cleanup() + + +class FlametraceTests(FlametraceTestBase): + + command = ["ls"] + + def test_flametrace(self): + self.assertEqual("", self.stderr) + self.assertIn(f"strace: {self.out_base}.strace", self.stdout) + self.assertIn(f"folded: {self.out_base}.folded", self.stdout) + self.assertIn(f"chart: {self.out_base}.svg", self.stdout) + self.assertEqual(0, self.returncode) diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..c368951 --- /dev/null +++ b/tox.ini @@ -0,0 +1,30 @@ +[tox] +envlist = py37,py38,py39,docs,flake8 + +[testenv] +commands = + python -m unittest discover -v -s src/tests -p test_*.py + +[testenv:docs] +basepython = python3.9 +deps = + sphinx + sphinx_click + sphinx_rtd_theme +commands = + sphinx-build -d "{toxworkdir}/docs_doctree" doc "{toxworkdir}/docs_out" --color -W -bhtml {posargs} + python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))' + +[testenv:flake8] +basepython = python3.9 +deps = + flake8 + pep8-naming +commands = + flake8 + +[gh-actions] +python = + 3.7: py37 + 3.8: py38 + 3.9: py39,docs,flake8 \ No newline at end of file