> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bothive.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability & Traces

> Every Bothive run produces a full trace. No more debugging blind.

## What you can inspect

<CardGroup cols={2}>
  <Card title="Run Executions" icon="play" className="glass-effect">
    Every message processed by any bot — time, channel, user, status, cost.
  </Card>

  <Card title="Tool Calls" icon="plug" className="glass-effect">
    Exactly which tools were called, with what arguments, and what was returned.
  </Card>

  <Card title="Latency Breakdown" icon="clock" className="glass-effect">
    Per-step latency: memory load time, model inference time, tool execution time.
  </Card>

  <Card title="Memory Reads & Writes" icon="database" className="glass-effect">
    What was read from memory, what was written, and what was missing.
  </Card>

  <Card title="Error Details" icon="triangle-exclamation" className="glass-effect">
    Full error messages, stack traces for integration failures, model errors.
  </Card>

  <Card title="End-User Sessions" icon="users" className="glass-effect">
    Filter by user ID to see all their runs — useful for per-user debugging.
  </Card>
</CardGroup>

## Anatomy of a trace

Every run produces a structured trace you can open in the dashboard:

<Steps>
  <Step title="Input">
    The raw user message, channel it came from, and the session ID.
  </Step>

  <Step title="Context loaded">
    What memory was injected — conversation history, persistent keys, user profile.
  </Step>

  <Step title="Model selected">
    Which model was routed to and why — based on agent config or dynamic routing rules.
  </Step>

  <Step title="Tool decision">
    If a tool was selected: which tool, the arguments sent, the raw response returned.
  </Step>

  <Step title="Response generated">
    The final output, token count, and cost.
  </Step>

  <Step title="Memory updated">
    Any memory keys that were written during this turn.
  </Step>

  <Step title="Run metadata">
    Total latency, status (success/error/timeout), channel, timestamp.
  </Step>
</Steps>

## Debugging workflow

<Steps>
  <Step title="Find the failing run">
    Open **Runs** in your bot dashboard. Filter by status: `error`, `timeout`, or `tool_failure`.
  </Step>

  <Step title="Open the trace">
    Click any run to see the full trace tree. Expand each step to see input/output at that stage.
  </Step>

  <Step title="Identify the issue">
    Common issues:

    * Wrong tool selected → Update instructions to be more specific
    * Tool returned null → Check integration credentials
    * Model hallucinated → Add explicit rules to instructions
    * Context window overflow → Switch to `summarized` memory
  </Step>

  <Step title="Use HiveMind Debug">
    Click **Debug with HiveMind** on any run. The AI will read the trace and suggest what to fix.
  </Step>

  <Step title="Fix and redeploy">
    Update your agent config or HiveLang file. Changes deploy instantly.
  </Step>
</Steps>

## Bothive Observability vs LangSmith

<Note>
  LangSmith is a serious observability and evaluation platform for LLM applications and agents. Bothive's observability is different: it sits inside the same product surface where the agent is built, deployed, changed, and operated.
</Note>

| Feature                  | Bothive                                               | LangSmith                                                                      |
| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Primary job**          | Operate Bothive-hosted bots and agent runs            | Trace, monitor, evaluate, and improve LLM applications                         |
| **Setup path**           | Included in the bot console for Bothive runs          | Add LangSmith to your app/framework stack                                      |
| **Framework support**    | Focused on Bothive runtime surfaces                   | Works with many frameworks and providers, including LangChain and other stacks |
| **Tool call visibility** | Bot run traces and tool/action metadata               | Full traces, runs, dashboards, and monitoring                                  |
| **Evaluation depth**     | Foundations exist; release gates still need hardening | Core product strength: datasets, experiments, evaluators, monitoring           |
| **Memory visibility**    | Bot memory and knowledge surfaces are product pages   | Trace/eval platform rather than a product memory console                       |
| **Deployment tie-in**    | Same platform as bot deployment and changes           | Separate observability/evals product                                           |

Use LangSmith when you need a dedicated observability and evaluation platform across your AI stack. Use Bothive observability when the agent is hosted and operated inside Bothive and you want traces connected to bot configuration, channels, memory, and changes.

## Observability in Swarms

When running multi-agent swarms, each agent's trace is nested under the swarm run:

```
Swarm: ResearchTeam [run_abc123]
  └── Agent: Scout [run_xyz789]
       ├── tool: web.search(query="AI trends 2025")
       └── result: [10 sources]
  └── Agent: Analyst [run_def456]
       ├── memory.read: last_sources
       └── response: "Based on 10 sources..."
```

You can drill into any agent's sub-trace independently.

## Alerting

Set up run-level alerts in your bot settings:

| Alert Type             | Trigger                            |
| ---------------------- | ---------------------------------- |
| **High error rate**    | >10% of runs fail in 1 hour        |
| **Slow latency**       | P95 latency exceeds your threshold |
| **Tool failure spike** | A specific tool fails repeatedly   |
| **Unusual usage**      | Sudden spike in runs per user      |

Alerts can be delivered to Slack, email, or a webhook endpoint.

## Next reads

<CardGroup cols={3}>
  <Card title="Architecture" icon="layer-group" href="./architecture" className="glass-effect" />

  <Card title="Deployment Guide" icon="rocket" href="../guides/deployment-guide" className="glass-effect" />
</CardGroup>