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