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_attention flag and attention_reasons to 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_id and session_id contexts, 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.