feat(traces): Add traces UI

Signed-off-by: Richard Palethorpe <[email protected]>

Author: richiejp

core/cli/run.go

@@ -79,6 +79,7 @@ type RunCMD struct {
 	MachineTag                         string   `env:"LOCALAI_MACHINE_TAG,MACHINE_TAG" help:"Add Machine-Tag header to each response which is useful to track the machine in the P2P network" group:"api"`
 	LoadToMemory                       []string `env:"LOCALAI_LOAD_TO_MEMORY,LOAD_TO_MEMORY" help:"A list of models to load into memory at startup" group:"models"`
 	EnableTracing                      bool     `env:"LOCALAI_ENABLE_TRACING,ENABLE_TRACING" help:"Enable API tracing" group:"api"`
+	TracingMaxItems                    int      `env:"LOCALAI_TRACING_MAX_ITEMS" default:"1024" help:"Maximum number of traces to keep" group:"api"`
 	AgentJobRetentionDays              int      `env:"LOCALAI_AGENT_JOB_RETENTION_DAYS,AGENT_JOB_RETENTION_DAYS" default:"30" help:"Number of days to keep agent job history (default: 30)" group:"api"`
 
 	Version bool
@@ -155,6 +156,11 @@ func (r *RunCMD) Run(ctx *cliContext.Context) error {
 		opts = append(opts, config.EnableTracing)
 	}
 
+	if r.EnableTracing {
+		opts = append(opts, config.EnableTracing)
+	}
+	opts = append(opts, config.WithTracingMaxItems(r.TracingMaxItems))
+
 	token := ""
 	if r.Peer2Peer || r.Peer2PeerToken != "" {
 		log.Info().Msg("P2P mode enabled")

core/config/application_config.go

@@ -20,6 +20,7 @@ type ApplicationConfig struct {
 	F16                                 bool
 	Debug                               bool
 	EnableTracing                       bool
+	TracingMaxItems                     int
 	GeneratedContentDir                 string
 
 	UploadDir string
@@ -90,6 +91,7 @@ func NewApplicationConfig(o ...AppOption) *ApplicationConfig {
 		Context:               context.Background(),
 		UploadLimitMB:         15,
 		Debug:                 true,
+		TracingMaxItems:       1024,
 		AgentJobRetentionDays: 30, // Default: 30 days
 		PathWithoutAuth: []string{
 			"/static/",
@@ -391,6 +393,12 @@ func WithDebug(debug bool) AppOption {
 	}
 }
 
+func WithTracingMaxItems(items int) AppOption {
+	return func(o *ApplicationConfig) {
+		o.TracingMaxItems = items
+	}
+}
+
 func WithGeneratedContentDir(generatedContentDir string) AppOption {
 	return func(o *ApplicationConfig) {
 		o.GeneratedContentDir = generatedContentDir
@@ -514,6 +522,8 @@ func (o *ApplicationConfig) ToRuntimeSettings() RuntimeSettings {
 	contextSize := o.ContextSize
 	f16 := o.F16
 	debug := o.Debug
+	tracingMaxItems := o.TracingMaxItems
+	enableTracing := o.EnableTracing
 	cors := o.CORS
 	csrf := o.CSRF
 	corsAllowOrigins := o.CORSAllowOrigins
@@ -561,6 +571,8 @@ func (o *ApplicationConfig) ToRuntimeSettings() RuntimeSettings {
 		ContextSize:              &contextSize,
 		F16:                      &f16,
 		Debug:                    &debug,
+		TracingMaxItems:          &tracingMaxItems,
+		EnableTracing:            &enableTracing,
 		CORS:                     &cors,
 		CSRF:                     &csrf,
 		CORSAllowOrigins:         &corsAllowOrigins,
@@ -661,6 +673,12 @@ func (o *ApplicationConfig) ApplyRuntimeSettings(settings *RuntimeSettings) (req
 	if settings.Debug != nil {
 		o.Debug = *settings.Debug
 	}
+	if settings.EnableTracing != nil {
+		o.EnableTracing = *settings.EnableTracing
+	}
+	if settings.TracingMaxItems != nil {
+		o.TracingMaxItems = *settings.TracingMaxItems
+	}
 	if settings.CORS != nil {
 		o.CORS = *settings.CORS
 	}

core/config/runtime_settings.go

@@ -27,10 +27,12 @@ type RuntimeSettings struct {
 	MemoryReclaimerThreshold *float64 `json:"memory_reclaimer_threshold,omitempty"` // Threshold 0.0-1.0 (e.g., 0.95 = 95%)
 
 	// Performance settings
-	Threads     *int  `json:"threads,omitempty"`
-	ContextSize *int  `json:"context_size,omitempty"`
-	F16         *bool `json:"f16,omitempty"`
-	Debug       *bool `json:"debug,omitempty"`
+	Threads         *int  `json:"threads,omitempty"`
+	ContextSize     *int  `json:"context_size,omitempty"`
+	F16             *bool `json:"f16,omitempty"`
+	Debug           *bool `json:"debug,omitempty"`
+	EnableTracing   *bool `json:"enable_tracing,omitempty"`
+	TracingMaxItems *int  `json:"tracing_max_items,omitempty"`
 
 	// Security/CORS settings
 	CORS             *bool   `json:"cors,omitempty"`

core/http/middleware/trace.go

@@ -2,43 +2,40 @@ package middleware
 
 import (
 	"bytes"
+	"github.com/emirpasic/gods/v2/queues/circularbuffer"
 	"io"
 	"net/http"
+	"sort"
 	"sync"
+	"time"
 
 	"github.com/labstack/echo/v4"
 	"github.com/mudler/LocalAI/core/application"
 	"github.com/rs/zerolog/log"
 )
 
+type APIExchangeRequest struct {
+	Method  string       `json:"method"`
+	Path    string       `json:"path"`
+	Headers *http.Header `json:"headers"`
+	Body    *[]byte      `json:"body"`
+}
+
+type APIExchangeResponse struct {
+	Status  int          `json:"status"`
+	Headers *http.Header `json:"headers"`
+	Body    *[]byte      `json:"body"`
+}
+
 type APIExchange struct {
-	Request struct {
-		Method  string
-		Path    string
-		Headers http.Header
-		Body    []byte
-	}
-	Response struct {
-		Status  int
-		Headers http.Header
-		Body    []byte
-	}
+	Timestamp time.Time           `json:"timestamp"`
+	Request   APIExchangeRequest  `json:"request"`
+	Response  APIExchangeResponse `json:"response"`
 }
 
-var apiLogs []APIExchange
+var traceBuffer *circularbuffer.Queue[APIExchange]
 var mu sync.Mutex
-var logChan = make(chan APIExchange, 100) // Buffered channel for serialization
-
-func init() {
-	go func() {
-		for exchange := range logChan {
-			mu.Lock()
-			apiLogs = append(apiLogs, exchange)
-			mu.Unlock()
-			log.Debug().Msgf("Logged exchange: %s %s - Status: %d", exchange.Request.Method, exchange.Request.Path, exchange.Response.Status)
-		}
-	}()
-}
+var logChan = make(chan APIExchange, 100)
 
 type bodyWriter struct {
 	http.ResponseWriter
@@ -58,13 +55,24 @@ func (w *bodyWriter) Flush() {
 
 // TraceMiddleware intercepts and logs JSON API requests and responses
 func TraceMiddleware(app *application.Application) echo.MiddlewareFunc {
+	if app.ApplicationConfig().EnableTracing && traceBuffer == nil {
+		traceBuffer = circularbuffer.New[APIExchange](app.ApplicationConfig().TracingMaxItems)
+
+		go func() {
+			for exchange := range logChan {
+				mu.Lock()
+				traceBuffer.Enqueue(exchange)
+				mu.Unlock()
+			}
+		}()
+	}
+
 	return func(next echo.HandlerFunc) echo.HandlerFunc {
 		return func(c echo.Context) error {
 			if !app.ApplicationConfig().EnableTracing {
 				return next(c)
 			}
 
-			// Only log if Content-Type is application/json
 			if c.Request().Header.Get("Content-Type") != "application/json" {
 				return next(c)
 			}
@@ -78,6 +86,8 @@ func TraceMiddleware(app *application.Application) echo.MiddlewareFunc {
 			// Restore the body for downstream handlers
 			c.Request().Body = io.NopCloser(bytes.NewBuffer(body))
 
+			startTime := time.Now()
+
 			// Wrap response writer to capture body
 			resBody := new(bytes.Buffer)
 			mw := &bodyWriter{
@@ -93,51 +103,54 @@ func TraceMiddleware(app *application.Application) echo.MiddlewareFunc {
 			}
 
 			// Create exchange log
+			requestHeaders := c.Request().Header.Clone()
+			requestBody := make([]byte, len(body))
+			copy(requestBody, body)
+			responseHeaders := c.Response().Header().Clone()
+			responseBody := make([]byte, resBody.Len())
+			copy(responseBody, resBody.Bytes())
 			exchange := APIExchange{
-				Request: struct {
-					Method  string
-					Path    string
-					Headers http.Header
-					Body    []byte
-				}{
+				Timestamp: startTime,
+				Request: APIExchangeRequest{
 					Method:  c.Request().Method,
 					Path:    c.Path(),
-					Headers: c.Request().Header.Clone(),
-					Body:    body,
+					Headers: &requestHeaders,
+					Body:    &requestBody,
 				},
-				Response: struct {
-					Status  int
-					Headers http.Header
-					Body    []byte
-				}{
+				Response: APIExchangeResponse{
 					Status:  c.Response().Status,
-					Headers: c.Response().Header().Clone(),
-					Body:    resBody.Bytes(),
+					Headers: &responseHeaders,
+					Body:    &responseBody,
 				},
 			}
 
-			// Send to channel (non-blocking)
 			select {
 			case logChan <- exchange:
 			default:
-				log.Warn().Msg("API log channel full, dropping log")
+				log.Warn().Msg("Trace channel full, dropping trace")
 			}
 
 			return nil
 		}
 	}
 }
 
-// GetAPILogs returns a copy of the logged API exchanges for display
-func GetAPILogs() []APIExchange {
+// GetTraces returns a copy of the logged API exchanges for display
+func GetTraces() []APIExchange {
 	mu.Lock()
-	defer mu.Unlock()
-	return append([]APIExchange{}, apiLogs...)
+	traces := traceBuffer.Values()
+	mu.Unlock()
+
+	sort.Slice(traces, func(i, j int) bool {
+		return traces[i].Timestamp.Before(traces[j].Timestamp)
+	})
+
+	return traces
 }
 
-// ClearAPILogs clears the in-memory logs
-func ClearAPILogs() {
+// ClearTraces clears the in-memory logs
+func ClearTraces() {
 	mu.Lock()
-	apiLogs = nil
+	traceBuffer.Clear()
 	mu.Unlock()
 }

core/http/routes/ui.go

@@ -317,4 +317,24 @@ func RegisterUIRoutes(app *echo.Echo,
 		// Render index
 		return c.Render(200, "views/tts", summary)
 	})
+
+	// Traces UI
+	app.GET("/traces", func(c echo.Context) error {
+		summary := map[string]interface{}{
+			"Title":   "LocalAI - Traces",
+			"BaseURL": middleware.BaseURL(c),
+			"Version": internal.PrintableVersion(),
+		}
+		return c.Render(200, "views/traces", summary)
+	})
+
+	app.GET("/api/traces", func(c echo.Context) error {
+		return c.JSON(200, middleware.GetTraces())
+	})
+
+	app.POST("/api/traces/clear", func(c echo.Context) error {
+		middleware.ClearTraces()
+		return c.NoContent(204)
+	})
+
 }

core/http/routes/ui_api.go

@@ -956,14 +956,14 @@ func RegisterUIAPIRoutes(app *echo.Echo, cl *config.ModelConfigLoader, ml *model
 				"error": "Tracing disabled",
 				})
 		}
-		logs := middleware.GetAPILogs()
+		traces := middleware.GetTraces()
 		return c.JSON(200, map[string]interface{}{
-			"logs": logs,
+			"traces": traces,
 		})
 	})
 
 	app.POST("/api/traces/clear", func(c echo.Context) error {
-		middleware.ClearAPILogs()
+		middleware.ClearTraces()
 		return c.JSON(200, map[string]interface{}{
 			"message": "Traces cleared",
 		})