NeatlogsChatbot Sessions
Group multi-turn chatbot traces into a single session with auto_session=True.
This guide shows how to instrument a multi-turn chatbot so every conversation turn appears as its own trace, and all turns for a session are grouped together in the dashboard.
Setup
Pass auto_session=True to neatlogs.init(). The SDK generates a single session ID at startup and attaches it to every trace for the lifetime of the process:
import os
import neatlogs
neatlogs.init(
api_key=os.environ["NEATLOGS_API_KEY"],
endpoint=os.environ["NEATLOGS_ENDPOINT"],
workflow_name="support-chatbot",
instrumentations=["openai"],
auto_session=True,
)
from openai import OpenAI
client = OpenAI()Instrument the Agent
Decorate the per-turn agent function with @neatlogs.span(kind="AGENT"). Each time this function is called it produces one trace. Because auto_session=True was set at init, all those traces share the same session ID automatically:
from neatlogs import PromptTemplate, UserPromptTemplate
system_tpl = PromptTemplate([
{"role": "system", "content": "You are a helpful support assistant. Use the conversation history to give consistent answers."},
])
user_tpl = UserPromptTemplate([
{"role": "user", "content": "{{message}}"},
])
@neatlogs.span(kind="AGENT", name="chatbot_turn")
def chatbot_turn(message: str, history: list) -> str:
with neatlogs.trace("respond", kind="LLM",
prompt_template=system_tpl,
user_prompt_template=user_tpl):
system_msgs = system_tpl.compile()
user_msgs = user_tpl.compile(message=message)
messages = system_msgs + history + user_msgs
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
)
return response.choices[0].message.contentRun a Multi-Turn Conversation
Each call to chatbot_turn is a separate trace. No manual wrapping is needed — session grouping is handled by the SDK:
history = []
while True:
user_input = input("You: ")
if user_input.lower() in ("exit", "quit"):
break
reply = chatbot_turn(user_input, history)
print(f"Bot: {reply}")
history.append({"role": "user", "content": user_input})
history.append({"role": "assistant", "content": reply})
neatlogs.flush()
neatlogs.shutdown()What You'll See in the Dashboard
A session timeline showing all conversation turns in order. Each turn is an individual trace with its own AGENT span and LLM sub-span. All traces share the same session ID, so the dashboard groups them under one session view.