639 lines
46 KiB
HTML
639 lines
46 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
<meta property="og:title" content="sys.monitoring — Execution event monitoring" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/library/sys.monitoring.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="This namespace provides access to the functions and constants necessary to activate and control event monitoring. As programs execute, events occur that might be of interest to tools that monitor e..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="This namespace provides access to the functions and constants necessary to activate and control event monitoring. As programs execute, events occur that might be of interest to tools that monitor e..." />
|
||
<meta property="og:image:width" content="200" />
|
||
<meta property="og:image:height" content="200" />
|
||
<meta name="theme-color" content="#3776ab" />
|
||
|
||
<title>sys.monitoring — Execution event monitoring — Python 3.12.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?digest=b37c26da2f7529d09fe70b41c4b2133fe4931a90" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css" />
|
||
|
||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.12.0 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="sysconfig — Provide access to Python’s configuration information" href="sysconfig.html" />
|
||
<link rel="prev" title="sys — System-specific parameters and functions" href="sys.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/sys.monitoring.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/themetoggle.js"></script>
|
||
|
||
</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="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">sys.monitoring</span></code> — Execution event monitoring</a><ul>
|
||
<li><a class="reference internal" href="#tool-identifiers">Tool identifiers</a><ul>
|
||
<li><a class="reference internal" href="#registering-and-using-tools">Registering and using tools</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#events">Events</a><ul>
|
||
<li><a class="reference internal" href="#local-events">Local events</a></li>
|
||
<li><a class="reference internal" href="#ancillary-events">Ancillary events</a></li>
|
||
<li><a class="reference internal" href="#other-events">Other events</a></li>
|
||
<li><a class="reference internal" href="#the-stop-iteration-event">The STOP_ITERATION event</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#turning-events-on-and-off">Turning events on and off</a><ul>
|
||
<li><a class="reference internal" href="#setting-events-globally">Setting events globally</a></li>
|
||
<li><a class="reference internal" href="#per-code-object-events">Per code object events</a></li>
|
||
<li><a class="reference internal" href="#disabling-events">Disabling events</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#registering-callback-functions">Registering callback functions</a><ul>
|
||
<li><a class="reference internal" href="#callback-function-arguments">Callback function arguments</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="sys.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code> — System-specific parameters and functions</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="sysconfig.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sysconfig</span></code> — Provide access to Python’s configuration information</a></p>
|
||
</div>
|
||
<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 href="https://github.com/python/cpython/blob/main/Doc/library/sys.monitoring.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="sysconfig.html" title="sysconfig — Provide access to Python’s configuration information"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="sys.html" title="sys — System-specific parameters and functions"
|
||
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.12.0 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="python.html" accesskey="U">Python Runtime Services</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> — Execution event monitoring</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" />
|
||
<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-sys.monitoring">
|
||
<span id="sys-monitoring-execution-event-monitoring"></span><h1><a class="reference internal" href="#module-sys.monitoring" title="sys.monitoring: Access and control event monitoring"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code></a> — Execution event monitoring<a class="headerlink" href="#module-sys.monitoring" title="Permalink to this headline">¶</a></h1>
|
||
<hr class="docutils" />
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">sys.monitoring</span></code> is a namespace within the <code class="docutils literal notranslate"><span class="pre">sys</span></code> module,
|
||
not an independent module, so there is no need to
|
||
<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">sys.monitoring</span></code>, simply <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">sys</span></code> and then use
|
||
<code class="docutils literal notranslate"><span class="pre">sys.monitoring</span></code>.</p>
|
||
</div>
|
||
<p>This namespace provides access to the functions and constants necessary to
|
||
activate and control event monitoring.</p>
|
||
<p>As programs execute, events occur that might be of interest to tools that
|
||
monitor execution. The <code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> namespace provides means to
|
||
receive callbacks when events of interest occur.</p>
|
||
<p>The monitoring API consists of three components:</p>
|
||
<ul class="simple">
|
||
<li><p>Tool identifiers</p></li>
|
||
<li><p>Events</p></li>
|
||
<li><p>Callbacks</p></li>
|
||
</ul>
|
||
<section id="tool-identifiers">
|
||
<h2>Tool identifiers<a class="headerlink" href="#tool-identifiers" title="Permalink to this headline">¶</a></h2>
|
||
<p>A tool identifier is an integer and associated name.
|
||
Tool identifiers are used to discourage tools from interfering with each
|
||
other and to allow multiple tools to operate at the same time.
|
||
Currently tools are completely independent and cannot be used to
|
||
monitor each other. This restriction may be lifted in the future.</p>
|
||
<p>Before registering or activating events, a tool should choose an identifier.
|
||
Identifiers are integers in the range 0 to 5.</p>
|
||
<section id="registering-and-using-tools">
|
||
<h3>Registering and using tools<a class="headerlink" href="#registering-and-using-tools" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.use_tool_id">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">use_tool_id</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.use_tool_id" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Must be called before <code class="docutils literal notranslate"><span class="pre">id</span></code> can be used.
|
||
<code class="docutils literal notranslate"><span class="pre">id</span></code> must be in the range 0 to 5 inclusive.
|
||
Raises a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> if <code class="docutils literal notranslate"><span class="pre">id</span></code> is in use.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.free_tool_id">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">free_tool_id</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.free_tool_id" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Should be called once a tool no longer requires <code class="docutils literal notranslate"><span class="pre">id</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.get_tool">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">get_tool</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.get_tool" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the name of the tool if <code class="docutils literal notranslate"><span class="pre">id</span></code> is in use,
|
||
otherwise it returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.
|
||
<code class="docutils literal notranslate"><span class="pre">id</span></code> must be in the range 0 to 5 inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<p>All IDs are treated the same by the VM with regard to events, but the
|
||
following IDs are pre-defined to make co-operation of tools easier:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">DEBUGGER_ID</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">COVERAGE_ID</span> <span class="o">=</span> <span class="mi">1</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">PROFILER_ID</span> <span class="o">=</span> <span class="mi">2</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">monitoring</span><span class="o">.</span><span class="n">OPTIMIZER_ID</span> <span class="o">=</span> <span class="mi">5</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>There is no obligation to set an ID, nor is there anything preventing a tool
|
||
from using an ID even it is already in use.
|
||
However, tools are encouraged to use a unique ID and respect other tools.</p>
|
||
</section>
|
||
</section>
|
||
<section id="events">
|
||
<h2>Events<a class="headerlink" href="#events" title="Permalink to this headline">¶</a></h2>
|
||
<p>The following events are supported:</p>
|
||
<dl class="simple">
|
||
<dt>BRANCH</dt><dd><p>A conditional branch is taken (or not).</p>
|
||
</dd>
|
||
<dt>CALL</dt><dd><p>A call in Python code (event occurs before the call).</p>
|
||
</dd>
|
||
<dt>C_RAISE</dt><dd><p>Exception raised from any callable, except Python functions (event occurs after the exit).</p>
|
||
</dd>
|
||
<dt>C_RETURN</dt><dd><p>Return from any callable, except Python functions (event occurs after the return).</p>
|
||
</dd>
|
||
<dt>EXCEPTION_HANDLED</dt><dd><p>An exception is handled.</p>
|
||
</dd>
|
||
<dt>INSTRUCTION</dt><dd><p>A VM instruction is about to be executed.</p>
|
||
</dd>
|
||
<dt>JUMP</dt><dd><p>An unconditional jump in the control flow graph is made.</p>
|
||
</dd>
|
||
<dt>LINE</dt><dd><p>An instruction is about to be executed that has a different line number from the preceding instruction.</p>
|
||
</dd>
|
||
<dt>PY_RESUME</dt><dd><p>Resumption of a Python function (for generator and coroutine functions), except for throw() calls.</p>
|
||
</dd>
|
||
<dt>PY_RETURN</dt><dd><p>Return from a Python function (occurs immediately before the return, the callee’s frame will be on the stack).</p>
|
||
</dd>
|
||
<dt>PY_START</dt><dd><p>Start of a Python function (occurs immediately after the call, the callee’s frame will be on the stack)</p>
|
||
</dd>
|
||
<dt>PY_THROW</dt><dd><p>A Python function is resumed by a throw() call.</p>
|
||
</dd>
|
||
<dt>PY_UNWIND</dt><dd><p>Exit from a Python function during exception unwinding.</p>
|
||
</dd>
|
||
<dt>PY_YIELD</dt><dd><p>Yield from a Python function (occurs immediately before the yield, the callee’s frame will be on the stack).</p>
|
||
</dd>
|
||
<dt>RAISE</dt><dd><p>An exception is raised, except those that cause a <code class="docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code> event.</p>
|
||
</dd>
|
||
<dt>RERAISE</dt><dd><p>An exception is re-raised, for example at the end of a <code class="docutils literal notranslate"><span class="pre">finally</span></code> block.</p>
|
||
</dd>
|
||
<dt>STOP_ITERATION</dt><dd><p>An artificial <code class="docutils literal notranslate"><span class="pre">StopIteration</span></code> is raised; see <a class="reference internal" href="#the-stop-iteration-event">the STOP_ITERATION event</a>.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>More events may be added in the future.</p>
|
||
<p>These events are attributes of the <code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring.events</span></code> namespace.
|
||
Each event is represented as a power-of-2 integer constant.
|
||
To define a set of events, simply bitwise or the individual events together.
|
||
For example, to specify both <code class="docutils literal notranslate"><span class="pre">PY_RETURN</span></code> and <code class="docutils literal notranslate"><span class="pre">PY_START</span></code> events, use the
|
||
expression <code class="docutils literal notranslate"><span class="pre">PY_RETURN</span> <span class="pre">|</span> <span class="pre">PY_START</span></code>.</p>
|
||
<p>Events are divided into three groups:</p>
|
||
<section id="local-events">
|
||
<h3>Local events<a class="headerlink" href="#local-events" title="Permalink to this headline">¶</a></h3>
|
||
<p>Local events are associated with normal execution of the program and happen
|
||
at clearly defined locations. All local events can be disabled.
|
||
The local events are:</p>
|
||
<ul class="simple">
|
||
<li><p>PY_START</p></li>
|
||
<li><p>PY_RESUME</p></li>
|
||
<li><p>PY_RETURN</p></li>
|
||
<li><p>PY_YIELD</p></li>
|
||
<li><p>CALL</p></li>
|
||
<li><p>LINE</p></li>
|
||
<li><p>INSTRUCTION</p></li>
|
||
<li><p>JUMP</p></li>
|
||
<li><p>BRANCH</p></li>
|
||
<li><p>STOP_ITERATION</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="ancillary-events">
|
||
<h3>Ancillary events<a class="headerlink" href="#ancillary-events" title="Permalink to this headline">¶</a></h3>
|
||
<p>Ancillary events can be monitored like other events, but are controlled
|
||
by another event:</p>
|
||
<ul class="simple">
|
||
<li><p>C_RAISE</p></li>
|
||
<li><p>C_RETURN</p></li>
|
||
</ul>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">C_RETURN</span></code> and <code class="docutils literal notranslate"><span class="pre">C_RAISE</span></code> events are are controlled by the <code class="docutils literal notranslate"><span class="pre">CALL</span></code>
|
||
event. <code class="docutils literal notranslate"><span class="pre">C_RETURN</span></code> and <code class="docutils literal notranslate"><span class="pre">C_RAISE</span></code> events will only be seen if the
|
||
corresponding <code class="docutils literal notranslate"><span class="pre">CALL</span></code> event is being monitored.</p>
|
||
</section>
|
||
<section id="other-events">
|
||
<h3>Other events<a class="headerlink" href="#other-events" title="Permalink to this headline">¶</a></h3>
|
||
<p>Other events are not necessarily tied to a specific location in the
|
||
program and cannot be individually disabled.</p>
|
||
<p>The other events that can be monitored are:</p>
|
||
<ul class="simple">
|
||
<li><p>PY_THROW</p></li>
|
||
<li><p>PY_UNWIND</p></li>
|
||
<li><p>RAISE</p></li>
|
||
<li><p>EXCEPTION_HANDLED</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="the-stop-iteration-event">
|
||
<h3>The STOP_ITERATION event<a class="headerlink" href="#the-stop-iteration-event" title="Permalink to this headline">¶</a></h3>
|
||
<p><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0380/#use-of-stopiteration-to-return-values"><strong>PEP 380</strong></a>
|
||
specifies that a <code class="docutils literal notranslate"><span class="pre">StopIteration</span></code> exception is raised when returning a value
|
||
from a generator or coroutine. However, this is a very inefficient way to
|
||
return a value, so some Python implementations, notably CPython 3.12+, do not
|
||
raise an exception unless it would be visible to other code.</p>
|
||
<p>To allow tools to monitor for real exceptions without slowing down generators
|
||
and coroutines, the <code class="docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code> event is provided.
|
||
<code class="docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code> can be locally disabled, unlike <code class="docutils literal notranslate"><span class="pre">RAISE</span></code>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="turning-events-on-and-off">
|
||
<h2>Turning events on and off<a class="headerlink" href="#turning-events-on-and-off" title="Permalink to this headline">¶</a></h2>
|
||
<p>In order to monitor an event, it must be turned on and a callback registered.
|
||
Events can be turned on or off by setting the events either globally or
|
||
for a particular code object.</p>
|
||
<section id="setting-events-globally">
|
||
<h3>Setting events globally<a class="headerlink" href="#setting-events-globally" title="Permalink to this headline">¶</a></h3>
|
||
<p>Events can be controlled globally by modifying the set of events being monitored.</p>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.get_events">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">get_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></span><a class="headerlink" href="#sys.monitoring.get_events" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the <code class="docutils literal notranslate"><span class="pre">int</span></code> representing all the active events.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.set_events">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">set_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">event_set</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sys.monitoring.set_events" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Activates all events which are set in <code class="docutils literal notranslate"><span class="pre">event_set</span></code>.
|
||
Raises a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> if <code class="docutils literal notranslate"><span class="pre">tool_id</span></code> is not in use.</p>
|
||
</dd></dl>
|
||
|
||
<p>No events are active by default.</p>
|
||
</section>
|
||
<section id="per-code-object-events">
|
||
<h3>Per code object events<a class="headerlink" href="#per-code-object-events" title="Permalink to this headline">¶</a></h3>
|
||
<p>Events can also be controlled on a per code object basis.</p>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.get_local_events">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">get_local_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">code</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="types.html#types.CodeType" title="types.CodeType"><span class="pre">CodeType</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></span><a class="headerlink" href="#sys.monitoring.get_local_events" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns all the local events for <code class="docutils literal notranslate"><span class="pre">code</span></code></p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.set_local_events">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">set_local_events</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">code</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="types.html#types.CodeType" title="types.CodeType"><span class="pre">CodeType</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">event_set</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span><a class="headerlink" href="#sys.monitoring.set_local_events" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Activates all the local events for <code class="docutils literal notranslate"><span class="pre">code</span></code> which are set in <code class="docutils literal notranslate"><span class="pre">event_set</span></code>.
|
||
Raises a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> if <code class="docutils literal notranslate"><span class="pre">tool_id</span></code> is not in use.</p>
|
||
</dd></dl>
|
||
|
||
<p>Local events add to global events, but do not mask them.
|
||
In other words, all global events will trigger for a code object,
|
||
regardless of the local events.</p>
|
||
</section>
|
||
<section id="disabling-events">
|
||
<h3>Disabling events<a class="headerlink" href="#disabling-events" title="Permalink to this headline">¶</a></h3>
|
||
<p>Local events can be disabled for a specific code location by returning
|
||
<code class="docutils literal notranslate"><span class="pre">sys.monitoring.DISABLE</span></code> from a callback function. This does not change
|
||
which events are set, or any other code locations for the same event.</p>
|
||
<p>Disabling events for specific locations is very important for high
|
||
performance monitoring. For example, a program can be run under a
|
||
debugger with no overhead if the debugger disables all monitoring
|
||
except for a few breakpoints.</p>
|
||
</section>
|
||
</section>
|
||
<section id="registering-callback-functions">
|
||
<h2>Registering callback functions<a class="headerlink" href="#registering-callback-functions" title="Permalink to this headline">¶</a></h2>
|
||
<p>To register a callable for events call</p>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="sys.monitoring.register_callback">
|
||
<span class="sig-prename descclassname"><span class="pre">sys.monitoring.</span></span><span class="sig-name descname"><span class="pre">register_callback</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tool_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">event</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">func</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="collections.abc.html#collections.abc.Callable" title="collections.abc.Callable"><span class="pre">Callable</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">→</span> <span class="sig-return-typehint"><a class="reference internal" href="collections.abc.html#collections.abc.Callable" title="collections.abc.Callable"><span class="pre">Callable</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span></span><a class="headerlink" href="#sys.monitoring.register_callback" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Registers the callable <code class="docutils literal notranslate"><span class="pre">func</span></code> for the <code class="docutils literal notranslate"><span class="pre">event</span></code> with the given <code class="docutils literal notranslate"><span class="pre">tool_id</span></code></p>
|
||
<p>If another callback was registered for the given <code class="docutils literal notranslate"><span class="pre">tool_id</span></code> and <code class="docutils literal notranslate"><span class="pre">event</span></code>,
|
||
it is unregistered and returned.
|
||
Otherwise <code class="docutils literal notranslate"><span class="pre">register_callback</span></code> returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>Functions can be unregistered by calling
|
||
<code class="docutils literal notranslate"><span class="pre">sys.monitoring.register_callback(tool_id,</span> <span class="pre">event,</span> <span class="pre">None)</span></code>.</p>
|
||
<p>Callback functions can be registered and unregistered at any time.</p>
|
||
<p>Registering or unregistering a callback function will generate a <code class="docutils literal notranslate"><span class="pre">sys.audit</span></code> event.</p>
|
||
<section id="callback-function-arguments">
|
||
<h3>Callback function arguments<a class="headerlink" href="#callback-function-arguments" title="Permalink to this headline">¶</a></h3>
|
||
<p>When an active event occurs, the registered callback function is called.
|
||
Different events will provide the callback function with different arguments, as follows:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">PY_START</span></code> and <code class="docutils literal notranslate"><span class="pre">PY_RESUME</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="n">CodeType</span><span class="p">,</span> <span class="n">instruction_offset</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">DISABLE</span> <span class="o">|</span> <span class="n">Any</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">PY_RETURN</span></code> and <code class="docutils literal notranslate"><span class="pre">PY_YIELD</span></code>:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">func(code:</span> <span class="pre">CodeType,</span> <span class="pre">instruction_offset:</span> <span class="pre">int,</span> <span class="pre">retval:</span> <span class="pre">object)</span> <span class="pre">-></span> <span class="pre">DISABLE</span> <span class="pre">|</span> <span class="pre">Any</span></code></p>
|
||
</div></blockquote>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">CALL</span></code>, <code class="docutils literal notranslate"><span class="pre">C_RAISE</span></code> and <code class="docutils literal notranslate"><span class="pre">C_RETURN</span></code>:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">func(code:</span> <span class="pre">CodeType,</span> <span class="pre">instruction_offset:</span> <span class="pre">int,</span> <span class="pre">callable:</span> <span class="pre">object,</span> <span class="pre">arg0:</span> <span class="pre">object</span> <span class="pre">|</span> <span class="pre">MISSING)</span> <span class="pre">-></span> <span class="pre">DISABLE</span> <span class="pre">|</span> <span class="pre">Any</span></code></p>
|
||
<p>If there are no arguments, <code class="docutils literal notranslate"><span class="pre">arg0</span></code> is set to <code class="docutils literal notranslate"><span class="pre">MISSING</span></code>.</p>
|
||
</div></blockquote>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">RAISE</span></code>, <code class="docutils literal notranslate"><span class="pre">RERAISE</span></code>, <code class="docutils literal notranslate"><span class="pre">EXCEPTION_HANDLED</span></code>, <code class="docutils literal notranslate"><span class="pre">PY_UNWIND</span></code>, <code class="docutils literal notranslate"><span class="pre">PY_THROW</span></code> and <code class="docutils literal notranslate"><span class="pre">STOP_ITERATION</span></code>:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">func(code:</span> <span class="pre">CodeType,</span> <span class="pre">instruction_offset:</span> <span class="pre">int,</span> <span class="pre">exception:</span> <span class="pre">BaseException)</span> <span class="pre">-></span> <span class="pre">DISABLE</span> <span class="pre">|</span> <span class="pre">Any</span></code></p>
|
||
</div></blockquote>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">LINE</span></code>:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">func(code:</span> <span class="pre">CodeType,</span> <span class="pre">line_number:</span> <span class="pre">int)</span> <span class="pre">-></span> <span class="pre">DISABLE</span> <span class="pre">|</span> <span class="pre">Any</span></code></p>
|
||
</div></blockquote>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">BRANCH</span></code> and <code class="docutils literal notranslate"><span class="pre">JUMP</span></code>:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">func(code:</span> <span class="pre">CodeType,</span> <span class="pre">instruction_offset:</span> <span class="pre">int,</span> <span class="pre">destination_offset:</span> <span class="pre">int)</span> <span class="pre">-></span> <span class="pre">DISABLE</span> <span class="pre">|</span> <span class="pre">Any</span></code></p>
|
||
</div></blockquote>
|
||
<p>Note that the <code class="docutils literal notranslate"><span class="pre">destination_offset</span></code> is where the code will next execute.
|
||
For an untaken branch this will be the offset of the instruction following
|
||
the branch.</p>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">INSTRUCTION</span></code>:</p>
|
||
<blockquote>
|
||
<div><p><code class="docutils literal notranslate"><span class="pre">func(code:</span> <span class="pre">CodeType,</span> <span class="pre">instruction_offset:</span> <span class="pre">int)</span> <span class="pre">-></span> <span class="pre">DISABLE</span> <span class="pre">|</span> <span class="pre">Any</span></code></p>
|
||
</div></blockquote>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<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">sys.monitoring</span></code> — Execution event monitoring</a><ul>
|
||
<li><a class="reference internal" href="#tool-identifiers">Tool identifiers</a><ul>
|
||
<li><a class="reference internal" href="#registering-and-using-tools">Registering and using tools</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#events">Events</a><ul>
|
||
<li><a class="reference internal" href="#local-events">Local events</a></li>
|
||
<li><a class="reference internal" href="#ancillary-events">Ancillary events</a></li>
|
||
<li><a class="reference internal" href="#other-events">Other events</a></li>
|
||
<li><a class="reference internal" href="#the-stop-iteration-event">The STOP_ITERATION event</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#turning-events-on-and-off">Turning events on and off</a><ul>
|
||
<li><a class="reference internal" href="#setting-events-globally">Setting events globally</a></li>
|
||
<li><a class="reference internal" href="#per-code-object-events">Per code object events</a></li>
|
||
<li><a class="reference internal" href="#disabling-events">Disabling events</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#registering-callback-functions">Registering callback functions</a><ul>
|
||
<li><a class="reference internal" href="#callback-function-arguments">Callback function arguments</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="sys.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code> — System-specific parameters and functions</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="sysconfig.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sysconfig</span></code> — Provide access to Python’s configuration information</a></p>
|
||
</div>
|
||
<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 href="https://github.com/python/cpython/blob/main/Doc/library/sys.monitoring.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="sysconfig.html" title="sysconfig — Provide access to Python’s configuration information"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="sys.html" title="sys — System-specific parameters and functions"
|
||
>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.12.0 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="python.html" >Python Runtime Services</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys.monitoring</span></code> — Execution event monitoring</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" />
|
||
<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-2023, 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 Oct 02, 2023.
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.5.0.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |