| Server IP : 121.121.20.254 / Your IP : 216.73.216.202 Web Server : Microsoft-IIS/10.0 System : Windows NT WEB-SERVER 10.0 build 20348 (Windows Server 2022) AMD64 User : IUSR ( 0) PHP Version : 8.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Python315/Doc/html/library/ |
Upload File : |
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="profiling.tracing — Deterministic profiler" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/profiling.tracing.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="Source code: Lib/profiling/tracing/ The profiling.tracing module provides deterministic profiling of Python programs. It monitors every function call, function return, and exception event, recordin..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="Source code: Lib/profiling/tracing/ The profiling.tracing module provides deterministic profiling of Python programs. It monitors every function call, function return, and exception event, recordin..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>profiling.tracing — Deterministic profiler — Python 3.15.0rc1 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=791e38b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0rc1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="profiling.sampling — Statistical profiler" href="profiling.sampling.html" />
<link rel="prev" title="profiling — Python profilers" href="profiling.html" />
<link rel="canonical" href="https://docs.python.org/3/library/profiling.tracing.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> — Deterministic profiler</a><ul>
<li><a class="reference internal" href="#what-is-deterministic-profiling">What is deterministic profiling?</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
<li><a class="reference internal" href="#programmatic-usage-examples">Programmatic usage examples</a><ul>
<li><a class="reference internal" href="#basic-profiling">Basic profiling</a></li>
<li><a class="reference internal" href="#using-the-profile-class">Using the <code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code> class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-reference">Module reference</a></li>
<li><a class="reference internal" href="#using-a-custom-timer">Using a custom timer</a></li>
<li><a class="reference internal" href="#limitations">Limitations</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="profiling.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling</span></code> — Python profilers</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="profiling.sampling.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code> — Statistical profiler</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/profiling.tracing.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/profiling.tracing.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="profiling.sampling.html" title="profiling.sampling — Statistical profiler"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="profiling.html" title="profiling — Python profilers"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="debug.html" >Debugging and profiling</a> »</li>
<li class="nav-item nav-item-3"><a href="profiling.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling</span></code> — Python profilers</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> — Deterministic profiler</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-profiling.tracing">
<span id="profiling-tracing-deterministic-profiler"></span><span id="profiling-tracing"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> — Deterministic profiler<a class="headerlink" href="#module-profiling.tracing" title="Link to this heading">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/profiling/tracing/">Lib/profiling/tracing/</a></p>
<hr class="docutils" />
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> module provides deterministic profiling of Python
programs. It monitors every function call, function return, and exception event,
recording precise timing for each. This approach provides exact call counts and
complete visibility into program execution, making it ideal for development and
testing scenarios.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This module is also available as <code class="docutils literal notranslate"><span class="pre">cProfile</span></code> for backward compatibility.
The <code class="docutils literal notranslate"><span class="pre">cProfile</span></code> name will continue to work in all future Python versions.
Use whichever import style suits your codebase:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Preferred (new style)</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">profiling.tracing</span>
<span class="n">profiling</span><span class="o">.</span><span class="n">tracing</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s1">'my_function()'</span><span class="p">)</span>
<span class="c1"># Also works (backward compatible)</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">cProfile</span>
<span class="n">cProfile</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s1">'my_function()'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<section id="what-is-deterministic-profiling">
<h2>What is deterministic profiling?<a class="headerlink" href="#what-is-deterministic-profiling" title="Link to this heading">¶</a></h2>
<p><em class="dfn">Deterministic profiling</em> captures every function call, function return,
and exception event during program execution. The profiler measures the precise
time intervals between these events, providing exact statistics about how the
program behaves.</p>
<p>In contrast to <a class="reference internal" href="profiling.sampling.html#profiling-sampling"><span class="std std-ref">statistical profiling</span></a>, which samples
the call stack periodically to estimate where time is spent, deterministic
profiling records every event. This means you get exact call counts rather than
statistical approximations. The trade-off is that instrumenting every event
introduces overhead that can slow down program execution.</p>
<p>Python’s interpreted nature makes deterministic profiling practical. The
interpreter already dispatches events for function calls and returns, so the
profiler can hook into this mechanism without requiring code modification. The
overhead tends to be moderate relative to the inherent cost of interpretation,
making deterministic profiling suitable for most development workflows.</p>
<p>Deterministic profiling helps answer questions like:</p>
<ul class="simple">
<li><p>How many times was this function called?</p></li>
<li><p>What is the complete call graph of my program?</p></li>
<li><p>Which functions are called by a particular function?</p></li>
<li><p>Are there unexpected function calls happening?</p></li>
</ul>
<p>Call count statistics can identify bugs (surprising counts) and inline
expansion opportunities (high call counts). Internal time statistics reveal
“hot loops” that warrant optimization. Cumulative time statistics help identify
algorithmic inefficiencies. The handling of cumulative times in this profiler
allows direct comparison of recursive and iterative implementations.</p>
</section>
<section id="command-line-interface">
<span id="profiling-tracing-cli"></span><h2>Command-line interface<a class="headerlink" href="#command-line-interface" title="Link to this heading">¶</a></h2>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> module can be invoked as a script to profile
another script or module:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="go">python -m profiling.tracing [-o output_file] [-s sort_order] (-m module | script.py)</span>
</pre></div>
</div>
<p>This runs the specified script or module under the profiler and prints the
results to standard output (or saves them to a file).</p>
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-profiling.tracing-o">
<span class="sig-name descname"><span class="pre">-o</span></span><span class="sig-prename descclassname"> <span class="pre"><output_file></span></span><a class="headerlink" href="#cmdoption-profiling.tracing-o" title="Link to this definition">¶</a></dt>
<dd><p>Write the profile results to a file instead of standard output. The output
file can be read by the <a class="reference internal" href="pstats.html#module-pstats" title="pstats: Statistics object for analyzing profiler output."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code></a> module for later analysis.</p>
</dd></dl>
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-profiling.tracing-s">
<span class="sig-name descname"><span class="pre">-s</span></span><span class="sig-prename descclassname"> <span class="pre"><sort_order></span></span><a class="headerlink" href="#cmdoption-profiling.tracing-s" title="Link to this definition">¶</a></dt>
<dd><p>Sort the output by the specified key. This accepts any of the sort keys
recognized by <a class="reference internal" href="pstats.html#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pstats.Stats.sort_stats()</span></code></a>, such as <code class="docutils literal notranslate"><span class="pre">cumulative</span></code>,
<code class="docutils literal notranslate"><span class="pre">time</span></code>, <code class="docutils literal notranslate"><span class="pre">calls</span></code>, or <code class="docutils literal notranslate"><span class="pre">name</span></code>. This option only applies when
<a class="reference internal" href="#cmdoption-profiling.tracing-o"><code class="xref std std-option docutils literal notranslate"><span class="pre">-o</span></code></a> is not specified.</p>
</dd></dl>
<dl class="std option">
<dt class="sig sig-object std" id="cmdoption-profiling.tracing-m">
<span class="sig-name descname"><span class="pre">-m</span></span><span class="sig-prename descclassname"> <span class="pre"><module></span></span><a class="headerlink" href="#cmdoption-profiling.tracing-m" title="Link to this definition">¶</a></dt>
<dd><p>Profile a module instead of a script. The module is located using the
standard import mechanism.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7: </span>The <code class="docutils literal notranslate"><span class="pre">-m</span></code> option for <code class="docutils literal notranslate"><span class="pre">cProfile</span></code>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.8: </span>The <code class="docutils literal notranslate"><span class="pre">-m</span></code> option for <a class="reference internal" href="profile.html#module-profile" title="profile: Pure Python profiler (deprecated). (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profile</span></code></a>.</p>
</div>
</dd></dl>
</section>
<section id="programmatic-usage-examples">
<h2>Programmatic usage examples<a class="headerlink" href="#programmatic-usage-examples" title="Link to this heading">¶</a></h2>
<p>For more control over profiling, use the module’s functions and classes
directly.</p>
<section id="basic-profiling">
<h3>Basic profiling<a class="headerlink" href="#basic-profiling" title="Link to this heading">¶</a></h3>
<p>The simplest approach uses the <code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code> function:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">profiling.tracing</span>
<span class="n">profiling</span><span class="o">.</span><span class="n">tracing</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s1">'my_function()'</span><span class="p">)</span>
</pre></div>
</div>
<p>This profiles the given code string and prints a summary to standard output.
To save results for later analysis:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">profiling</span><span class="o">.</span><span class="n">tracing</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s1">'my_function()'</span><span class="p">,</span> <span class="s1">'output.prof'</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="using-the-profile-class">
<h3>Using the <code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code> class<a class="headerlink" href="#using-the-profile-class" title="Link to this heading">¶</a></h3>
<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code> class provides fine-grained control:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">profiling.tracing</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">pstats</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">io</span><span class="w"> </span><span class="kn">import</span> <span class="n">StringIO</span>
<span class="n">pr</span> <span class="o">=</span> <span class="n">profiling</span><span class="o">.</span><span class="n">tracing</span><span class="o">.</span><span class="n">Profile</span><span class="p">()</span>
<span class="n">pr</span><span class="o">.</span><span class="n">enable</span><span class="p">()</span>
<span class="c1"># ... code to profile ...</span>
<span class="n">pr</span><span class="o">.</span><span class="n">disable</span><span class="p">()</span>
<span class="c1"># Print results</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">()</span>
<span class="n">ps</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="n">pr</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="n">s</span><span class="p">)</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">pstats</span><span class="o">.</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span>
<span class="n">ps</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="n">s</span><span class="o">.</span><span class="n">getvalue</span><span class="p">())</span>
</pre></div>
</div>
<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code> class also works as a context manager:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">profiling.tracing</span>
<span class="k">with</span> <span class="n">profiling</span><span class="o">.</span><span class="n">tracing</span><span class="o">.</span><span class="n">Profile</span><span class="p">()</span> <span class="k">as</span> <span class="n">pr</span><span class="p">:</span>
<span class="c1"># ... code to profile ...</span>
<span class="n">pr</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
</pre></div>
</div>
</section>
</section>
<section id="module-reference">
<h2>Module reference<a class="headerlink" href="#module-reference" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="profiling.tracing.run">
<span class="sig-prename descclassname"><span class="pre">profiling.tracing.</span></span><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">command</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sort</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.run" title="Link to this definition">¶</a></dt>
<dd><p>Profile execution of a command and print or save the results.</p>
<p>This function executes the <em>command</em> string using <a class="reference internal" href="functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> in the
<code class="docutils literal notranslate"><span class="pre">__main__</span></code> module’s namespace:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">exec</span><span class="p">(</span><span class="n">command</span><span class="p">,</span> <span class="n">__main__</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">,</span> <span class="n">__main__</span><span class="o">.</span><span class="vm">__dict__</span><span class="p">)</span>
</pre></div>
</div>
<p>If <em>filename</em> is not provided, the function creates a <a class="reference internal" href="pstats.html#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">pstats.Stats</span></code></a>
instance and prints a summary to standard output. If <em>filename</em> is
provided, the raw profile data is saved to that file for later analysis
with <a class="reference internal" href="pstats.html#module-pstats" title="pstats: Statistics object for analyzing profiler output."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code></a>.</p>
<p>The <em>sort</em> argument specifies the sort order for printed output, accepting
any value recognized by <a class="reference internal" href="pstats.html#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pstats.Stats.sort_stats()</span></code></a>.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="profiling.tracing.runctx">
<span class="sig-prename descclassname"><span class="pre">profiling.tracing.</span></span><span class="sig-name descname"><span class="pre">runctx</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">command</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globals</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">locals</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sort</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.runctx" title="Link to this definition">¶</a></dt>
<dd><p>Profile execution of a command with explicit namespaces.</p>
<p>Like <a class="reference internal" href="#profiling.tracing.run" title="profiling.tracing.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>, but executes the command with the specified <em>globals</em>
and <em>locals</em> mappings instead of using the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module’s namespace:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">exec</span><span class="p">(</span><span class="n">command</span><span class="p">,</span> <span class="nb">globals</span><span class="p">,</span> <span class="nb">locals</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="profiling.tracing.Profile">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">profiling.tracing.</span></span><span class="sig-name descname"><span class="pre">Profile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timer</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeunit</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0.0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">subcalls</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">builtins</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile" title="Link to this definition">¶</a></dt>
<dd><p>A profiler object that collects execution statistics.</p>
<p>The optional <em>timer</em> argument specifies a custom timing function. If not
provided, the profiler uses a platform-appropriate default timer. When
supplying a custom timer, it must return a single number representing the
current time. If the timer returns integers, use <em>timeunit</em> to specify the
duration of one time unit (for example, <code class="docutils literal notranslate"><span class="pre">0.001</span></code> for milliseconds).</p>
<p>The <em>subcalls</em> argument controls whether the profiler tracks call
relationships between functions. The <em>builtins</em> argument controls whether
built-in functions are profiled.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.8: </span>Added context manager support.</p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.enable">
<span class="sig-name descname"><span class="pre">enable</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.enable" title="Link to this definition">¶</a></dt>
<dd><p>Start collecting profiling data.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.disable">
<span class="sig-name descname"><span class="pre">disable</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.disable" title="Link to this definition">¶</a></dt>
<dd><p>Stop collecting profiling data.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.create_stats">
<span class="sig-name descname"><span class="pre">create_stats</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.create_stats" title="Link to this definition">¶</a></dt>
<dd><p>Stop collecting data and record the results internally as the current
profile.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.print_stats">
<span class="sig-name descname"><span class="pre">print_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sort</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.print_stats" title="Link to this definition">¶</a></dt>
<dd><p>Create a <a class="reference internal" href="pstats.html#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">pstats.Stats</span></code></a> object from the current profile and print
the results to standard output.</p>
<p>The <em>sort</em> argument specifies the sorting order. It accepts a single
key or a tuple of keys for multi-level sorting, using the same values
as <a class="reference internal" href="pstats.html#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pstats.Stats.sort_stats()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13: </span>Support for a tuple of sort keys.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.dump_stats">
<span class="sig-name descname"><span class="pre">dump_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.dump_stats" title="Link to this definition">¶</a></dt>
<dd><p>Write the current profile data to <em>filename</em>. The file can be read by
<a class="reference internal" href="pstats.html#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">pstats.Stats</span></code></a> for later analysis.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.run">
<span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cmd</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.run" title="Link to this definition">¶</a></dt>
<dd><p>Profile the command string via <a class="reference internal" href="functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.runctx">
<span class="sig-name descname"><span class="pre">runctx</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cmd</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globals</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">locals</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.runctx" title="Link to this definition">¶</a></dt>
<dd><p>Profile the command string via <a class="reference internal" href="functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> with the specified
namespaces.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="profiling.tracing.Profile.runcall">
<span class="sig-name descname"><span class="pre">runcall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#profiling.tracing.Profile.runcall" title="Link to this definition">¶</a></dt>
<dd><p>Profile a function call. Returns whatever <em>func</em> returns:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">result</span> <span class="o">=</span> <span class="n">pr</span><span class="o">.</span><span class="n">runcall</span><span class="p">(</span><span class="n">my_function</span><span class="p">,</span> <span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">,</span> <span class="n">keyword</span><span class="o">=</span><span class="n">value</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Profiling requires that the profiled code returns normally. If the
interpreter terminates (for example, via <a class="reference internal" href="sys.html#sys.exit" title="sys.exit"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exit()</span></code></a>) during
profiling, no results will be available.</p>
</div>
</section>
<section id="using-a-custom-timer">
<h2>Using a custom timer<a class="headerlink" href="#using-a-custom-timer" title="Link to this heading">¶</a></h2>
<p>The <a class="reference internal" href="#profiling.tracing.Profile" title="profiling.tracing.Profile"><code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code></a> class accepts a custom timing function, allowing you to
measure different aspects of execution such as wall-clock time or CPU time.
Pass the timing function to the constructor:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">pr</span> <span class="o">=</span> <span class="n">profiling</span><span class="o">.</span><span class="n">tracing</span><span class="o">.</span><span class="n">Profile</span><span class="p">(</span><span class="n">my_timer_function</span><span class="p">)</span>
</pre></div>
</div>
<p>The timer function must return a single number representing the current time.
If it returns integers, also specify <em>timeunit</em> to indicate the duration of
one unit:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Timer returns time in milliseconds</span>
<span class="n">pr</span> <span class="o">=</span> <span class="n">profiling</span><span class="o">.</span><span class="n">tracing</span><span class="o">.</span><span class="n">Profile</span><span class="p">(</span><span class="n">my_ms_timer</span><span class="p">,</span> <span class="mf">0.001</span><span class="p">)</span>
</pre></div>
</div>
<p>For best performance, the timer function should be as fast as possible. The
profiler calls it frequently, so timer overhead directly affects profiling
overhead.</p>
<p>The <a class="reference internal" href="time.html#module-time" title="time: Time access and conversions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code></a> module provides several functions suitable for use as custom
timers:</p>
<ul class="simple">
<li><p><a class="reference internal" href="time.html#time.perf_counter" title="time.perf_counter"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.perf_counter()</span></code></a> for high-resolution wall-clock time</p></li>
<li><p><a class="reference internal" href="time.html#time.process_time" title="time.process_time"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.process_time()</span></code></a> for CPU time (excluding sleep)</p></li>
<li><p><a class="reference internal" href="time.html#time.monotonic" title="time.monotonic"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.monotonic()</span></code></a> for monotonic clock time</p></li>
</ul>
</section>
<section id="limitations">
<h2>Limitations<a class="headerlink" href="#limitations" title="Link to this heading">¶</a></h2>
<p>Deterministic profiling has inherent limitations related to timing accuracy.</p>
<p>The underlying timer typically has a resolution of about one millisecond.
Measurements cannot be more accurate than this resolution. With enough
measurements, timing errors tend to average out, but individual measurements
may be imprecise.</p>
<p>There is also latency between when an event occurs and when the profiler
captures the timestamp. Similarly, there is latency after reading the
timestamp before user code resumes. Functions called frequently accumulate
this latency, which can make them appear slower than they actually are. This
error is typically less than one clock tick per call but can become
significant for functions called many times.</p>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> module (and its <code class="docutils literal notranslate"><span class="pre">cProfile</span></code> alias) is
implemented as a C extension with low overhead, so these timing issues are
less pronounced than with the deprecated pure Python <a class="reference internal" href="profile.html#module-profile" title="profile: Pure Python profiler (deprecated). (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profile</span></code></a> module.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="profiling.html#module-profiling" title="profiling: Python profiling tools for performance analysis."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling</span></code></a></dt><dd><p>Overview of Python profiling tools and guidance on choosing a profiler.</p>
</dd>
<dt><a class="reference internal" href="profiling.sampling.html#module-profiling.sampling" title="profiling.sampling: Statistical sampling profiler for Python processes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code></a></dt><dd><p>Statistical sampling profiler for production use.</p>
</dd>
<dt><a class="reference internal" href="pstats.html#module-pstats" title="pstats: Statistics object for analyzing profiler output."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code></a></dt><dd><p>Statistics analysis and formatting for profile data.</p>
</dd>
<dt><a class="reference internal" href="profile.html#module-profile" title="profile: Pure Python profiler (deprecated). (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profile</span></code></a></dt><dd><p>Deprecated pure Python profiler (includes calibration documentation).</p>
</dd>
</dl>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> — Deterministic profiler</a><ul>
<li><a class="reference internal" href="#what-is-deterministic-profiling">What is deterministic profiling?</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
<li><a class="reference internal" href="#programmatic-usage-examples">Programmatic usage examples</a><ul>
<li><a class="reference internal" href="#basic-profiling">Basic profiling</a></li>
<li><a class="reference internal" href="#using-the-profile-class">Using the <code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code> class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-reference">Module reference</a></li>
<li><a class="reference internal" href="#using-a-custom-timer">Using a custom timer</a></li>
<li><a class="reference internal" href="#limitations">Limitations</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="profiling.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling</span></code> — Python profilers</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="profiling.sampling.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code> — Statistical profiler</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/profiling.tracing.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/profiling.tracing.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="profiling.sampling.html" title="profiling.sampling — Statistical profiler"
>next</a> |</li>
<li class="right" >
<a href="profiling.html" title="profiling — Python profilers"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="debug.html" >Debugging and profiling</a> »</li>
<li class="nav-item nav-item-3"><a href="profiling.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling</span></code> — Python profilers</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code> — Deterministic profiler</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Aug 04, 2026 (11:13 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>