Traceability

Traceability & Observability

AI-Horizon includes built-in trace observability and transaction monitoring features. Using the Traceability logs, developers can inspect execution spans, monitor agent workflows, count token usages, compute execution costs, and review raw trace logs.

Observability Features

  • Nested Execution Spans: Details parent-child events in execution pipelines (e.g. parent POST requests calling children LLM completions, Weaviate searches, etc.).
  • Latency & Duration Reporting: Tracks precisely when events started and ended, computing exact time elapsed (in seconds or milliseconds).
  • Cost & Token Auditing: Aggregates prompt and completion tokens, displays the associated cost calculations, and exposes overall session cost summaries.
  • Trace Export Files: Generates isolated, shareable HTML trace logs (/logs/trace_report.html) showing complete execution timelines.

Programmatic Tracing APIs

The Traceability system exposes the following REST APIs to read trace execution files directly:

1. Read Trace File (GET /api/read-trace-file)

Retrieves detailed trace files (.jsonl format) from the server's disk storage.

  • Request Query Parameter:

    • trace_id: String trace identifier.

  • Response:

    {
  "trace_id": "trace-uuid-777",
  "spans": [
    {
      "span_id": "span-1",
      "parent_id": null,
      "name": "AgentRequest:/api/pdfchatBotResponse",
      "run_type": "pipeline",
      "duration": 2.45,
      "status": "SUCCESS",
      "token_usage": {
        "prompt_tokens": 1250,
        "completion_tokens": 250,
        "total_tokens": 1500
      },
      "metadata": {
        "path": "/api/pdfchatBotResponse"
      }
    }
  ]
}

2. Fetch Unified Bot History (GET /api/unified-bot-history)

Returns historical trace logs across all active agent types (PDF, Docx, Text, YouTube, Web page, Video, Voice, etc.).

  • Response: 
    [
  {
    "_id": "run-id-123",
    "agentType": "PDFChatBot",
    "createdAt": "2026-07-31T11:03:32Z",
    "response": {
      "Session_Details": {
        "Session ID": "session-uuid-999",
        "Overall_Status": "Success",
        "overall_time_elapsed": "0h 0m 2.45s",
        "overall_cost": 0.045,
        "overall_tokens": {
          "prompt": 1250,
          "completion": 250,
          "total": 1500
        }
      }
    }
  }
]
ExamplesOverview & Drilldown