From 80f3d4759e0aa30118e0487c51dbd2a0de9efec7 Mon Sep 17 00:00:00 2001
From: Wang Qi <wangq8@outlook.com>
Date: Mon, 9 Nov 2026 16:36:55 +0800
Subject: [PATCH] Feature: observability OSS stub (#22168)

---
 internal/observability/stub.go    | 5 +++++
 internal/server/admin/server.go   | 2 ++
 internal/server/admin/stub.go     | 7 +++++++
 internal/service/nlp/reranker.go  | 2 ++
 internal/service/nlp/retrieval.go | 7 +++++--
 5 files changed, 21 insertions(+), 2 deletions(-)
 create mode 100644 internal/observability/stub.go
 create mode 100644 internal/server/admin/stub.go

diff --git a/internal/observability/stub.go b/internal/observability/stub.go
new file mode 100644
index 0000000000..e12691c6a3
--- /dev/null
+++ b/internal/observability/stub.go
@@ -0,0 +1,5 @@
+//go:build !ee
+
+package observability
+
+func BeginRetrieval(_ string) func(*error) { return func(*error) {} }
diff --git a/internal/server/admin/server.go b/internal/server/admin/server.go
index d8be1e00cd..63886bb562 100644
--- a/internal/server/admin/server.go
+++ b/internal/server/admin/server.go
@@ -105,6 +105,8 @@ func Run(ctx context.Context, serverName string, args *bootstrap.ServerArgs) err
 	validator := utility.NewScheduledTask("Admin validator", globalConfig.GetHeartbeatInterval(), adminapi.CheckServicePeriodically)
 	validator.Start()
 	defer validator.Stop()
+	stopMetrics := startMetrics(ctx)
+	defer stopMetrics()
 
 	// Start HTTP server in a goroutine
 	go func() {
diff --git a/internal/server/admin/stub.go b/internal/server/admin/stub.go
new file mode 100644
index 0000000000..6cea093ddd
--- /dev/null
+++ b/internal/server/admin/stub.go
@@ -0,0 +1,7 @@
+//go:build !ee
+
+package admin
+
+import "context"
+
+func startMetrics(context.Context) func() { return func() {} }
diff --git a/internal/service/nlp/reranker.go b/internal/service/nlp/reranker.go
index 0ae7a8cbf2..1752a82c3b 100644
--- a/internal/service/nlp/reranker.go
+++ b/internal/service/nlp/reranker.go
@@ -25,6 +25,7 @@ import (
 
 	"ragflow/internal/common"
 	"ragflow/internal/entity/models"
+	"ragflow/internal/observability"
 
 	"go.uber.org/zap"
 )
@@ -51,6 +52,7 @@ func RerankByModel(
 	rankFeature map[string]float64,
 	language string,
 ) (sim []float64, tsim []float64, vsim []float64, err error) {
+	defer observability.BeginRetrieval("retrieval_rerank")(&err)
 	if chunks == nil || len(chunks) == 0 {
 		return []float64{}, []float64{}, []float64{}, nil
 	}
diff --git a/internal/service/nlp/retrieval.go b/internal/service/nlp/retrieval.go
index 7a4f6164da..514d6300e6 100644
--- a/internal/service/nlp/retrieval.go
+++ b/internal/service/nlp/retrieval.go
@@ -31,6 +31,7 @@ import (
 	"ragflow/internal/engine"
 	"ragflow/internal/engine/types"
 	"ragflow/internal/entity/models"
+	"ragflow/internal/observability"
 	"ragflow/internal/tokenizer"
 
 	"go.uber.org/zap"
@@ -107,7 +108,8 @@ const (
 // - Calculate pagination to extract actual page returned from reranked results
 // - Build chunks
 // - Build document aggregation if specified
-func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest) (*RetrievalResult, error) {
+func (s *RetrievalService) Retrieval(ctx context.Context, req *RetrievalRequest) (result *RetrievalResult, err error) {
+	defer observability.BeginRetrieval("retrieval")(&err)
 	common.InfoCtx(ctx, "Retrieval START", zap.String("question", req.Question), zap.Int("page", req.Page), zap.Int("pageSize", req.PageSize))
 	if req.Question == "" {
 		return &RetrievalResult{Chunks: []map[string]interface{}{}, DocAggs: []map[string]interface{}{}, Total: 0}, nil
@@ -1020,7 +1022,8 @@ func cloneDenseExpr(source *types.MatchDenseExpr) *types.MatchDenseExpr {
 }
 
 // GetVector computes query vector and returns MatchDenseExpr for hybrid search
-func (s *RetrievalService) GetVector(ctx context.Context, txt string, embModel *models.EmbeddingModel, knnTopK, numCandidates int, similarity float64) (*types.MatchDenseExpr, error) {
+func (s *RetrievalService) GetVector(ctx context.Context, txt string, embModel *models.EmbeddingModel, knnTopK, numCandidates int, similarity float64) (result *types.MatchDenseExpr, err error) {
+	defer observability.BeginRetrieval("retrieval_embedding")(&err)
 	embeddingConfig := &models.EmbeddingConfig{
 		Dimension: 0,
 	}