path: root/devdocs/python~3.12/library%2Fsyslog.html

 <span id="syslog-unix-syslog-library-routines"></span><h1>syslog — Unix syslog library routines</h1>  <p>This module provides an interface to the Unix <code>syslog</code> library routines. Refer to the Unix manual pages for a detailed description of the <code>syslog</code> facility.</p> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, not Emscripten, not WASI.</p> </div> <p>This module wraps the system <code>syslog</code> family of routines. A pure Python library that can speak to a syslog server is available in the <a class="reference internal" href="logging.handlers#module-logging.handlers" title="logging.handlers: Handlers for the logging module."><code>logging.handlers</code></a> module as <code>SysLogHandler</code>.</p> <p>The module defines the following functions:</p> <dl class="py function"> <dt class="sig sig-object py" id="syslog.syslog">
<code>syslog.syslog(message)</code> </dt> <dt class="sig sig-object py"> <span class="sig-prename descclassname">syslog.</span><span class="sig-name descname">syslog</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">priority</span></em>, <em class="sig-param"><span class="n">message</span></em><span class="sig-paren">)</span>
</dt> <dd>
<p>Send the string <em>message</em> to the system logger. A trailing newline is added if necessary. Each message is tagged with a priority composed of a <em>facility</em> and a <em>level</em>. The optional <em>priority</em> argument, which defaults to <code>LOG_INFO</code>, determines the message priority. If the facility is not encoded in <em>priority</em> using logical-or (<code>LOG_INFO | LOG_USER</code>), the value given in the <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> call is used.</p> <p>If <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> has not been called prior to the call to <a class="reference internal" href="#module-syslog" title="syslog: An interface to the Unix syslog library routines. (Unix)"><code>syslog()</code></a>, <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> will be called with no arguments.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>syslog.syslog</code> with arguments <code>priority</code>, <code>message</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>In previous versions, <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> would not be called automatically if it wasn’t called prior to the call to <a class="reference internal" href="#module-syslog" title="syslog: An interface to the Unix syslog library routines. (Unix)"><code>syslog()</code></a>, deferring to the syslog implementation to call <code>openlog()</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>This function is restricted in subinterpreters. (Only code that runs in multiple interpreters is affected and the restriction is not relevant for most users.) <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> must be called in the main interpreter before <a class="reference internal" href="#module-syslog" title="syslog: An interface to the Unix syslog library routines. (Unix)"><code>syslog()</code></a> may be used in a subinterpreter. Otherwise it will raise <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a>.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="syslog.openlog">
<code>syslog.openlog([ident[, logoption[, facility]]])</code> </dt> <dd>
<p>Logging options of subsequent <a class="reference internal" href="#module-syslog" title="syslog: An interface to the Unix syslog library routines. (Unix)"><code>syslog()</code></a> calls can be set by calling <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a>. <a class="reference internal" href="#module-syslog" title="syslog: An interface to the Unix syslog library routines. (Unix)"><code>syslog()</code></a> will call <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> with no arguments if the log is not currently open.</p> <p>The optional <em>ident</em> keyword argument is a string which is prepended to every message, and defaults to <code>sys.argv[0]</code> with leading path components stripped. The optional <em>logoption</em> keyword argument (default is 0) is a bit field – see below for possible values to combine. The optional <em>facility</em> keyword argument (default is <code>LOG_USER</code>) sets the default facility for messages which do not have a facility explicitly encoded.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>syslog.openlog</code> with arguments <code>ident</code>, <code>logoption</code>, <code>facility</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>In previous versions, keyword arguments were not allowed, and <em>ident</em> was required.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>This function is restricted in subinterpreters. (Only code that runs in multiple interpreters is affected and the restriction is not relevant for most users.) This may only be called in the main interpreter. It will raise <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a> if called in a subinterpreter.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="syslog.closelog">
<code>syslog.closelog()</code> </dt> <dd>
<p>Reset the syslog module values and call the system library <code>closelog()</code>.</p> <p>This causes the module to behave as it does when initially imported. For example, <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> will be called on the first <a class="reference internal" href="#module-syslog" title="syslog: An interface to the Unix syslog library routines. (Unix)"><code>syslog()</code></a> call (if <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> hasn’t already been called), and <em>ident</em> and other <a class="reference internal" href="#syslog.openlog" title="syslog.openlog"><code>openlog()</code></a> parameters are reset to defaults.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>syslog.closelog</code> with no arguments.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>This function is restricted in subinterpreters. (Only code that runs in multiple interpreters is affected and the restriction is not relevant for most users.) This may only be called in the main interpreter. It will raise <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a> if called in a subinterpreter.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="syslog.setlogmask">
<code>syslog.setlogmask(maskpri)</code> </dt> <dd>
<p>Set the priority mask to <em>maskpri</em> and return the previous mask value. Calls to <a class="reference internal" href="#module-syslog" title="syslog: An interface to the Unix syslog library routines. (Unix)"><code>syslog()</code></a> with a priority level not set in <em>maskpri</em> are ignored. The default is to log all priorities. The function <code>LOG_MASK(pri)</code> calculates the mask for the individual priority <em>pri</em>. The function <code>LOG_UPTO(pri)</code> calculates the mask for all priorities up to and including <em>pri</em>.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>syslog.setlogmask</code> with argument <code>maskpri</code>.</p> </dd>
</dl> <p>The module defines the following constants:</p> <dl class="simple"> <dt>Priority levels (high to low):</dt>
<dd>
<p><code>LOG_EMERG</code>, <code>LOG_ALERT</code>, <code>LOG_CRIT</code>, <code>LOG_ERR</code>, <code>LOG_WARNING</code>, <code>LOG_NOTICE</code>, <code>LOG_INFO</code>, <code>LOG_DEBUG</code>.</p> </dd> <dt>Facilities:</dt>
<dd>
<p><code>LOG_KERN</code>, <code>LOG_USER</code>, <code>LOG_MAIL</code>, <code>LOG_DAEMON</code>, <code>LOG_AUTH</code>, <code>LOG_LPR</code>, <code>LOG_NEWS</code>, <code>LOG_UUCP</code>, <code>LOG_CRON</code>, <code>LOG_SYSLOG</code>, <code>LOG_LOCAL0</code> to <code>LOG_LOCAL7</code>, and, if defined in <code>&lt;syslog.h&gt;</code>, <code>LOG_AUTHPRIV</code>.</p> </dd> <dt>Log options:</dt>
<dd>
<p><code>LOG_PID</code>, <code>LOG_CONS</code>, <code>LOG_NDELAY</code>, and, if defined in <code>&lt;syslog.h&gt;</code>, <code>LOG_ODELAY</code>, <code>LOG_NOWAIT</code>, and <code>LOG_PERROR</code>.</p> </dd> </dl> <section id="examples"> <h2>Examples</h2> <section id="simple-example"> <h3>Simple example</h3> <p>A simple set of examples:</p> <pre data-language="python">import syslog

syslog.syslog('Processing started')
if error:
    syslog.syslog(syslog.LOG_ERR, 'Processing started')
</pre> <p>An example of setting some log options, these would include the process ID in logged messages, and write the messages to the destination facility used for mail logging:</p> <pre data-language="python">syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')
</pre> </section> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/syslog.html" class="_attribution-link">https://docs.python.org/3.12/library/syslog.html</a>
  </p>
</div>