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 | |
d7976b2f | 15 | import time |
024571e4 PP |
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 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 seconds. This timeout value is overridden by the | |
68 | `LTTNG_UST_PYTHON_REGISTER_RETRY_DELAY` environment variable. |