internal, static: add telemetry click beacon for search A/B testing

Add /search-click handler to log search result click metadata
(query, clicked_package, rank, cohort, timestamp) to Cloud Logging.
Pass IsVectorSearch to SearchPage template and fire non-blocking
sendBeacon telemetry when users select search results.

Change-Id: I4d4aec11d28bdb65c4977b04288d63cef57c96c6
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/806500
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Auto-Submit: Ethan Lee <ethanalee@google.com>
kokoro-CI: kokoro <noreply+kokoro@google.com>
LUCI-TryBot-Result: golang-scoped@luci-project-accounts.iam.gserviceaccount.com <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

Author: ethanalee-work

internal/frontend/search.go

@@ -6,6 +6,7 @@ package frontend
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"net/http"
@@ -247,11 +248,17 @@ func fetchSearchPage(ctx context.Context, ds internal.DataSource, cq, symbol str
 	pageParams paginationParams, searchSymbols bool, vulnClient *vuln.Client, embeddingsClient VectorEmbedder) (*SearchPage, error) {
 	maxResultCount := maxSearchOffset + pageParams.limit
 
-	var vec []float32
+	var (
+		vec              []float32
+		embeddingLatency time.Duration
+		searchLatency    time.Duration
+	)
 	if embeddingsClient != nil && !searchSymbols && strings.TrimSpace(cq) != "" && experiment.IsActive(ctx, internal.ExperimentVectorSearch) {
 		embedCtx, cancel := context.WithTimeout(ctx, searchEmbeddingTimeout)
 		defer cancel()
+		startEmbed := time.Now()
 		vecs, err := embeddingsClient.GenerateEmbeddings(embedCtx, []string{cq}, "RETRIEVAL_QUERY")
+		embeddingLatency = time.Since(startEmbed)
 		if err != nil {
 			log.Errorf(ctx, "failed to generate query vector for %q: %v", cq, err)
 		} else if len(vecs) > 0 {
@@ -261,6 +268,7 @@ func fetchSearchPage(ctx context.Context, ds internal.DataSource, cq, symbol str
 
 	// Pageless search: always start from the beginning.
 	offset := 0
+	startSearch := time.Now()
 	dbresults, err := ds.Search(ctx, cq, internal.SearchOptions{
 		MaxResults:     pageParams.limit,
 		Offset:         offset,
@@ -270,6 +278,7 @@ func fetchSearchPage(ctx context.Context, ds internal.DataSource, cq, symbol str
 		GroupResults:   true,
 		Vector:         vec,
 	})
+	searchLatency = time.Since(startSearch)
 	if err != nil {
 		return nil, err
 	}
@@ -299,6 +308,19 @@ func fetchSearchPage(ctx context.Context, ds internal.DataSource, cq, symbol str
 		numPageResults += 1 + len(r.SameModule)
 	}
 
+	cohort := "control"
+	if len(vec) > 0 {
+		cohort = "treatment"
+	}
+	log.Info(ctx, map[string]any{
+		"log_type":             "search_query_execution",
+		"query":                cq,
+		"cohort":               cohort,
+		"embedding_latency_ms": embeddingLatency.Milliseconds(),
+		"search_latency_ms":    searchLatency.Milliseconds(),
+		"num_results":          numResults,
+	})
+
 	pgs := newPagination(pageParams, numPageResults, numResults)
 	sp := &SearchPage{
 		PackageTabQuery: cq,
@@ -604,5 +626,47 @@ func addVulns(ctx context.Context, rs []*SearchResult, vc *vuln.Client) {
 		})
 	}
 	wg.Wait()
+}
+
+type searchClickPayload struct {
+	Query          string `json:"query"`
+	ClickedPackage string `json:"clicked_package"`
+	Rank           int    `json:"rank"`
+	Cohort         string `json:"cohort"`
+	Timestamp      string `json:"timestamp"`
+}
+
+func (s *Server) handleSearchClick(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
 
+	r.Body = http.MaxBytesReader(w, r.Body, 10<<10)
+
+	var payload searchClickPayload
+	if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+		http.Error(w, "bad request", http.StatusBadRequest)
+		return
+	}
+
+	// Input validation: require non-empty fields & valid cohort.
+	if strings.TrimSpace(payload.Query) == "" || strings.TrimSpace(payload.ClickedPackage) == "" || payload.Rank < 0 {
+		http.Error(w, "missing or invalid required fields", http.StatusBadRequest)
+		return
+	}
+	if payload.Cohort != "control" && payload.Cohort != "treatment" {
+		http.Error(w, "invalid cohort", http.StatusBadRequest)
+		return
+	}
+
+	log.Info(r.Context(), map[string]any{
+		"log_type":        "search_click_telemetry",
+		"query":           payload.Query,
+		"clicked_package": payload.ClickedPackage,
+		"rank":            payload.Rank,
+		"cohort":          payload.Cohort,
+		"timestamp":       payload.Timestamp,
+	})
+	w.WriteHeader(http.StatusNoContent)
 }

internal/frontend/search_test.go

@@ -920,3 +920,60 @@ func TestFetchSearchPageWithVector(t *testing.T) {
 		})
 	}
 }
+
+func TestHandleSearchClick(t *testing.T) {
+	s := &Server{}
+
+	tests := []struct {
+		name       string
+		method     string
+		payload    string
+		wantStatus int
+	}{
+		{
+			name:       "valid click treatment",
+			method:     http.MethodPost,
+			payload:    `{"query":"http router","clicked_package":"net/http","rank":0,"cohort":"treatment","timestamp":"2026-07-27T17:00:00Z"}`,
+			wantStatus: http.StatusNoContent,
+		},
+		{
+			name:       "valid click control",
+			method:     http.MethodPost,
+			payload:    `{"query":"http router","clicked_package":"net/http","rank":0,"cohort":"control","timestamp":"2026-07-27T17:00:00Z"}`,
+			wantStatus: http.StatusNoContent,
+		},
+		{
+			name:       "invalid method GET",
+			method:     http.MethodGet,
+			payload:    "",
+			wantStatus: http.StatusMethodNotAllowed,
+		},
+		{
+			name:       "invalid payload empty query",
+			method:     http.MethodPost,
+			payload:    `{"query":"","clicked_package":"net/http","rank":0,"cohort":"treatment"}`,
+			wantStatus: http.StatusBadRequest,
+		},
+		{
+			name:       "invalid cohort",
+			method:     http.MethodPost,
+			payload:    `{"query":"http router","clicked_package":"net/http","rank":0,"cohort":"unknown"}`,
+			wantStatus: http.StatusBadRequest,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			req := httptest.NewRequest(test.method, "/search-click", strings.NewReader(test.payload))
+			req.Header.Set("Content-Type", "application/json")
+			w := httptest.NewRecorder()
+
+			s.handleSearchClick(w, req)
+
+			if w.Code != test.wantStatus {
+				t.Errorf("got status %d, want %d", w.Code, test.wantStatus)
+			}
+		})
+	}
+}

internal/frontend/server.go

@@ -233,6 +233,7 @@ func (s *Server) Install(handle func(string, http.Handler), cacher Cacher, authV
 	handle("POST /play/fmt", http.HandlerFunc(s.handleFmt))
 	handle("/play/share", http.HandlerFunc(s.proxyPlayground))
 	handle("GET /search", searchHandler)
+	handle("POST /search-click", http.HandlerFunc(s.handleSearchClick))
 	handle("GET /search-help", s.staticPageHandler("search-help", "Search Help"))
 	handle("GET /license-policy", s.licensePolicyHandler())
 	handle("GET /about", s.staticPageHandler("about", "About"))

static/frontend/search/search.js

@@ -107,7 +107,11 @@
         <div class="SearchSnippet-headerContainer">
           <h2>
             <a href="/{{$v.PackagePath}}" data-gtmc="search result" data-gtmv="{{$i}}"
-                data-test-id="snippet-title">
+                data-test-id="snippet-title"
+                data-search-query="{{$query}}"
+                data-clicked-package="{{$v.PackagePath}}"
+                data-rank="{{$i}}"
+                data-experiment-cohort="{{if $.Experiments.IsActive "vector-search"}}treatment{{else}}control{{end}}">
               {{$v.Name}}
               <span class="SearchSnippet-header-path">({{$v.PackagePath}})</span>
             </a>

static/frontend/search/search.tmpl

@@ -43,4 +43,29 @@ searchHeader?.addEventListener('dblclick', e => {
   }
 });
 
+// Send non-blocking search result click telemetry via navigator.sendBeacon
+document.addEventListener('click', e => {
+  const target = e.target as HTMLElement | null;
+  const link = target?.closest<HTMLAnchorElement>('a[data-search-query]');
+  if (!link) return;
+
+  const query = link.getAttribute('data-search-query');
+  const clickedPackage = link.getAttribute('data-clicked-package');
+  const rankStr = link.getAttribute('data-rank');
+  const cohort = link.getAttribute('data-experiment-cohort');
+
+  if (query && clickedPackage && rankStr && cohort) {
+    const payload = {
+      query: query,
+      clicked_package: clickedPackage,
+      rank: parseInt(rankStr, 10),
+      cohort: cohort,
+      timestamp: new Date().toISOString(),
+    };
+    if (navigator.sendBeacon) {
+      navigator.sendBeacon('/search-click', JSON.stringify(payload));
+    }
+  }
+});
+
 export {};