| 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 | logging.basicConfig() |
| 20 | logger = logging.getLogger('my-logger') |
| 21 | |
| 22 | while True: |
| 23 | logger.debug('debug message') |
| 24 | logger.info('info message') |
| 25 | logger.warn('warn message') |
| 26 | logger.error('error message') |
| 27 | logger.critical('critical message') |
| 28 | time.sleep(1) |
| 29 | |
| 30 | |
| 31 | if __name__ == '__main__': |
| 32 | example() |
| 33 | ~~~ |
| 34 | |
| 35 | Importing `lttngust` adds a logging handler which emits LTTng-UST |
| 36 | events. You do not need to get a special logger for tracing to work. |
| 37 | |
| 38 | Note that `logging.basicConfig()`, which adds to the root logger a basic |
| 39 | logging handler which prints to the standard error stream, is not |
| 40 | strictly required for LTTng-UST tracing to work, but in versions of |
| 41 | Python preceding 3.2, a warning message could be seen indicating that no |
| 42 | handler exists for the logger `my-logger`. |
| 43 | |
| 44 | Use the `--python` option of the `lttng enable-event`, |
| 45 | `lttng disable-event`, and `lttng list` commands to target |
| 46 | Python applications. For example, here's how to enable the events |
| 47 | produced by the Python logger above: |
| 48 | |
| 49 | <pre class="term"> |
| 50 | lttng enable-event --python my-logger |
| 51 | </pre> |
| 52 | |
| 53 | Standard Python log levels are supported using the `PYTHON_` prefix. |
| 54 | For example, here's how to enable the warning (and more important) |
| 55 | events produced by the Python logger above: |
| 56 | |
| 57 | <pre class="term"> |
| 58 | lttng enable-event --python my-logger --loglevel PYTHON_WARNING |
| 59 | </pre> |
| 60 | |
| 61 | See [Enabling and disabling events](#doc-enabling-disabling-events) for |
| 62 | more options. |
| 63 | |
| 64 | When loading, the LTTng-UST Python agent tries to register to the |
| 65 | [session daemon](#doc-lttng-sessiond). Note that the session daemon |
| 66 | needs to be started _before_ the Python application is started. If a |
| 67 | session daemon is found, the agent tries to register to it during |
| 68 | 5 seconds, after which the application continues without LTTng |
| 69 | tracing support. This timeout value is overriden by the |
| 70 | `LTTNG_UST_PYTHON_REGISTER_TIMEOUT` environment variable (milliseconds). |
| 71 | |
| 72 | If the session daemon stops while a registered Python application is |
| 73 | registered, the application retries to connect and register to a session |
| 74 | daemon every 3 seconds. This timeout value is overridden by the |
| 75 | `LTTNG_UST_PYTHON_REGISTER_RETRY_DELAY` environment variable. |