pyetw 1.1.0

Python logging via Event Tracing for Windows

Python logging via Event Tracing for Windows (ETW)

PyEtw is a Python package that allows you to use Pythons standard logging facility with Event Tracing for Windows (ETW).

PyEtw implements logging.Handler and overloads emit() to handle the logging.LogRecord objects. The logging.LogRecord object is then converted to a Windows event record, and written via the API EventWriteTransfer as an ETW TraceLogging event.

Using ETW for Python logging allows you to leverage the many tools available for the Windows ETW ecosystem, such as MGTEK TraceView Plus.

Features

• Log Python logging.LogRecord via Event Tracing for Windows.
• Includes standard metadata in ETW records, such as ETW provider, time-stamp, process and thread ID, and log-level.
• Includes Python specific logging.LogRecord metadata in ETW records, such as Python module, function name, filename and line-number, and log message.
• Automatic provider ID (GUID) generation via provider name hash.
• Native WIN32 implementation with no dependecies.

Logging ETW events via Python

To log ETW events via the Python logging module you can write:

import logging
import pyetw

logging.basicConfig(level=logging.DEBUG, handlers=(pyetw.LoggerHandler(),))
logging.info("Hello from PyEtw!")

Note the parameter handlers to basicConfig(). By specifing the pyetw.LoggerHandler(), the log records are written as ETW TraceLogging events.

To record and view the traces, you can use any ETW tracing tool.

ETW Provider GUID hash

PyEtw uses the standard TraceLogging hashing algorithm to derive the provider GUID from the trace provider name, which is set to the Python logger name by default.

If your tracing tool is not able to generate the provider GUID from the provider name, you can use the guid property of the EventProvider class to obtain the GUID. For instance, to get the provider GUID for the root logger, enter the following command:

python -c "import pyetw;print(pyetw.EventProvider('root').guid)"

Recording ETW Traces

Here is an example that records the events of the root logger to a trace file using Tracelog, which is included in the Windows SDK

C:\Temp> tracelog -start mytrace -guid *root

Note that the specified GUID must match the name of the Python logger. Prefix the logger name with a star to have tracelog create a GUID hash of the logger name.

After you are done running the Python example from above, run

C:\Temp> tracelog -stop mytrace

When the trace is stopped, you will have a file LogFile.Etl that contains a single trace record.

To view the recorded trace, you can write

C:\Temp> tracefmt -displayonly LogFile.Etl

Installing PyEtw

You can install the PyEtw package from PyPI using pip:

pip install pyetw

In order to use the PyEtw package, you need Python 3.6 or higher.

The source code for the PyEtw package can be found at GitHub at https://github.com/mgtek/pyetw.

Documentation

You can find the PyEtw user's guide at https://pyetw.readthedocs.io/.

Examples

You can find Python examples using PyEtw in the pyetw GitHub repository at https://github.com/mgtek/pyetw/tree/main/examples.

Getting help

For issues with PyEtw, please visit the pyetw issue tracker.