Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.langsight.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Usage

langsight sessions [OPTIONS]

​
Options

OptionDefaultDescription
--configauto-discoveredPath to .langsight.yaml
--window, -w24hLook-back window (24h, 7d, 30d)
--agent, -aall agentsFilter 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
--jsonfalseOutput 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
Filter by health tag: 
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
Legend:
  • 🤖 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
Returns a JSON array of session objects: 
[
  {
    "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"
  }
]
For a single session with --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"})
See the SDK quickstart and the Python SDK guide for full setup instructions.

​
Storage backend

BackendSessions supportNotes
dual (default)YesFull support — Postgres metadata + ClickHouse mv_agent_sessions
clickhouse onlyYesFull support — mv_agent_sessions materialized view pre-aggregates session metrics
postgres onlyNoNo session aggregation without ClickHouse
Start the full stack with 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.