debug.go

Overview

The debug.go file defines the DebugAPIRouter type, which is responsible for setting up HTTP routes related to the Debug API within the system. This router provides RESTful endpoints primarily used for retrieving debug and tracing information about runtime events, sessions, and application user interactions. The file encapsulates the route definitions and associates them with handler functions implemented in the DebugAPIController.

This routing component fits into the broader routing infrastructure that organizes REST API endpoints by domain, as detailed in the Router Setup topic, and serves as part of the REST API server described in REST API and Web Launchers. It allows external clients and tools to query detailed debug data, supporting observability and troubleshooting workflows.

Types and Functions

DebugAPIRouter

type DebugAPIRouter struct {
	runtimeController *controllers.DebugAPIController
}

• Description:
  DebugAPIRouter is a router type encapsulating the routes for the Debug API endpoints. It holds a reference to a DebugAPIController, which implements the actual handler logic for debug-related HTTP requests.

• Fields:

  • runtimeController (controllers.DebugAPIController): The controller instance that processes debug API requests.

NewDebugAPIRouter

func NewDebugAPIRouter(controller *controllers.DebugAPIController) *DebugAPIRouter

• Description:
  Constructs a new DebugAPIRouter instance by injecting the given DebugAPIController.

• Parameters:

  • controller: A pointer to an existing DebugAPIController which handles all debug API operations.

• Returns:

  • A pointer to the instantiated DebugAPIRouter.

• Usage example:

  debugController := controllers.NewDebugAPIController(...)
  router := NewDebugAPIRouter(debugController)
  

(DebugAPIRouter) Routes

func (r *DebugAPIRouter) Routes() Routes

• Description:
  Returns a slice of Route structs defining the Debug API endpoints. Each route specifies the endpoint's HTTP methods, URL pattern, and the handler function.

• Returns:

  • Routes: A collection of Route objects representing the Debug API's HTTP routes.

• Defined Routes:

  Route Name	HTTP Method	URL Pattern	Handler Function	Notes
  GetTraceDict	GET	/debug/trace/{event_id}	runtimeController.TraceDictHandler	Retrieves trace dictionary for a given event ID.
  GetEventGraph	GET	/apps/{app_name}/users/{user_id}/sessions/{session_id}/events/{event_id}/graph	runtimeController.EventGraphHandler	Returns event graph visualization for a session event.
  GetSessionTrace	GET	/debug/trace/session/{session_id}	controllers.Unimplemented	Placeholder for session trace retrieval, not yet implemented.

• Usage example:

  The returned routes are typically registered with a HTTP router such as gorilla/mux during server initialization.

  debugRouter := NewDebugAPIRouter(debugController)
  for _, route := range debugRouter.Routes() {
      // Register route with HTTP server
      httpRouter.HandleFunc(route.Pattern, route.HandlerFunc).Methods(route.Methods...)
  }
  

Implementation Details

• The router uses the DebugAPIController from the controllers package to delegate actual request handling logic.

• Routes are defined using path parameters (e.g., {event_id}, {app_name}, {user_id}, {session_id}), leveraging the expressive routing capabilities of the underlying HTTP router (likely gorilla/mux).

• The GetSessionTrace endpoint is currently marked as unimplemented, represented by a generic handler controllers.Unimplemented, indicating a future feature extension.

• The routes primarily expose debug information such as trace dictionaries and event graphs, which are useful for analyzing and diagnosing the internal state and event flows in the system.

• The router focuses exclusively on GET routes, as debug data retrieval is read-only.

Interaction With Other System Components

• DebugAPIController:
  The router depends on this controller for business logic. The controller processes requests, interacts with backend services (e.g., session management, event tracing), and prepares responses. This aligns with the controller pattern used throughout the REST API as outlined in REST API Controllers.

• Session and Event Services:
  The debug endpoints use session and event identifiers in their URL patterns, implying integration with session management and event processing components documented in Session Management and Event Conversion and Processing.

• Routing Infrastructure:
  The DebugAPIRouter is one of several routers that collectively define the full API surface, as detailed in Router Setup. It is aggregated with other routers (runtime, sessions, artifacts, apps) into the main HTTP router.

• Clients:
  The endpoints exposed here serve debugging tools, developer interfaces, or automated systems that require detailed event inspection and trace visualization to monitor or troubleshoot the AI agent system.

Visual Diagram: DebugAPIRouter Structure

classDiagram
class DebugAPIRouter {
-runtimeController: DebugAPIController
+Routes()
}
class DebugAPIController {
+TraceDictHandler()
+EventGraphHandler()
+OtherDebugHandlers()
}
DebugAPIRouter --> DebugAPIController

This class diagram illustrates that DebugAPIRouter maintains a reference to a DebugAPIController instance and exposes routes that invoke the controller's handlers.

Summary of Routes and Their Purpose

Relation to Relevant Topics

• The routing definitions conform to the patterns and modular architecture described in Router Setup.

• Handlers implemented by the DebugAPIController operate as part of the REST API server framework in REST API and Web Launchers.

• The debug endpoints rely on session and event management logic as detailed in Session Management and Event Conversion and Processing.

• The file's role is to expose debugging capabilities for observability, linking to telemetry and tracing systems discussed in Telemetry and Observability.

This file is a core part of the system's debugging interface, enabling programmatic access to runtime traces and event data to support developers and operators in monitoring and troubleshooting the AI agent platform.