From 232a30459babebece653795d136fb6516444ecf0 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Fri, 16 Feb 2024 12:56:39 -0800
Subject: [PATCH] DATASETTE_TRACE_PLUGINS setting, closes #2274

---
 datasette/plugins.py     | 24 ++++++++++++++++++++++++
 docs/writing_plugins.rst | 24 ++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/datasette/plugins.py b/datasette/plugins.py
index f7a1905f..3769a209 100644
--- a/datasette/plugins.py
+++ b/datasette/plugins.py
@@ -1,6 +1,7 @@
 import importlib
 import os
 import pluggy
+from pprint import pprint
 import sys
 from . import hookspecs
 
@@ -33,6 +34,29 @@ DEFAULT_PLUGINS = (
 pm = pluggy.PluginManager("datasette")
 pm.add_hookspecs(hookspecs)
 
+DATASETTE_TRACE_PLUGINS = os.environ.get("DATASETTE_TRACE_PLUGINS", None)
+
+
+def before(hook_name, hook_impls, kwargs):
+    print(file=sys.stderr)
+    print(f"{hook_name}:", file=sys.stderr)
+    pprint(kwargs, width=40, indent=4, stream=sys.stderr)
+    print("Hook implementations:", file=sys.stderr)
+    pprint(hook_impls, width=40, indent=4, stream=sys.stderr)
+
+
+def after(outcome, hook_name, hook_impls, kwargs):
+    results = outcome.get_result()
+    if not isinstance(results, list):
+        results = [results]
+    print(f"Results:", file=sys.stderr)
+    pprint(results, width=40, indent=4, stream=sys.stderr)
+
+
+if DATASETTE_TRACE_PLUGINS:
+    pm.add_hookcall_monitoring(before, after)
+
+
 DATASETTE_LOAD_PLUGINS = os.environ.get("DATASETTE_LOAD_PLUGINS", None)
 
 if not hasattr(sys, "_called_from_test") and DATASETTE_LOAD_PLUGINS is None:
diff --git a/docs/writing_plugins.rst b/docs/writing_plugins.rst
index 5c8bc4c6..2bc6bd24 100644
--- a/docs/writing_plugins.rst
+++ b/docs/writing_plugins.rst
@@ -7,6 +7,30 @@ You can write one-off plugins that apply to just one Datasette instance, or you
 
 Want to start by looking at an example? The `Datasette plugins directory <https://datasette.io/plugins>`__ lists more than 90 open source plugins with code you can explore. The :ref:`plugin hooks <plugin_hooks>` page includes links to example plugins for each of the documented hooks.
 
+.. _writing_plugins_tracing:
+
+Tracing plugin hooks
+--------------------
+
+The ``DATASETTE_TRACE_PLUGINS`` environment variable turns on detailed tracing showing exactly which hooks are being run. This can be useful for understanding how Datasette is using your plugin.
+
+.. code-block:: bash
+
+    DATASETTE_TRACE_PLUGINS=1 datasette mydb.db
+
+Example output::
+
+    actor_from_request:
+    {   'datasette': <datasette.app.Datasette object at 0x100bc7220>,
+        'request': <asgi.Request method="GET" url="http://127.0.0.1:4433/">}
+    Hook implementations:
+    [   <HookImpl plugin_name='codespaces', plugin=<module 'datasette_codespaces' from '.../site-packages/datasette_codespaces/__init__.py'>>,
+        <HookImpl plugin_name='datasette.actor_auth_cookie', plugin=<module 'datasette.actor_auth_cookie' from '.../datasette/datasette/actor_auth_cookie.py'>>,
+        <HookImpl plugin_name='datasette.default_permissions', plugin=<module 'datasette.default_permissions' from '.../datasette/default_permissions.py'>>]
+    Results:
+    [{'id': 'root'}]
+
+
 .. _writing_plugins_one_off:
 
 Writing one-off plugins