[Bug] Python agent’s @runnable does not behave as expected #11605

Activity

1. xlq20080808

   added

   bugSomething isn't working and you are sure it's a bug!Something isn't working and you are sure it's a bug!

   on Nov 28, 2023
2. wu-sheng

   added

   pythonPython agent relatedPython agent related

   on Nov 28, 2023
3. wu-sheng

   assigned

   kezhenxu94

   and

   Superskyyy

   on Nov 28, 2023
4. wu-sheng

   added

   pluginPlugin for agent or collector. Be used to extend the capabilities of default implementor.Plugin for agent or collector. Be used to extend the capabilities of default implementor.

   on Nov 28, 2023
5. wu-sheng

   added this to the python - 1.3.0 milestone on Apr 12, 2026
6. wu-sheng

   self-assigned this

   on Apr 12, 2026
7. wu-sheng

   added a commit that references this issue on Apr 12, 2026

   feat: add sw_threading plugin for automatic cross-thread context prop…

   ...

   This issue will close once commit 8b5df98 is merged into the 'master' branch.

   8b5df98
8. wu-sheng commented on Apr 12, 2026

   

   wu-sheng

   on Apr 12, 2026

   Last edited by wu-sheng

   Member

   More actions

   Root Cause

   The @runnable decorator captured the snapshot at decoration time (decorator() scope), not at execution time:

   def decorator(func):
       snapshot = get_context().capture()  # runs when @runnable is applied

   When @runnable is applied at module level (the natural Python pattern shown in the issue):

   @runnable(op="/post")
   def post():
       ...

   get_context().capture() runs at import time — no active trace exists, so snapshot is None. Later when the child thread runs, context.continued(None) is a no-op, and the cross-thread trace link is lost.

   The existing test used @runnable inline inside a request handler, where the trace context was active at decoration time — that's why it passed.

   How to write it to work (current version)

   Define and decorate the function inside the request handler:

   @app.route("/")
   def hello():
       @runnable(op="/post")  # decorated during request, snapshot is valid
       def post():
           ...
       thread = Thread(target=post)
       thread.start()
       return "ok"

   Fix: continue_tracing() API (apache/skywalking-python#391)

   @runnable now returns a wrapper object with a continue_tracing() method. Call it on the parent thread to capture the snapshot at the right moment:

   from skywalking.decorators import runnable
   
   @runnable(op="/post")
   def post():
       requests.post('http://provider:9091/users')
   
   @app.route("/")
   def hello():
       thread = Thread(target=post.continue_tracing())  # snapshot captured here
       thread.start()
       return "ok"

   • post.continue_tracing() — called on the parent thread during the request, captures the snapshot, returns a callable that propagates the trace context to the child thread via CrossThread reference
   • post() — direct call still works as before (local span + decoration-time snapshot), fully backward compatible

   The inline pattern also continues to work unchanged:

   @app.route("/")
   def hello():
       @runnable(op="/post")  # snapshot captured here, during the request
       def post():
           ...
       thread = Thread(target=post)  # no change needed
       thread.start()
       return "ok"

   No global monkey-patching of threading.Thread is involved.
9. wu-sheng

   closed this as completedon Apr 12, 2026
10. wu-sheng

    added a commit that references this issue on Apr 12, 2026

    fix: support module-level @Runnable with continue_tracing() for cross…

    ...

    This issue will close once commit 10d5e18 is merged into the 'master' branch.

    10d5e18
11. wu-sheng

    modified the milestones: python - 1.3.0, Infra E2E 1.4.0 on Apr 12, 2026
12. wu-sheng

    added a commit that references this issue on Apr 12, 2026

    fix: support module-level @Runnable with continue_tracing() (#391)

    ...

    263a936