contents/using-lttng/instrumenting/python-application.md

   1 ---
   2 id: python-application
   3 since: 2.7
   4 ---
   5
   6 Python 2 and Python 3 applications using the standard
   7 <a href="https://docs.python.org/3/howto/logging.html" class="ext"><code>logging</code> module</a>
   8 can be traced by LTTng using the LTTng-UST Python agent.
   9
  10 Import the `lttngust` package in your Python application. For example:
  11
  12 ~~~ python
  13 import lttngust
  14 import logging
  15 import time
  16
  17
  18 def example():
  19     logger = logging.getLogger('my-logger')
  20
  21     while True:
  22         logger.debug('debug message')
  23         logger.info('info message')
  24         logger.warn('warn message')
  25         logger.error('error message')
  26         logger.critical('critical message')
  27         time.sleep(1)
  28
  29
  30 if __name__ == '__main__':
  31     example()
  32 ~~~
  33
  34 Importing `lttngust` adds a logging handler which emits LTTng-UST
  35 events. You do not need to get a special logger for tracing to work.
  36
  37 Use the `--python` option of the `lttng enable-event`,
  38 `lttng disable-event`, and `lttng list` commands to target
  39 Python applications. For example, here's how to enable the events
  40 produced by the Python logger above:
  41
  42 <pre class="term">
  43 lttng enable-event --python my-logger
  44 </pre>
  45
  46 Standard Python log levels are supported using the `PYTHON_` prefix.
  47 For example, here's how to enable the warning (and more important)
  48 events produced by the Python logger above:
  49
  50 <pre class="term">
  51 lttng enable-event --python my-logger --loglevel PYTHON_WARNING
  52 </pre>
  53
  54 See [Enabling and disabling events](#doc-enabling-disabling-events) for
  55 more options.
  56
  57 When loading, the LTTng-UST Python agent tries to register to the
  58 [session daemon](#doc-lttng-sessiond). Note that the session daemon
  59 needs to be started _before_ the Python application is started. If a
  60 session daemon is found, the agent tries to register to it during
  61 5&nbsp;seconds, after which the application continues without LTTng
  62 tracing support. This timeout value is overriden by the
  63 `LTTNG_UST_PYTHON_REGISTER_TIMEOUT` environment variable (milliseconds).
  64
  65 If the session daemon stops while a registered Python application is
  66 registered, the application retries to connect and register to a session
  67 daemon every 3&nbsp;seconds. This timeout value is overridden by the
  68 `LTTNG_UST_PYTHON_REGISTER_RETRY_DELAY` environment variable.