Skip to content

Commit 8c7b161

Browse files
committed
Document async-related limitations
Also document async-related limitations for the Python SDK, similar to Java (Dynatrace/OneAgent-SDK-for-Java#32)
1 parent 29ea314 commit 8c7b161

File tree

1 file changed

+17
-0
lines changed

1 file changed

+17
-0
lines changed

README.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,23 @@ exception message (if you do not want or need this behavior, tracers have
222222
explicit methods for starting, ending and attaching error information too; see the
223223
[documentation](https://dynatrace.github.io/OneAgent-SDK-for-Python/docs/sdkref.html#oneagent.sdk.tracers.Tracer)).
224224

225+
A Tracer instance can only be used from the thread on which it was created.
226+
Whenever you start a tracer, the tracer becomes a child of the previously active tracer
227+
on this thread and the new tracer then becomes the active tracer. You may only end the active tracer.
228+
If you do, the tracer that was active before it (its parent) becomes active again.
229+
Put another way, tracers must be ended in reverse order of starting them
230+
(you can think of this being like HTML tags where you must also close the child tag before you can close the parent tag).
231+
While the tracer's automatic parent-child relationship works very intuitively in most cases,
232+
it does not work with **asynchronous patterns**, where the same thread handles multiple logically
233+
separate operations in an interleaved way on the same thread. If you need to instrument
234+
such patterns with the SDK, you need to end your tracer before the thread is potentially reused
235+
by any other operation (e.g., before yielding to the event loop). To later continue the trace,
236+
capture an in-process link before and later resume using the in-process link tracer, as explained in
237+
[Trace in-process asynchronous execution](#trace-in-process-asynchronous-execution). This approach is rather awkward and
238+
may lead to complex and difficult to interpret traces. If your application makes extensive use of
239+
asynchronous patterns of the kind that is difficult to instrument with the SDK, consider using
240+
the [OpenTelemetry support of Dynatrace](https://www.dynatrace.com/support/help/shortlink/opent-python) instead.
241+
225242
There are different tracer types requiring different information for creation.
226243
As an example, to trace an incoming remote call, this would be the most simple
227244
way to trace it:

0 commit comments

Comments
 (0)