agentops.init() Not Creating Session Span by Default; start_session() Creates Sibling Span Without Context Propagation

[Dwij1704]

When calling agentops.init(), a session span is not created by default. This forces us to manually call agentops.start_session() to generate a session span. However, even when using agentops.start_session(), the generated session span is not propagated correctly and appears as a sibling span rather than as a parent of subsequent spans.

Steps to Reproduce:

1. Call agentops.init() without calling agentops.start_session().

   • Observation: No session span is created (see [trace](https://jaeger.agentops.cloud/trace/631a65b1dfeec4c30cddcc1e741876c2)).

2. Call agentops.start_session() after agentops.init().

   • Observation: A session span is created, but it becomes a sibling span and does not propagate the context to subsequent spans (see [trace](https://jaeger.agentops.cloud/trace/4eeb8f9c2487a5557a71b1b4f51c29b2)).

Expected Behavior:

• A call to agentops.init() should automatically create a session span, or at least the manual call to agentops.start_session() should correctly propagate the session context so that the session span is the parent for subsequent spans.

[bboynton97]

used to have agentops.init(auto_start_session=False) and then later agentops.start_session()

expected behavior is if you call both without auto_start_session=False then two traces start

[tcdent]

Digging into this:

Framework instrumentation (like openai_agents and crewai) create a root span for the "workflow" internally.

LLM instrumentation simply creates spans for the API calls.

Both get assigned to the trace correctly. It is up to the framework instrumentation to nest it's spans correctly, which the two mentioned seem to do. LLM calls end up as flat spans on the trace.

Since this context handling is left up to the instrumentation, we don't have any internal management for it. The opentelemetry.context API provides a way to reference spans IDs across processes, but doesn't provide references to the actual Span instances.

We would need to create a root span inside of TracingCore and update all instrumentation to expect to export their spans as children of that node. This would break compatibility with any third party instrumentation and require that instrumentation references functionality of agentops instead of opentelemetry.

Since instrumentation creates and manages it's root span, this is really just an issue with raw LLM calls as far as I can tell. And, since they're not part of a formal "workflow" as in the use a of a framework, it seems like leaving them as root spans makes sense.

We should ensure that starting and ending a session using the legacy API behaves as expected. start_session and end_session are not part of the v4 public API, so we should discuss wether adding continued support for that is worth the effort.

[bboynton97]

reopening because no PR was closed to fix this. @Dwij1704 is investigating further (<3)

[Dwij1704]

In the current implementation, calling agentops.init() generates a session span, but this span is not automatically flushed or ended.

In contrast, the agentops.start_session() method not only generates a session span but also ensures that it is flushed (ended) as soon as it is generated. This guarantees that the session data is recorded and exported immediately, providing a complete and reliable session lifecycle.

Updates needed:

• Set auto_start_session True by default in init(), Even by setting auto_start_session True, it doesn't flush the span (needs debugging), this should generate and flush span just like start_session().
• User can either use

import agentops
agentops.init(tags=['test'])

or

import agentops
agentops.init(auto_start_session=False)
agentops.start_session(tags=['test'])

[Dwij1704]

The underlying issue was from incomplete OpenTelemetry context management during session span creation, particularly when using start_session() after init(auto_start_session=False) and init(). Session spans were being created but lacked proper context initialization, resulting in the OpenTelemetry span lifecycle never completing – spans were started but their on_end events weren't firing, leading to spans not being properly exported. The fix implements proper context initialization for root spans, ensuring session spans are created with valid contexts regardless of creation method. By optimizing span creation logic to handle sessions as special root spans, implementing a centralized session registry, and adding reliable shutdown mechanisms with proper error recovery, we've ensured the complete span lifecycle from creation through finalization. This guarantees that all session data is properly recorded, finalized, and exported.