Python module for tracing Windows DLL loads
Project description
dlltracer
The dlltracer
tool is an assistive tool for diagnosing import errors in
CPython when they are caused by DLL resolution failures on Windows.
In general, any DLL load error is reported as an ImportError
of the top-level
extension module. No more specific information is available for CPython to
display, which can make it difficult to diagnose.
This tool uses not-quite-documented performance events to report on the intermediate steps of importing an extension module. These events are undocumented and unsupported, so the format has been inferred by example and may change, but until it does it will report on the loads that actually occur. However, because it can't report on loads that never occur, you'll still need to do some work to diagnose the root cause of the failure.
The most useful static analysis tool is
dumpbin,
which is included with Visual Studio. When passed a DLL or PYD file and the
/imports
option, it will list all dependencies that should be loaded. It
shows them by name, that is, before path resolution occurs.
dlltracer
performs dynamic analysis, which shows the DLLs that are loaded at
runtime with their full paths. Combined with understanding the dependency
graph of your module, it is easier to diagnose why the overall import fails.
Install
pip install dlltracer
Where the pip
command may be replaced by a more appropriate command for your
environment, such as python -m pip
or pip3.9
.
Use
Note: Regardless of how output is collected, this tool must be run as
Administrator. Otherwise, starting a trace will fail with a PermissionError
.
Only one thread may be tracing across your entire machine. Because the state
of traces is not well managed by Windows, this tool will attempt to stop any
other running traces.
A basic trace that prints messages to standard output is:
import dlltracer
import sys
with dlltracer.Trace(out=sys.stdout):
import module_to_trace
The output may look like this (for import ssl
):
LoadLibrary \Device\HarddiskVolume3\Windows\System32\kernel.appcore.dll
LoadLibrary \Device\HarddiskVolume3\Program Files\Python39\DLLs\_ssl.pyd
LoadLibrary \Device\HarddiskVolume3\Windows\System32\crypt32.dll
LoadLibrary \Device\HarddiskVolume3\Program Files\Python39\DLLs\libcrypto-1_1.dll
LoadLibrary \Device\HarddiskVolume3\Program Files\Python39\DLLs\libssl-1_1.dll
LoadLibrary \Device\HarddiskVolume3\Windows\System32\user32.dll
LoadLibrary \Device\HarddiskVolume3\Windows\System32\win32u.dll
LoadLibrary \Device\HarddiskVolume3\Windows\System32\gdi32.dll
LoadLibrary \Device\HarddiskVolume3\Windows\System32\gdi32full.dll
LoadLibrary \Device\HarddiskVolume3\Windows\System32\msvcp_win.dll
LoadLibrary \Device\HarddiskVolume3\Windows\System32\imm32.dll
LoadLibrary \Device\HarddiskVolume3\Program Files\Python39\DLLs\_socket.pyd
LoadLibrary \Device\HarddiskVolume3\Program Files\Python39\DLLs\select.pyd
A failed import may look like this (for import ssl
but with libcrypto-1_1.dll
missing):
LoadLibrary \Device\HarddiskVolume3\Windows\System32\kernel.appcore.dll
LoadLibrary \Device\HarddiskVolume3\Program Files\Python39\DLLs\_ssl.pyd
LoadLibrary \Device\HarddiskVolume3\Windows\System32\crypt32.dll
LoadLibrary \Device\HarddiskVolume3\Program Files\Python39\DLLs\libssl-1_1.dll
Failed \Device\HarddiskVolume3\Windows\System32\crypt32.dll
Failed \Device\HarddiskVolume3\Program Files\Python39\DLLs\libssl-1_1.dll
Failed \Device\HarddiskVolume3\Program Files\Python39\DLLs\_ssl.pyd
Traceback (most recent call last):
File "C:\Projects\test-script.py", line 28, in <module>
import ssl
File "C:\Program Files\Python39\lib\ssl.py", line 98, in <module>
import _ssl # if we can't import it, let the error propagate
ImportError: DLL load failed while importing _ssl: The specified module could not be found.
Notice that the missing DLL is never mentioned, and so human analysis is necessary to diagnose the root cause.
Write to file
To write output to a file-like object (anything that can be passed to the
file=
argument of print
), pass it as the out=
argument of Trace
.
import dlltracer
with open("log.txt", "w") as log:
with dlltracer.Trace(out=log):
import module_to_trace
Collect to list
To collect events to an iterable object, pass collect=True
to Trace
and
bind the context manager. The result will be a list containing event objects,
typically dlltracer.LoadEvent
and dlltracer.LoadFailedEvent
.
import dlltracer
with dlltracer.Trace(collect=True) as events:
try:
import module_to_trace
except ImportError:
# If we don't handle the error, program will exit before
# we get to inspect the events.
pass
# Inspect the events after ending the trace
all_loaded = {e.path for e in events if isinstance(e, dlltracer.LoadEvent)}
all_failed = {e.path for e in events if isinstance(e, dlltracer.LoadFailedEvent)}
Raise audit events
To raise audit events for DLL loads, pass audit=True
to Trace
. The events
raised are dlltracer.load
and dlltracer.failed
, and both only include the
path as an argument.
import dlltracer
import sys
def hook(event, args):
if event == "dlltracer.load":
# args = (path,)
print("Loaded", args[0])
elif event == "dlltracer.failed":
# args = (path,)
print("Failed", args[0])
sys.add_audit_hook(hook)
with dlltracer.Trace(audit=True):
import module_to_trace
Additional events
Note: This is mainly intended for development of dlltracer
.
Because event formats may change, and additional events may be of interest but
are not yet handled, passing the debug=True
option to Trace
enables all
events to be collected, written, or audited. Regular events are suppressed.
import dlltracer
import sys
def hook(event, args):
if event != "dlltracer.debug":
return
# args schema:
# provider is a UUID representing the event source
# opcode is an int representing the operation
# header is bytes taken directly from the event header
# data is bytes taken directly from the event data
provider, opcode, header, data = args
sys.add_audit_hook(hook)
with dlltracer.Trace(debug=True, audit=True, collect=True, out=sys.stderr) as events:
try:
import module_to_trace
except ImportError:
pass
for e in events:
assert isinstance(e, dlltracer.DebugEvent)
# DebugEvent contains provider, opcode, header and data as for the audit event
Contribute
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for dlltracer-1.0.3a1-cp313-cp313-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f1e9ee87b88631d3585b99e7587ba7fcb4c09e42ec8aa0391ee5a340ed089599 |
|
MD5 | 3d26c42ee4e6edc33c87d3595f6222b8 |
|
BLAKE2b-256 | 454afe65cfbee6a91f4fce9bfa377dbeee589815210e219785adf1788366ba83 |
Hashes for dlltracer-1.0.3a1-cp312-cp312-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ac5639c4aaa70cb591950051cd96f4dc428e8d28b7d9ae0384c2dd7ae0322109 |
|
MD5 | 5596887ec3d2b459bf4f7c29c5372efa |
|
BLAKE2b-256 | 10b2f9fbd83c919c67b3c1427958f1f3bbad454d535428fbad10b7ca4d787e81 |
Hashes for dlltracer-1.0.3a1-cp311-cp311-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4cfc78e07310c39d38e042be860c363c5ec7556087b841866084757392a625ba |
|
MD5 | 9265301fabc2452283a1c04748b7bcec |
|
BLAKE2b-256 | b7de5bc4f68da2f31e41cb6705cbbc08d6fc2d23500b06593c9bb1db7e704b3f |
Hashes for dlltracer-1.0.3a1-cp310-cp310-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 32330f6b624197ec1e348a7abfd8b85fb025cba8c36b03ba82c41925234417c0 |
|
MD5 | 1336953ada2a149eacf53e87eb184fa8 |
|
BLAKE2b-256 | 73fd7834711f315bf5ebcd238ab21d4f531c989d697aec049083477bdcc366fa |
Hashes for dlltracer-1.0.3a1-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ec69277131873c3177f9473ed4e387caf15b23da30670fa815cd9de003ab6752 |
|
MD5 | 5a25ff8c1cf4483d2c6f81166ab2b83c |
|
BLAKE2b-256 | 0a784fe8f01a0e1715975793bf4dc4f76c81c31d838671ed893cad47bfd10766 |
Hashes for dlltracer-1.0.3a1-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fe835d1330ae4853cf5c543e91ea9281d76681c20196d14cfbb76bf864e29dfd |
|
MD5 | 25e38435693f7fe090042cbaae168b85 |
|
BLAKE2b-256 | 7e6c9af9b6ed8ae085761e3b9c30f15d736936eada8bbbf34e92312c589aaadc |