Sessions

A session groups multiple traces from the same conversation together in the dashboard. Without a session, each agent invocation appears as an isolated trace. With a session, all traces from a single user conversation are linked and viewable as a timeline.

When to Use Sessions

Sessions are useful for multi-turn applications — chatbots, voice assistants, or any app where a user sends multiple messages and each message triggers a new agent run.

In a single-run script or batch job, sessions add no value.

auto_session

For chatbots and short-lived processes (one process = one conversation), pass auto_session=True to neatlogs.init(). The SDK generates a unique session ID at startup and attaches it to every trace automatically:

neatlogs.init(
    api_key=os.environ["NEATLOGS_API_KEY"],
    endpoint=os.environ["NEATLOGS_ENDPOINT"],
    workflow_name="support-chatbot",
    auto_session=True,
)

Each top-level with neatlogs.trace("turn"): block creates a new root trace (because no active parent span exists), and all traces share the same auto-generated session ID:

# Turn 1
with neatlogs.trace("turn_1"):
    agent.run("How do I reset my password?")

# Turn 2
with neatlogs.trace("turn_2"):
    agent.run("Thanks, but the link isn't working")

Both traces appear in the dashboard grouped under the same session.

Custom session_id

If you want to supply your own session identifier — for example, when you already have a conversation ID in your system — pass session_id to init() instead:

neatlogs.init(
    api_key=os.environ["NEATLOGS_API_KEY"],
    endpoint=os.environ["NEATLOGS_ENDPOINT"],
    workflow_name="support-chatbot",
    session_id=f"conv_{conversation_id}",
)

The same with neatlogs.trace("turn_n"): pattern then applies — each top-level trace block becomes a new trace under your custom session ID.