| Name | pyetw JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | |
| Summary | Python logging via Event Tracing for Windows |
| upload_time | 2022-12-17 11:19:27 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | |
| keywords |
etw
windows
tracelogging
traceview
traceview plus
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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`](https://docs.python.org/3/library/logging.handlers.html)
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`](https://learn.microsoft.com/en-us/windows/win32/api/evntprov/nf-evntprov-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](https://www.mgtek.com/traceview).
## 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:
```python
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.
## Recording ETW Traces
Here is an example that records the events of the `root` logger to a trace file
using [`Tracelog`](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/tracelog),
which is included in the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/)
```console
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
```console
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
```console
C:\Temp> tracefmt -displayonly LogFile.Etl
```
## Installing PyEtw
You can install the [PyEtw package](https://pypi.org/project/pyetw/) from PyPI using pip:
```console
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](https://github.com/mgtek/pyetw/issues).
Raw data
{
"_id": null,
"home_page": "",
"name": "pyetw",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "etw,windows,tracelogging,traceview,traceview plus",
"author": "",
"author_email": "Marius Greuel <greuelm@mgtek.com>",
"download_url": "https://files.pythonhosted.org/packages/e5/de/a33ea1d4b7328335ba1e6d33b21691be7879f026001ff97682230c6bce4b/pyetw-1.0.1.tar.gz",
"platform": null,
"description": "# Python logging via Event Tracing for Windows (ETW)\n\n\n\n\n**PyEtw** is a Python package that allows you to use Pythons standard logging facility\nwith **Event Tracing for Windows (ETW)**.\n\n**PyEtw** implements [`logging.Handler`](https://docs.python.org/3/library/logging.handlers.html)\nand overloads `emit()` to handle the `logging.LogRecord` objects.\nThe `logging.LogRecord` object is then converted to a Windows event record,\nand written via the API [`EventWriteTransfer`](https://learn.microsoft.com/en-us/windows/win32/api/evntprov/nf-evntprov-eventwritetransfer)\nas an ETW TraceLogging event.\n\nUsing ETW for Python logging allows you to leverage the many tools available\nfor the Windows ETW ecosystem, such as [MGTEK TraceView Plus](https://www.mgtek.com/traceview).\n\n## Features\n\n- Log Python `logging.LogRecord` via **Event Tracing for Windows**.\n- Includes standard metadata in ETW records, such as ETW provider, time-stamp, process and thread ID, and log-level.\n- Includes Python specific `logging.LogRecord` metadata in ETW records, such as Python module, function name, filename and line-number, and log message.\n- Automatic provider ID (GUID) generation via provider name hash.\n- Native WIN32 implementation with no dependecies.\n\n## Logging ETW events via Python\n\nTo log ETW events via the Python `logging` module you can write:\n\n```python\nimport logging\nimport pyetw\n\nlogging.basicConfig(level=logging.DEBUG, handlers=(pyetw.LoggerHandler(),))\nlogging.info(\"Hello from PyEtw!\")\n```\n\nNote the parameter `handlers` to `basicConfig()`. By specifing the `pyetw.LoggerHandler()`,\nthe log records are written as ETW TraceLogging events.\n\nTo record and view the traces, you can use any ETW tracing tool.\n\n## Recording ETW Traces\n\nHere is an example that records the events of the `root` logger to a trace file\nusing [`Tracelog`](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/tracelog),\nwhich is included in the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/)\n\n```console\nC:\\Temp> tracelog -start mytrace -guid *root\n```\n\nNote that the specified GUID must match the name of the Python logger.\nPrefix the logger name with a **star** to have tracelog create a GUID hash of the logger name.\n\nAfter you are done running the Python example from above, run\n\n```console\nC:\\Temp> tracelog -stop mytrace\n```\n\nWhen the trace is stopped, you will have a file `LogFile.Etl` that contains a single trace record.\n\nTo view the recorded trace, you can write\n\n```console\nC:\\Temp> tracefmt -displayonly LogFile.Etl\n```\n\n## Installing PyEtw\n\nYou can install the [PyEtw package](https://pypi.org/project/pyetw/) from PyPI using pip:\n\n```console\npip install pyetw\n```\n\nIn order to use the **PyEtw** package, you need **Python 3.6** or higher.\n\nThe source code for the **PyEtw** package can be found at GitHub at <https://github.com/mgtek/pyetw>.\n\n## Documentation\n\nYou can find the **PyEtw** user's guide at <https://pyetw.readthedocs.io/>.\n\n## Examples\n\nYou can find Python examples using **PyEtw** in the pyetw GitHub repository at <https://github.com/mgtek/pyetw/tree/main/examples>.\n\n## Getting help\n\nFor issues with **PyEtw**, please visit the\n[pyetw issue tracker](https://github.com/mgtek/pyetw/issues).\n",
"bugtrack_url": null,
"license": "",
"summary": "Python logging via Event Tracing for Windows",
"version": "1.0.1",
"split_keywords": [
"etw",
"windows",
"tracelogging",
"traceview",
"traceview plus"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "c0578b3e86ba4ace098c290601cb1ee1",
"sha256": "f8c9059ed47795351d4f488cadae73e5dfed0bd2bcbfd202767a35abb44f4815"
},
"downloads": -1,
"filename": "pyetw-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c0578b3e86ba4ace098c290601cb1ee1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6694,
"upload_time": "2022-12-17T11:19:26",
"upload_time_iso_8601": "2022-12-17T11:19:26.236673Z",
"url": "https://files.pythonhosted.org/packages/95/b4/64f5ff796b69bd2877e642e1a4af56b5107e515f62ef58b67d87ec5b1871/pyetw-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "1778beaba33f601a0a12d1caad221063",
"sha256": "ff1a83aa0adf9a6adcf24a6b0c2a7268e21c50b3beaead7f86413730f8a73866"
},
"downloads": -1,
"filename": "pyetw-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "1778beaba33f601a0a12d1caad221063",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6420,
"upload_time": "2022-12-17T11:19:27",
"upload_time_iso_8601": "2022-12-17T11:19:27.220696Z",
"url": "https://files.pythonhosted.org/packages/e5/de/a33ea1d4b7328335ba1e6d33b21691be7879f026001ff97682230c6bce4b/pyetw-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-17 11:19:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "pyetw"
}
