Observability & Logging
Hive provides a structured, three-tier observability system designed to track autonomous agent behavior from high-level goal completion down to individual tool invocations. This architecture ensures that even when agents "self-improve" or evolve their workflows, every decision remains traceable and auditable.
The Three-Level Logging System
Hive categorizes runtime data into three distinct levels of granularity. These logs are OTel-aligned (OpenTelemetry), featuring trace_id and span_id fields to support future integration with distributed tracing platforms.
Level 1: Run Summary
The Summary level provides a high-level overview of a full graph execution. It is used for monitoring agent performance, success rates, and total resource consumption.
- Model:
RunSummaryLog - Key Data: Status (success/failure/degraded), total token counts, execution duration, and the specific node path taken through the graph.
- Attention Flags: Includes a
needs_attentionflag andattention_reasonsto highlight runs that require human review.
Level 2: Node Details
The Details level tracks the lifecycle of individual nodes within a run. This is essential for identifying bottlenecks or specific points of failure in a multi-agent workflow.
- Model:
NodeDetail - Key Data: Node-specific success/failure, retry attempts, and granular token usage.
- Execution Metadata: Captures
exit_status(e.g.,stalled,escalated,guard_failure) and counts for loop iterations (accepts vs. retries).
Level 3: Tool & Step Logs
The Tool Logs level is the most granular, capturing every interaction between the LLM and the environment. This is the primary tool for debugging "hallucinations" or tool-calling errors.
- Model:
NodeStepLog&ToolCallLog - Key Data: The raw LLM text output, specific tool inputs, and the returned tool results.
- Error Tracking: Captures full stack traces and identifies "partial" steps where an execution was interrupted.
# Example of a Level 3 Tool Call Log
ToolCallLog(
tool_name="view_file",
tool_input={"path": "src/main.py", "session_id": "sess_123"},
result="File content...",
is_error=False
)
Real-Time Observability with the TUI
For interactive development, Hive includes a Textual-based Terminal User Interface (TUI) that visualizes agent execution in real-time.
Graph Monitoring
The GraphOverview widget displays the agent's node graph. It uses visual indicators to show the current execution state:
- Active (●): The node currently being processed by the LLM or a function.
- Completed (✓): Nodes that have finished execution successfully.
- Terminal (■): End states for the current agent goal.
Execution Streaming
The LogPane and StatusBar provide live updates on:
- Active Node Details: What the agent is doing at this exact moment (e.g., "Thinking", "Searching").
- Latency: Real-time clock showing how long the current run has been active.
- Chat History: A synchronized view of the conversation between the user and the agent.
Security and Privacy in Logs
Hive is built to handle sensitive data. The logging system incorporates several safeguards:
- Secret Masking: Using Pydantic’s
SecretStr, sensitive values like API keys and OAuth tokens are automatically masked in logs to prevent accidental exposure in console output or log files. - Sandbox Isolation: File system logs are scoped to specific
workspace_idandsession_idcontexts, ensuring that observability data does not leak across different agent environments.
CLI Configuration
When running agents via the CLI, you can control the logging verbosity using standard flags:
- Default: Shows warnings and high-level progress.
- Verbose (
-v): Enables Level 1 and Level 2 logging (Info level). - Debug (
--debug): Enables Level 3 logging, including raw LLM prompts and full tool interaction traces.
# Run an agent with full debug logging for tool calls
python -m framework run --topic "Market Research" --debug
Programmatic Access
All logs are available programmatically through the AgentRuntime. Developers can hook into the EventBus to export these logs to external databases, monitoring stacks, or custom dashboards.
| Event Type | Description |
| :--- | :--- |
| EXECUTION_STARTED | Triggered when a node begins processing. |
| EXECUTION_COMPLETED | Triggered when a node finishes, providing the NodeDetail. |
| STEP_COMPLETED | Triggered after every tool call or LLM turn (Level 3 data). |