feat(observability): expand Langfuse spans across chat pipeline

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.<event> 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.
This commit is contained in:
wizardchen
2026-05-12 21:11:54 +08:00
committed by lyingbug
parent 64b20a2d87
commit f740e7cecf
3 changed files with 100 additions and 5 deletions
@@ -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,
@@ -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,
@@ -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)