Usage
langsight sessions [OPTIONS]
Options
| Option | Default | Description |
|---|
--config | auto-discovered | Path to .langsight.yaml |
--window, -w | 24h | Look-back window (24h, 7d, 30d) |
--agent, -a | all agents | Filter sessions by agent name |
--health-tag | — | Filter by health tag (v0.3): success, loop_detected, budget_exceeded, tool_failure, circuit_breaker_open, timeout, schema_drift, success_with_fallback |
--id | — | Show full multi-agent trace tree for one session |
--json | false | Output as JSON |
langsight sessions requires the ClickHouse backend. The default storage mode dual includes ClickHouse — start it with docker compose up -d. If using mode: postgres only, the command prints: No session data found. Sessions require the ClickHouse backend. See docs for setup.
Session list
langsight sessions --window 7d
Agent Sessions (last 168h — 42 sessions)
────────────────────────────────────────────────────────────────────────────────────────────────────
Session ID Agent Calls Failed Health Duration Servers
a3f1c2b0-1e4d-4a8f-8c9d-7b2e5f0d1a6 research-agent 24 1 tool_failure 14.2s jira-mcp, confluence-mcp
b7e9d4c3-2f5e-4b9g-9d0e-8c3f6g1e2b7 data-pipeline 8 0 success 3.1s postgres-mcp
c1a2b3d4-3g6f-4c0h-0e1f-9d4g7h2f3c8 support-agent 31 3 loop_detected 22.8s jira-mcp, slack-mcp, s3-mcp
d5b6c7e8-4h7g-4d1i-1f2g-0e5h8i3g4d9 code-reviewer 12 0 success 5.6s github-mcp, postgres-mcp
e9c0d1f2-5i8h-4e2j-2g3h-1f6i9j4h5e0 research-agent 18 2 budget_exceeded 11.4s confluence-mcp, s3-mcp
langsight sessions --health-tag loop_detected
Single-session trace tree
Use --id to drill into a session and see the full multi-agent call tree:
langsight sessions --id a3f1c2b0-1e4d-4a8f-8c9d-7b2e5f0d1a6
Session a3f1c2b0 research-agent 24 calls 1 failed 14.2s
research-agent
├── 🤖 agent_start 0ms
├── 🔧 jira-mcp / search_issues ✓ 342ms
├── 🔧 jira-mcp / get_issue ✓ 89ms
├── 🔧 confluence-mcp / search ✓ 214ms
├── → handoff: research-agent → summarizer-agent
│ ├── 🤖 agent_start 0ms
│ ├── 🔧 confluence-mcp / get_page ✓ 178ms
│ ├── 🔧 confluence-mcp / get_page ✓ 163ms
│ └── 🤖 agent_end 1241ms
├── 🔧 jira-mcp / create_issue ✓ 411ms
├── 🔧 slack-mcp / post_message ✗ timeout 5000ms
│ └── error: connection timeout after 5000ms
└── 🤖 agent_end 14200ms
🤖 agent lifecycle span (start / end)🔧 tool call span→ handoff — agent-to-agent delegation✓ success, ✗ failure
Filter by agent
langsight sessions --agent research-agent --window 24h
JSON output
langsight sessions --json --window 7d
[
{
"session_id": "a3f1c2b0-1e4d-4a8f-8c9d-7b2e5f0d1a6",
"agent_name": "research-agent",
"first_call_at": "2026-03-17T09:14:02Z",
"last_call_at": "2026-03-17T09:14:16Z",
"tool_calls": 24,
"failed_calls": 1,
"duration_ms": 14200,
"servers_used": ["jira-mcp", "confluence-mcp", "slack-mcp"],
"health_tag": "tool_failure"
}
]
--id --json, the response includes the full span tree with parent_span_id fields.
Requirements
Sessions are recorded by the LangSight SDK or any OTLP-instrumented framework:
from langsight.sdk import LangSightClient
client = LangSightClient(url="http://localhost:8000")
mcp = client.wrap(
your_mcp_client,
server_name="jira-mcp",
agent_name="research-agent",
session_id="sess-f2a9b1",
)
result = await mcp.call_tool("search_issues", {"query": "refund policy"})
Storage backend
| Backend | Sessions support | Notes |
|---|
dual (default) | Yes | Full support — Postgres metadata + ClickHouse mv_agent_sessions |
clickhouse only | Yes | Full support — mv_agent_sessions materialized view pre-aggregates session metrics |
postgres only | No | No session aggregation without ClickHouse |
docker compose up -d (default mode: dual).
Dashboard features
The langsight sessions CLI shows a summary. For full session debugging, open the dashboard (port 3003):
- Session detail page — click any row in the Sessions table to open
/sessions/<id>
- Details tab — timeline + interactive lineage graph + node/edge inspector
- Input / Output panel (v0.13.1) — clicking an agent node in the session graph shows the human question and final answer in the right-side inspector panel, when
input= and sess.set_output() were used. See Capturing user input and agent output.
- Trace tab — nested span tree with inline payloads and LLM prompt/completion panels
- Handoff edges (v0.13.1) — handoff edges in the session graph are now derived exclusively from explicit
handoff spans. The previous cross-agent inference heuristic that could inflate edge counts with shared proxies has been removed.
- Incomplete badge (v0.14.1) — sessions where
input= was not passed to session() (LLM-only sessions with no captured human prompt) show a grey Incomplete badge in the health tag column instead of appearing as silent successes with 0 tool calls.
