perf(http): gzip responses, cache hashed assets, bound the trace endpoints (#11056)

Three measured HTTP-layer regressions on a live deployment, fixed together
because they all shape the bytes on the wire.

1. No compression. The server sent no Content-Encoding regardless of what
   the client asked for, confirmed with curl straight at 127.0.0.1:8080 so
   it was not an ingress artefact. Adds gzip middleware, on by default and
   configurable via LOCALAI_DISABLE_HTTP_COMPRESSION and
   LOCALAI_HTTP_COMPRESSION_MIN_LENGTH (default 1024 bytes so tiny bodies
   are not wastefully wrapped). Streaming routes are skipped explicitly:
   an SSE Accept header, a WebSocket upgrade, and the completion / SSE /
   log-tail path prefixes, because whether a completion request streams is
   decided by the request body, which the middleware runs too early to see.
   Already-compressed formats (woff2, png, mp4, ...) are skipped too; gzip
   made those marginally larger. Measured over the embedded React build:
   JS+CSS 2815 KB raw to 808 KB gzipped (3.48x).

2. No cache headers on content-hashed assets. Vite hashes the filenames,
   so a given /assets/ URL can never change content, yet they shipped with
   no Cache-Control, ETag or Last-Modified, and the browser re-fetched the
   whole bundle on every navigation with no conditional request available.
   /assets/* now carries public, max-age=31536000, immutable. index.html
   stays no-cache so a deploy is picked up, and the unhashed locale JSONs
   get a short TTL rather than the immutable one.

3. Unbounded trace endpoints. /api/traces returned 21,033,606 bytes in
   4.65s and /api/backend-traces 3,471,682 bytes in 1.50s, and the admin
   UI polls both every few seconds. The ring buffer holds up to 1024
   entries, each embedding full input_text payloads. Both list endpoints
   now take limit / offset / full, default to 50 entries, and strip the
   heavy fields (request and response bodies plus headers for API traces,
   body and data for backend traces) unless full=true. Every trace gets a
   process-lifetime ID and GET /api/traces/{id} and
   /api/backend-traces/{id} serve the full record, which is what the UI
   fetches when a row is expanded. The list body stays a JSON array;
   paging metadata rides in X-Total-Count, X-Trace-Offset and
   X-Trace-Limit. Reproducing the live shape in a test, the polled payload
   goes from 21,131,097 bytes to 7,201 bytes.


Assisted-by: Claude:claude-opus-4-8 [Claude Code]

Signed-off-by: Ettore Di Giacinto <mudler@localai.io>
Co-authored-by: Ettore Di Giacinto <mudler@localai.io>

Author: localai-bot

core/cli/run.go

@@ -69,6 +69,8 @@ type RunCMD struct {
 	CORS                               bool     `env:"LOCALAI_CORS,CORS" help:"" group:"api"`
 	CORSAllowOrigins                   string   `env:"LOCALAI_CORS_ALLOW_ORIGINS,CORS_ALLOW_ORIGINS" group:"api"`
 	DisableCSRF                        bool     `env:"LOCALAI_DISABLE_CSRF" help:"Disable CSRF middleware (enabled by default)" group:"api"`
+	DisableHTTPCompression             bool     `env:"LOCALAI_DISABLE_HTTP_COMPRESSION" default:"false" help:"Disable gzip compression of HTTP responses (enabled by default). Streaming endpoints are never compressed" group:"api"`
+	HTTPCompressionMinLength           int      `env:"LOCALAI_HTTP_COMPRESSION_MIN_LENGTH" default:"1024" help:"Minimum response size in bytes before gzip compression is applied" group:"api"`
 	UploadLimit                        int      `env:"LOCALAI_UPLOAD_LIMIT,UPLOAD_LIMIT" default:"15" help:"Default upload-limit in MB" group:"api"`
 	APIKeys                            []string `env:"LOCALAI_API_KEY,API_KEY" help:"List of API Keys to enable API authentication. When this is set, all the requests must be authenticated with one of these API keys" group:"api"`
 	DisableWebUI                       bool     `env:"LOCALAI_DISABLE_WEBUI,DISABLE_WEBUI" default:"false" help:"Disables the web user interface. When set to true, the server will only expose API endpoints without serving the web interface" group:"api"`
@@ -279,6 +281,8 @@ func (r *RunCMD) Run(ctx *cliContext.Context) error {
 		config.WithCors(r.CORS),
 		config.WithCorsAllowOrigins(r.CORSAllowOrigins),
 		config.WithDisableCSRF(r.DisableCSRF),
+		config.WithDisableHTTPCompression(r.DisableHTTPCompression),
+		config.WithHTTPCompressionMinLength(r.HTTPCompressionMinLength),
 		config.WithThreads(r.Threads),
 		config.WithUploadLimitMB(r.UploadLimit),
 		config.WithApiKeys(r.APIKeys),

core/config/application_config.go

@@ -50,7 +50,14 @@ type ApplicationConfig struct {
 	DynamicConfigsDirPollInterval time.Duration
 	CORS                          bool
 	DisableCSRF                   bool
-	PreloadJSONModels             string
+	// DisableHTTPCompression turns off the gzip response middleware. Gzip is
+	// on by default because the React UI bundle and the admin JSON APIs are
+	// text-heavy; turn it off only when a fronting proxy already compresses.
+	DisableHTTPCompression bool
+	// HTTPCompressionMinLength is the response-size floor (bytes) below which
+	// gzip is skipped. 0 keeps middleware.DefaultCompressionMinLength.
+	HTTPCompressionMinLength int
+	PreloadJSONModels        string
 	PreloadModelsFromPath         string
 	CORSAllowOrigins              string
 	ApiKeys                       []string
@@ -382,6 +389,18 @@ func WithDisableCSRF(b bool) AppOption {
 	}
 }
 
+func WithDisableHTTPCompression(b bool) AppOption {
+	return func(o *ApplicationConfig) {
+		o.DisableHTTPCompression = b
+	}
+}
+
+func WithHTTPCompressionMinLength(n int) AppOption {
+	return func(o *ApplicationConfig) {
+		o.HTTPCompressionMinLength = n
+	}
+}
+
 func WithP2PToken(s string) AppOption {
 	return func(o *ApplicationConfig) {
 		o.P2PToken = s

core/http/app.go

@@ -49,6 +49,12 @@ var reactUI embed.FS
 
 var quietPaths = []string{"/api/operations", "/api/resources", "/healthz", "/readyz"}
 
+// immutableAssetCacheControl is the Cache-Control served for content-hashed
+// build output. The filename changes whenever the content does, so a one-year
+// TTL plus `immutable` is safe and removes both the re-download and the
+// conditional revalidation round-trip.
+const immutableAssetCacheControl = "public, max-age=31536000, immutable"
+
 // applyModelLoadCooldown maps a ModelLoadCooldownError anywhere in err's chain
 // to HTTP 503 with a Retry-After header (whole seconds, floor 1), so a client
 // polling a model whose load recently failed backs off instead of triggering a
@@ -202,6 +208,13 @@ func API(application *application.Application) (*echo.Echo, error) {
 	// errors — picks them up.
 	e.Use(httpMiddleware.SecurityHeaders())
 
+	// Gzip responses. Registered before the tracing and handler middlewares so
+	// the response writer it installs sits underneath them: the trace buffer
+	// keeps capturing plaintext while the wire carries the compressed bytes.
+	if !application.ApplicationConfig().DisableHTTPCompression {
+		e.Use(httpMiddleware.Compression(application.ApplicationConfig().HTTPCompressionMinLength))
+	}
+
 	// Custom logger middleware using xlog
 	e.Use(func(next echo.HandlerFunc) echo.HandlerFunc {
 		return func(c echo.Context) error {
@@ -512,6 +525,10 @@ func API(application *application.Application) (*echo.Echo, error) {
 				if err != nil {
 					return c.String(http.StatusNotFound, "React UI not built")
 				}
+				// index.html names the content-hashed bundles, so it must never
+				// be cached: a stale copy pins the browser to the previous
+				// deploy's assets.
+				c.Response().Header().Set("Cache-Control", "no-cache")
 				// Inject <base href> for reverse-proxy support; baseURL comes
 				// from attacker-controllable Host / X-Forwarded-Host headers.
 				baseURL := httpMiddleware.BaseURL(c)
@@ -573,8 +590,10 @@ func API(application *application.Application) (*echo.Echo, error) {
 			})
 
 			// Serve React static assets (JS, CSS, etc.) and i18n locale JSONs
-			// from the embedded React build.
-			serveReactSubdir := func(subdir string) echo.HandlerFunc {
+			// from the embedded React build. cacheControl is stamped on every
+			// hit so the browser can reuse the bytes instead of re-fetching
+			// ~1.8 MB of bundle on each navigation.
+			serveReactSubdir := func(subdir, cacheControl string) echo.HandlerFunc {
 				return func(c echo.Context) error {
 					p := subdir + "/" + c.Param("*")
 					f, err := reactFS.Open(p)
@@ -586,14 +605,21 @@ func API(application *application.Application) (*echo.Echo, error) {
 							if contentType == "" {
 								contentType = echo.MIMEOctetStream
 							}
+							if cacheControl != "" {
+								c.Response().Header().Set("Cache-Control", cacheControl)
+							}
 							return c.Stream(http.StatusOK, contentType, f)
 						}
 					}
 					return echo.NewHTTPError(http.StatusNotFound)
 				}
 			}
-			e.GET("/assets/*", serveReactSubdir("assets"))
-			e.GET("/locales/*", serveReactSubdir("locales"))
+			// Vite content-hashes everything under /assets (Manage-DrwQK63f.js),
+			// so a given URL can never change content: cache it for a year and
+			// skip revalidation entirely. Locale JSONs keep stable names, so
+			// they only get a short TTL.
+			e.GET("/assets/*", serveReactSubdir("assets", immutableAssetCacheControl))
+			e.GET("/locales/*", serveReactSubdir("locales", "public, max-age=300"))
 		}
 	}
 	routes.RegisterJINARoutes(e, requestExtractor, application.ModelConfigLoader(), application.ModelLoader(), application.ApplicationConfig())

core/http/endpoints/localai/traces.go

@@ -1,21 +1,106 @@
 package localai
 
 import (
+	"net/http"
+	"strconv"
+
 	"github.com/labstack/echo/v4"
 	"github.com/mudler/LocalAI/core/http/middleware"
+	"github.com/mudler/LocalAI/core/schema"
 	"github.com/mudler/LocalAI/core/trace"
 )
 
-// GetAPITracesEndpoint returns all API request/response traces
+// DefaultTraceListLimit bounds the trace list responses. The ring buffer holds
+// up to LOCALAI_TRACING_MAX_ITEMS entries (1024 in a typical deployment) and
+// each one can embed a full request/response payload, so returning the whole
+// buffer made /api/traces a multi-megabyte response that the admin UI
+// re-fetched on every poll. Callers that genuinely want everything can pass
+// limit=0.
+const DefaultTraceListLimit = 50
+
+// MaxTraceListLimit caps an explicit limit so a client cannot ask for an
+// unbounded page by accident.
+const MaxTraceListLimit = 1000
+
+// tracePageParams reads the limit/offset/full query parameters. Invalid values
+// fall back to the bounded defaults rather than erroring, so existing clients
+// keep working.
+func tracePageParams(c echo.Context) (offset, limit int, full bool) {
+	limit = DefaultTraceListLimit
+	if raw := c.QueryParam("limit"); raw != "" {
+		if n, err := strconv.Atoi(raw); err == nil && n >= 0 {
+			limit = n
+		}
+	}
+	if limit > MaxTraceListLimit {
+		limit = MaxTraceListLimit
+	}
+	if raw := c.QueryParam("offset"); raw != "" {
+		if n, err := strconv.Atoi(raw); err == nil && n > 0 {
+			offset = n
+		}
+	}
+	if raw := c.QueryParam("full"); raw != "" {
+		full, _ = strconv.ParseBool(raw)
+	}
+	return offset, limit, full
+}
+
+// setTracePageHeaders publishes the paging metadata out-of-band so the
+// response body stays a plain JSON array for existing consumers.
+func setTracePageHeaders(c echo.Context, total, offset, limit int) {
+	h := c.Response().Header()
+	h.Set("X-Total-Count", strconv.Itoa(total))
+	h.Set("X-Trace-Offset", strconv.Itoa(offset))
+	h.Set("X-Trace-Limit", strconv.Itoa(limit))
+}
+
+func traceNotFound(c echo.Context) error {
+	return c.JSON(http.StatusNotFound, schema.ErrorResponse{
+		Error: &schema.APIError{Message: "trace not found", Code: http.StatusNotFound},
+	})
+}
+
+// GetAPITracesEndpoint returns a bounded page of API request/response traces
 // @Summary List API request/response traces
-// @Description Returns captured API exchange traces (request/response pairs) in reverse chronological order
+// @Description Returns a bounded, newest-first page of captured API exchange traces. Request and response bodies plus headers are omitted unless full=true; fetch them per-trace from /api/traces/{id}. Paging metadata is returned in the X-Total-Count, X-Trace-Offset and X-Trace-Limit headers.
 // @Tags monitoring
 // @Produce json
+// @Param limit query int false "Maximum entries to return (default 50, max 1000, 0 for all)"
+// @Param offset query int false "Number of entries to skip (default 0)"
+// @Param full query bool false "Include request/response bodies and headers (default false)"
 // @Success 200 {object} map[string]any "Traced API exchanges"
 // @Router /api/traces [get]
 func GetAPITracesEndpoint() echo.HandlerFunc {
 	return func(c echo.Context) error {
-		return c.JSON(200, middleware.GetTraces())
+		offset, limit, full := tracePageParams(c)
+		page, total := middleware.GetTracesPage(offset, limit)
+		if !full {
+			for i := range page {
+				page[i] = middleware.SummarizeExchange(page[i])
+			}
+		}
+		setTracePageHeaders(c, total, offset, limit)
+		return c.JSON(http.StatusOK, page)
+	}
+}
+
+// GetAPITraceEndpoint returns a single API trace with its full payload
+// @Summary Get one API trace
+// @Description Returns a single captured API exchange, including the request and response bodies omitted from the list response
+// @Tags monitoring
+// @Produce json
+// @Param id path string true "Trace ID"
+// @Success 200 {object} map[string]any "Traced API exchange"
+// @Failure 404 {object} schema.ErrorResponse "Trace not found"
+// @Router /api/traces/{id} [get]
+func GetAPITraceEndpoint() echo.HandlerFunc {
+	return func(c echo.Context) error {
+		exchange, ok := middleware.GetTrace(c.Param("id"))
+		if !ok {
+			return traceNotFound(c)
+		}
+		return c.JSON(http.StatusOK, exchange)
 	}
 }
 
@@ -28,20 +113,50 @@ func GetAPITracesEndpoint() echo.HandlerFunc {
 func ClearAPITracesEndpoint() echo.HandlerFunc {
 	return func(c echo.Context) error {
 		middleware.ClearTraces()
-		return c.NoContent(204)
+		return c.NoContent(http.StatusNoContent)
 	}
 }
 
-// GetBackendTracesEndpoint returns all backend operation traces
+// GetBackendTracesEndpoint returns a bounded page of backend operation traces
 // @Summary List backend operation traces
-// @Description Returns captured backend traces (LLM calls, embeddings, TTS, etc.) in reverse chronological order
+// @Description Returns a bounded, newest-first page of captured backend traces (LLM calls, embeddings, TTS, etc). The heavy body and data fields are omitted unless full=true; fetch them per-trace from /api/backend-traces/{id}. Paging metadata is returned in the X-Total-Count, X-Trace-Offset and X-Trace-Limit headers.
 // @Tags monitoring
 // @Produce json
+// @Param limit query int false "Maximum entries to return (default 50, max 1000, 0 for all)"
+// @Param offset query int false "Number of entries to skip (default 0)"
+// @Param full query bool false "Include the body and data payloads (default false)"
 // @Success 200 {object} map[string]any "Backend operation traces"
 // @Router /api/backend-traces [get]
 func GetBackendTracesEndpoint() echo.HandlerFunc {
 	return func(c echo.Context) error {
-		return c.JSON(200, trace.GetBackendTraces())
+		offset, limit, full := tracePageParams(c)
+		page, total := trace.GetBackendTracesPage(offset, limit)
+		if !full {
+			for i := range page {
+				page[i] = trace.SummarizeBackendTrace(page[i])
+			}
+		}
+		setTracePageHeaders(c, total, offset, limit)
+		return c.JSON(http.StatusOK, page)
+	}
+}
+
+// GetBackendTraceEndpoint returns a single backend trace with its full payload
+// @Summary Get one backend operation trace
+// @Description Returns a single captured backend trace, including the body and data payloads omitted from the list response
+// @Tags monitoring
+// @Produce json
+// @Param id path string true "Trace ID"
+// @Success 200 {object} map[string]any "Backend operation trace"
+// @Failure 404 {object} schema.ErrorResponse "Trace not found"
+// @Router /api/backend-traces/{id} [get]
+func GetBackendTraceEndpoint() echo.HandlerFunc {
+	return func(c echo.Context) error {
+		t, ok := trace.GetBackendTrace(c.Param("id"))
+		if !ok {
+			return traceNotFound(c)
+		}
+		return c.JSON(http.StatusOK, t)
 	}
 }
 
@@ -54,6 +169,6 @@ func GetBackendTracesEndpoint() echo.HandlerFunc {
 func ClearBackendTracesEndpoint() echo.HandlerFunc {
 	return func(c echo.Context) error {
 		trace.ClearBackendTraces()
-		return c.NoContent(204)
+		return c.NoContent(http.StatusNoContent)
 	}
 }