[core] Add module import hook install logic

[Kyle-Verhoog]

Overview

This PR adds the required logic necessary for installing module import hooks.

Now integrations can register their patch functions to be run when the required module is imported. This means that integrations can be certain of being the first to run after the code is imported.

What this looks like for integrations (with gevent as the example). In gevent/__init__.py:

def _patch(gevent):
    # install logic that will be run when module is imported

def patch():
    # install the module import hook to patch gevent on module import
    install_module_import_hook('gevent', _patch)

def unpatch():
    # uninstall logic...
    # remove import hook if it exists
    uninstall_module_import_hook('gevent')

Caveats

This approach uses wrapt's module import hooking system which deletes the hooks after they are run. This isn't desirable for our use-case even though it's highly unlikely that modules will be reimported or deleted. Another undesired effect of using wrapt is that we cannot uninstall module import hooks and have to import wrapt privates to do so. While it is overkill for this PR to introduce our own meta-path managing it is something we will have to move to long term.

[brettlangdon]

While it is overkill for this PR to introduce our own meta-path managing it is something we will have to move to long term.

I wonder if we shouldn't just do this first? It feels like we are setting ourselves up for failure here.

We might not see an edge case where this is a problem right now, but a customer will definitely find one for us... especially if we already can see this being an issue in the future.

[Kyle-Verhoog]

I don't think we're quite setting ourselves up for failure since this is quite an edge-case (most modules break or have undefined behaviour when reimported/deleted and imported again). Plus there is the fact that our current patching does not account for reimports so the functionality is the same from the user's perspective (they would have to call ddtrace.patch(module=True) again after deleting the module.

With that said, it's something we're going to change out eventually so it's worth considering not introducing it in the first place. I will investigate bringing in the core pieces of wrapt or importhook with the modification that give us what we want from the start.

[brettlangdon]

Fair enough. My only concern here is if we know what we probably need, if we hold off on it, will we ever implement it?

[brettlangdon]

Mostly looks good.

It is probably worth having a test case where we setup a non-dd import hook and mess with importing and install/uninstall to ensure we don't mess with the default behavior of wrapt. Just in case someone is using dd-trace-py along with wrapt.register_post_import_hook

[brettlangdon]

a few minor comments

[brettlangdon]

do we need a test case for installing a module hook twice?

we should probably try to deduplicate functions being registered for a module.

[brettlangdon]

@Kyle-Verhoog I'll take it from here

[Kyle-Verhoog]

@brettlangdon #769 took out the hook logic from this PR. This PR is now focused on adding the API in which integrations will use the import hook system.