Document Python application logging

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

diff --git a/contents/using-lttng/instrumenting/python-application.md b/contents/using-lttng/instrumenting/python-application.md
new file mode 100644 (file)
index 0000000..d3ca711
--- /dev/null
+++ b/contents/using-lttng/instrumenting/python-application.md
@@ -0,0 +1,67 @@
+---
+id: python-application
+since: 2.7
+---
+
+Python 2 and Python 3 applications using the standard
+<a href="https://docs.python.org/3/howto/logging.html" class="ext"><code>logging</code> module</a>
+can be traced by LTTng using the LTTng-UST Python agent.
+
+Import the `lttngust` package in your Python application. For example:
+
+~~~ python
+import lttngust
+import logging
+
+
+def example():
+    logger = logging.getLogger('my-logger')
+
+    while True:
+        logger.debug('debug message')
+        logger.info('info message')
+        logger.warn('warn message')
+        logger.error('error message')
+        logger.critical('critical message')
+        time.sleep(1)
+
+
+if __name__ == '__main__':
+    example()
+~~~
+
+Importing `lttngust` adds a logging handler which emits LTTng-UST
+events. You do not need to get a special logger for tracing to work.
+
+Use the `--python` option of the `lttng enable-event`,
+`lttng disable-event`, and `lttng list` commands to target
+Python applications. For example, here's how to enable the events
+produced by the Python logger above:
+
+<pre class="term">
+lttng enable-event --python my-logger
+</pre>
+
+Standard Python log levels are supported using the `PYTHON_` prefix.
+For example, here's how to enable the warning (and more important)
+events produced by the Python logger above:
+
+<pre class="term">
+lttng enable-event --python my-logger --loglevel PYTHON_WARNING
+</pre>
+
+See [Enabling and disabling events](#doc-enabling-disabling-events) for
+more options.
+
+When loading, the LTTng-UST Python agent tries to register to the
+[session daemon](#doc-lttng-sessiond). Note that the session daemon
+needs to be started _before_ the Python application is started. If a
+session daemon is found, the agent tries to register to it during
+5&nbsp;seconds, after which the application continues without LTTng
+tracing support. This timeout value is overriden by the
+`LTTNG_UST_PYTHON_REGISTER_TIMEOUT` environment variable (milliseconds).
+
+If the session daemon stops while a registered Python application is
+registered, the application retries to connect and register to a session
+daemon every 3&nbsp;seconds. This timeout value is overridden by the
+`LTTNG_UST_PYTHON_REGISTER_RETRY_DELAY` environment variable.

diff --git a/toc/docs.yml b/toc/docs.yml
index 59c0b7ce0c26557703e503155edf854e48e455d2..9fa03ea74c6d5259ac128e9ebd0bdc3b9be2dde7 100644 (file)
--- a/toc/docs.yml
+++ b/toc/docs.yml
@@ -146,6 +146,8 @@ cats:
                 title: <code>java.util.logging</code>
               - id: log4j
                 title: Apache log4j 1.2
+          - id: python-application
+            title: Python application
           - id: instrumenting-linux-kernel
             title: Linux kernel
             cats: