Better explain which context the task is run in when using run_in_background(...) or run_as_background_process(...) (#18906)

Follow-up to https://github.com/element-hq/synapse/pull/18900

changelog.d/18906.misc

@@ -0,0 +1 @@
+Better explain how we manage the logcontext in `run_in_background(...)` and `run_as_background_process(...)`.

synapse/logging/context.py

@@ -802,8 +802,9 @@ def run_in_background(
     deferred returned by the function completes.
 
     To explain how the log contexts work here:
-     - When this function is called, the current context is stored ("original"), we kick
-       off the background task, and we restore that original context before returning
+     - When `run_in_background` is called, the current context is stored ("original"),
+       we kick off the background task in the current context, and we restore that
+       original context before returning
      - When the background task finishes, we don't want to leak our context into the
        reactor which would erroneously get attached to the next operation picked up by
        the event loop. We add a callback to the deferred which will clear the logging
@@ -828,6 +829,7 @@ def run_in_background(
     """
     calling_context = current_context()
     try:
+        # (kick off the task in the current context)
         res = f(*args, **kwargs)
     except Exception:
         # the assumption here is that the caller doesn't want to be disturbed

synapse/metrics/background_process_metrics.py

@@ -286,9 +286,11 @@ def run_as_background_process(
                 ).dec()
 
     # To explain how the log contexts work here:
-    #  - When this function is called, the current context is stored (using
-    #    `PreserveLoggingContext`), we kick off the background task, and we restore the
-    #    original context before returning (also part of `PreserveLoggingContext`).
+    #  - When `run_as_background_process` is called, the current context is stored
+    #    (using `PreserveLoggingContext`), we kick off the background task, and we
+    #    restore the original context before returning (also part of
+    #    `PreserveLoggingContext`).
+    #  - The background task runs in its own new logcontext named after `desc`
     #  - When the background task finishes, we don't want to leak our background context
     #    into the reactor which would erroneously get attached to the next operation
     #    picked up by the event loop. We use `PreserveLoggingContext` to set the