docs(insight): correct two rationales, note drain latency

The log filter's bind_invocation took a process-global lock on every
operation-start and user-function-start hook although the work is idempotent
after the first call on a thread. It now returns early when the thread
already carries this provider's claim.

Two comments described an ordering the SDK prevents. Insight's lock said a
checkpoint-path operation-change "genuinely races" the invocation-end hook;
the SDK joins the checkpoint thread and the branch pools before that hook is
dispatched. The lock stays -- it is what makes reentrancy from customer code
inside a build safe, and a guard resting on the SDK's join ordering is one
refactor from being wrong -- but the comment now says which of the two it is.

The Insight README documents what the invocation-end drain costs under
concurrency: it waits for every record any execution had pending, and one
worker serializes every export and flush, so ends are released together at
the slowest. Measured with a 30 ms exporter: ~72 ms at one execution, ~1.8 s
each at 48.

Author: ParidelPooya

packages/aws-durable-execution-sdk-python-insight/README.md

@@ -230,6 +230,19 @@ Behavior is validated cross-SDK by the `insight` conformance suite
 > cadence the JS and Java plugins have. Only a sampled-out execution neither
 > exports nor flushes.
 
+> **Note (invocation-end latency under concurrency).** The drain an invocation
+> end performs waits for every record any execution had pending when it was
+> called, and one worker serializes all exports and all flushes, so every
+> concurrently ending invocation is released together at the slowest one. The wait
+> therefore grows with the number of executions the environment is running, not
+> just with this execution's own work: measured with a 30 ms exporter, one
+> execution ended in ~72 ms and 48 concurrent executions in ~1.8 s each. That is
+> the deliberate trade against the alternative — releasing an end before its
+> record reached the exporters, which is what silently lost terminal records
+> before. It matters for an exporter that makes a network call per record: budget
+> invocation-end time against the environment's concurrency, not against one
+> execution.
+
 ## Requirements
 
 - `aws-durable-execution-sdk-python` with the plugin invocation hooks that

packages/aws-durable-execution-sdk-python-insight/src/aws_durable_execution_sdk_python_insight/plugin.py

@@ -281,11 +281,16 @@ def __init__(
         self._build_revision = 0
         # Guards `_closed`, `_build_revision`, the operations rebind and record
         # emission, so a late hook can never slip a RUNNING record in after the
-        # terminal one. Still earns its place with one instance per invocation: the
-        # SDK dispatches every hook synchronously on the thread that produced the
-        # event, so an operation-change raised off the checkpointing path runs
-        # concurrently with the invocation thread's on_invocation_end -- two hooks,
-        # one instance, genuinely racing.
+        # terminal one.
+        #
+        # What it protects against is reentrancy, not two threads. The SDK
+        # dispatches every hook synchronously on the thread that produced the
+        # event, and it joins the checkpoint thread and the branch pools before
+        # the invocation-end hook is dispatched, so a checkpoint-path
+        # operation-change cannot overlap `on_invocation_end` -- an earlier
+        # version of this comment claimed it could. The lock still earns its place
+        # for the reason below, and it stays because a guard whose correctness
+        # rests on the SDK's join ordering is one refactor away from being wrong.
         #
         # Reentrant on purpose: `_emit` runs the scheduler's `schedule()` inside
         # this hold, and `schedule()` releases the record it displaces, which can

packages/aws-durable-execution-sdk-python-otel/src/aws_durable_execution_sdk_python_otel/log_filter.py

@@ -132,9 +132,17 @@ def bind_invocation(provider: _SpanContextProvider) -> None:
     executing user code. Idempotent, so a plugin can call it from every such
     hook without tracking which threads it has already claimed.
 
+    A thread that already carries this provider's claim returns before taking the
+    registry lock. Every operation-start and user-function-start hook calls this,
+    and after the first call on a thread there is nothing to add: membership in
+    the open-invocation set is idempotent, and the claim is already in place.
+
     Args:
         provider: The plugin serving the invocation that owns this thread.
     """
+    claim = _current_invocation.get()
+    if claim is not None and claim() is provider:
+        return
     with _registry_lock:
         _open_invocations.add(provider)
     _current_invocation.set(weakref.ref(provider))