From f740e7cecfea85f3e95d24da61f4855e790af274 Mon Sep 17 00:00:00 2001 From: wizardchen Date: Tue, 12 May 2026 21:11:54 +0800 Subject: [PATCH] feat(observability): expand Langfuse spans across chat pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously the Langfuse timeline for a knowledge-chat request only showed generations (chat.completion, embedding.embed, rerank), so the work happening between them — query setup, vector/keyword search, result merging, prompt assembly — appeared as unexplained gaps. Add spans around the pieces that fill those gaps: * qa.setup wraps request-time KB / model / search-target resolution before the pipeline event loop starts, accounting for the visible delay before the first chat.completion. * pipeline. wraps each pipeline stage's eventManager.Trigger call so generations inside a stage nest under it. CHAT_COMPLETION_ STREAM is intentionally skipped because its OnEvent returns as soon as the streaming goroutine starts; a stage span would always finish before the chat.completion.stream generation it nominally parents. * retrieve wraps the actual vector + keyword retrieve call inside HybridSearch, exposing the DB round-trip that previously sat invisibly between embedding generations and rerank. * web_search wraps the external web-search HTTP call when enabled. --- .../service/chat_pipeline/search.go | 14 +++- .../service/knowledgebase_search.go | 26 +++++++- .../service/session_knowledge_qa.go | 65 ++++++++++++++++++- 3 files changed, 100 insertions(+), 5 deletions(-) diff --git a/internal/application/service/chat_pipeline/search.go b/internal/application/service/chat_pipeline/search.go index 08ea312b..77ddcb27 100644 --- a/internal/application/service/chat_pipeline/search.go +++ b/internal/application/service/chat_pipeline/search.go @@ -9,6 +9,7 @@ import ( "github.com/Tencent/WeKnora/internal/config" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/searchutil" + "github.com/Tencent/WeKnora/internal/tracing/langfuse" "github.com/Tencent/WeKnora/internal/types" "github.com/Tencent/WeKnora/internal/types/interfaces" ) @@ -645,7 +646,18 @@ func (p *PluginSearch) searchWebIfEnabled(ctx context.Context, chatManage *types "tenant_id": chatManage.TenantID, "provider_id": providerID, }) - webResults, err := p.webSearchService.Search(ctx, providerID, webConfig, chatManage.RewriteQuery) + webCtx, webSpan := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{ + Name: "web_search", + Input: map[string]interface{}{ + "provider_id": providerID, + "query": chatManage.RewriteQuery, + "max_results": webConfig.MaxResults, + }, + }) + webResults, err := p.webSearchService.Search(webCtx, providerID, webConfig, chatManage.RewriteQuery) + webSpan.Finish(map[string]interface{}{ + "hit_count": len(webResults), + }, nil, err) if err != nil { pipelineWarn(ctx, "Search", "web_search_error", map[string]interface{}{ "tenant_id": chatManage.TenantID, diff --git a/internal/application/service/knowledgebase_search.go b/internal/application/service/knowledgebase_search.go index 61b63b42..c02b6a22 100644 --- a/internal/application/service/knowledgebase_search.go +++ b/internal/application/service/knowledgebase_search.go @@ -6,6 +6,7 @@ import ( "github.com/Tencent/WeKnora/internal/application/service/retriever" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/models/embedding" + "github.com/Tencent/WeKnora/internal/tracing/langfuse" "github.com/Tencent/WeKnora/internal/types" ) @@ -133,9 +134,30 @@ func (s *knowledgeBaseService) HybridSearch(ctx context.Context, return nil, nil } - // Execute retrieval using the configured engines + // Execute retrieval using the configured engines. + // A dedicated span captures the actual vector/keyword DB round-trip + // — this is the time previously visible in Langfuse only as the gap + // between embedding generations and the rerank call. logger.Infof(ctx, "Starting retrieval, parameter count: %d", len(retrieveParams)) - retrieveResults, err := retrieveEngine.Retrieve(ctx, retrieveParams) + retrieverTypes := make([]string, 0, len(retrieveParams)) + for _, rp := range retrieveParams { + retrieverTypes = append(retrieverTypes, string(rp.RetrieverType)) + } + retrieveCtx, retrieveSpan := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{ + Name: "retrieve", + Input: map[string]interface{}{ + "kb_ids": searchKBIDs, + "match_count": matchCount, + "retrievers": retrieverTypes, + }, + Metadata: map[string]interface{}{ + "param_count": len(retrieveParams), + }, + }) + retrieveResults, err := retrieveEngine.Retrieve(retrieveCtx, retrieveParams) + retrieveSpan.Finish(map[string]interface{}{ + "result_count": len(retrieveResults), + }, nil, err) if err != nil { logger.ErrorWithFields(ctx, err, map[string]interface{}{ "knowledge_base_ids": searchKBIDs, diff --git a/internal/application/service/session_knowledge_qa.go b/internal/application/service/session_knowledge_qa.go index 36e8e70f..eddeb3b3 100644 --- a/internal/application/service/session_knowledge_qa.go +++ b/internal/application/service/session_knowledge_qa.go @@ -12,6 +12,7 @@ import ( "github.com/Tencent/WeKnora/internal/event" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/models/chat" + "github.com/Tencent/WeKnora/internal/tracing/langfuse" "github.com/Tencent/WeKnora/internal/types" ) @@ -32,6 +33,17 @@ func (s *sessionService) KnowledgeQA( req.EnableMemory, ) + // Span the request setup (KB / model resolution, search target building, + // agent override application). This covers the visible gap between trace + // start and the first stage observation in the Langfuse timeline. + setupCtx, setupSpan := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{ + Name: "qa.setup", + Metadata: map[string]interface{}{ + "session_id": req.Session.ID, + }, + }) + ctx = setupCtx + // Resolve knowledge bases using shared helper knowledgeBaseIDs, knowledgeIDs := s.resolveKnowledgeBases(ctx, req) @@ -191,6 +203,11 @@ func (s *sessionService) KnowledgeQA( // Start knowledge QA event processing (set session tenant so pipeline session/message lookups use session owner) ctx = context.WithValue(ctx, types.SessionTenantIDContextKey, req.Session.TenantID) logger.Info(ctx, "Triggering question answering event") + setupSpan.Finish(map[string]interface{}{ + "stages": len(pipeline), + "knowledge_base_ids": knowledgeBaseIDs, + "search_targets": len(searchTargets), + }, nil, nil) err = s.KnowledgeQAByEvent(ctx, chatManage, pipeline) if err != nil { logger.ErrorWithFields(ctx, err, map[string]interface{}{ @@ -536,8 +553,40 @@ func (s *sessionService) KnowledgeQAByEvent(ctx context.Context, pipelineStart := time.Now() for _, eventType := range eventList { stageStart := time.Now() - err := s.eventManager.Trigger(ctx, eventType, chatManage) + // Wrap each pipeline stage in a Langfuse span so the trace timeline + // shows the gaps between LLM/embedding/rerank generations (the work + // that happens between them — vector DB search, merge, filter, prompt + // assembly — was previously invisible). Generations created inside + // the stage automatically nest under this span. + // + // CHAT_COMPLETION_STREAM is intentionally skipped: its OnEvent kicks + // off a streaming goroutine and returns immediately, so a span would + // finish well before the chat.completion.stream generation does. The + // generation already captures the full stream duration; adding a + // stage span here would just produce a child observation that + // visually exceeds its parent. + stageCtx := ctx + var stageSpan *langfuse.Span + if eventType != types.CHAT_COMPLETION_STREAM { + stageCtx, stageSpan = langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{ + Name: "pipeline." + string(eventType), + Metadata: map[string]interface{}{ + "event_type": string(eventType), + "session_id": chatManage.SessionID, + }, + }) + } + err := s.eventManager.Trigger(stageCtx, eventType, chatManage) stageDuration := time.Since(stageStart) + var spanErr error + if err != nil && err != chatpipeline.ErrSearchNothing { + spanErr = err.Err + } + if stageSpan != nil { + stageSpan.Finish(map[string]interface{}{ + "duration_ms": stageDuration.Milliseconds(), + }, nil, spanErr) + } if err == chatpipeline.ErrSearchNothing { common.PipelineWarn(ctx, "Pipeline", "stage_fallback", map[string]interface{}{ @@ -664,7 +713,19 @@ func (s *sessionService) SearchKnowledge(ctx context.Context, for _, event := range searchEvents { logger.Infof(ctx, "Starting to trigger search event: %v", event) - err := s.eventManager.Trigger(ctx, event, chatManage) + stageCtx, stageSpan := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{ + Name: "pipeline." + string(event), + Metadata: map[string]interface{}{ + "event_type": string(event), + "flow": "search_knowledge", + }, + }) + err := s.eventManager.Trigger(stageCtx, event, chatManage) + var spanErr error + if err != nil && err != chatpipeline.ErrSearchNothing { + spanErr = err.Err + } + stageSpan.Finish(nil, nil, spanErr) if err == chatpipeline.ErrSearchNothing { logger.Warnf(ctx, "Event %v triggered, search result is empty", event)