Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(observability): nest follow-up completions under the chat trace
wizardchen7fbbaffb9ff2
diff --git a/internal/application/service/message_suggestion.go b/internal/application/service/message_suggestion.goindex ba9c4762a..c825110d8 100644--- a/internal/application/service/message_suggestion.go+++ b/internal/application/service/message_suggestion.go@@ -14,6 +14,7 @@ import ("github.com/Tencent/WeKnora/internal/logger""github.com/Tencent/WeKnora/internal/models/chat""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""github.com/google/uuid"@@ -258,7 +259,30 @@ func (s *messageSuggestionService) generate(message *types.Message,answer string,config types.FollowUpSuggestionConfig,-) (types.SuggestionItems, types.TokenUsage, error) {+) (questions types.SuggestionItems, usage types.TokenUsage, err error) {+ // The LLM call often runs on POST .../suggestions (frontend onTurnComplete)+ // or after GinMiddleware has already ended the HTTP root. Resume the+ // originating chat trace so chat.completion nests under that turn instead+ // of auto-creating an orphan root.+ ctx = langfuse.AttachTraceparent(ctx, message.ExecutionContext.LangfuseTraceparent)+ ctx, span := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{+ Name: "follow_up.suggestions",+ Input: map[string]interface{}{+ "session_id": message.SessionID,+ "assistant_message_id": message.ID,+ "mode": config.Mode,+ },+ Metadata: map[string]interface{}{+ "count": config.Count,+ "model_id": config.ModelID,+ },+ })+ defer func() {+ span.Finish(map[string]interface{}{+ "question_count": len(questions),+ }, nil, err)+ }()+count := config.Countif count < 1 {count = 3@@ -269,7 +293,6 @@ func (s *messageSuggestionService) generate(}var generated types.SuggestionItemsvar knowledge types.SuggestionItems- var usage types.TokenUsagevar modelErr errorif config.Mode == types.SuggestionModeGenerated || config.Mode == types.SuggestionModeHybrid {generated, usage, modelErr = s.generateWithModel(@@ -329,6 +352,7 @@ func (s *messageSuggestionService) generateWithModel(if err != nil {return nil, types.TokenUsage{}, err}+ modelCtx = types.WithLLMCallMetadata(modelCtx, "follow_up.suggestions", "")categories := strings.Join(config.Categories, ", ")if categories == "" {categories = "clarify, deepen, action"diff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.goindex 595d524a1..795491c38 100644--- a/internal/handler/session/qa.go+++ b/internal/handler/session/qa.go@@ -18,6 +18,7 @@ import ("github.com/Tencent/WeKnora/internal/event""github.com/Tencent/WeKnora/internal/logger""github.com/Tencent/WeKnora/internal/storageurl"+ "github.com/Tencent/WeKnora/internal/tracing/langfuse""github.com/Tencent/WeKnora/internal/types"secutils "github.com/Tencent/WeKnora/internal/utils""github.com/gin-gonic/gin"@@ -437,14 +438,15 @@ func buildMessageExecutionContext(locale := types.LanguageFromContextOrDefault(ctx)snapshot := types.MessageExecutionContext{- KnowledgeBaseIDs: knowledgeBaseIDs,- KnowledgeIDs: knowledgeIDs,- TagIDs: tagIDs,- TagScopes: cloneTagScopes(tagScopes),- MCPServiceIDs: mcpServiceIDs,- SkillNames: skillNames,- WebSearchEnabled: webSearchEnabled,- Locale: locale,+ KnowledgeBaseIDs: knowledgeBaseIDs,+ KnowledgeIDs: knowledgeIDs,+ TagIDs: tagIDs,+ TagScopes: cloneTagScopes(tagScopes),+ MCPServiceIDs: mcpServiceIDs,+ SkillNames: skillNames,+ WebSearchEnabled: webSearchEnabled,+ Locale: locale,+ LangfuseTraceparent: langfuse.TraceparentFromContext(ctx),}if agent == nil {return snapshot, "", effectiveTenantID, modelOverridediff --git a/internal/tracing/langfuse/context.go b/internal/tracing/langfuse/context.goindex 236e2c2d2..61e55c4ae 100644--- a/internal/tracing/langfuse/context.go+++ b/internal/tracing/langfuse/context.go@@ -4,6 +4,8 @@ import ("context""github.com/Tencent/WeKnora/internal/types"+ "go.opentelemetry.io/otel/propagation"+ oteltrace "go.opentelemetry.io/otel/trace")// traceCtxKey is the exported context key defined in types/const.go. It lives@@ -43,3 +45,41 @@ func traceFromCtx(ctx context.Context) (*Trace, bool) {func TraceFromContext(ctx context.Context) (*Trace, bool) {return traceFromCtx(ctx)}++// TraceparentFromContext returns the W3C traceparent for the active span, or+// empty when Langfuse is disabled or ctx carries no span. Used to stamp the+// originating chat trace onto derived work (follow-up suggestions) that may+// run after the HTTP handler returns, or on a later request.+func TraceparentFromContext(ctx context.Context) string {+ mgr := GetManager()+ if ctx == nil || !mgr.Enabled() {+ return ""+ }+ c := propagation.MapCarrier{}+ propagator.Inject(ctx, c)+ return c["traceparent"]+}++// AttachTraceparent resumes the originating trace from a W3C traceparent+// previously captured by TraceparentFromContext / InjectTracing. When ctx+// already has a *Trace (same-request background work), it is left unchanged+// so we do not replace a live local parent with a remote one.+//+// This is the in-process counterpart of AsynqMiddleware's extract path: a+// later HTTP request (e.g. POST .../suggestions) has no GinMiddleware trace,+// and without this StartGeneration would auto-create an orphan root named+// after the LLM call.+func AttachTraceparent(ctx context.Context, traceparent string) context.Context {+ mgr := GetManager()+ if ctx == nil || traceparent == "" || !mgr.Enabled() {+ return ctx+ }+ if _, ok := traceFromCtx(ctx); ok {+ return ctx+ }+ ctx = propagator.Extract(ctx, propagation.MapCarrier{"traceparent": traceparent})+ if sc := oteltrace.SpanContextFromContext(ctx); sc.IsValid() {+ ctx = withTrace(ctx, &Trace{ID: sc.TraceID().String(), manager: mgr})+ }+ return ctx+}diff --git a/internal/tracing/langfuse/tracer_test.go b/internal/tracing/langfuse/tracer_test.goindex e4c2ed85b..29fb73694 100644--- a/internal/tracing/langfuse/tracer_test.go+++ b/internal/tracing/langfuse/tracer_test.go@@ -311,3 +311,83 @@ func TestTraceparentPropagation(t *testing.T) {}t.Fatal("weknora-root span not exported")}++// TestAttachTraceparent_FollowUpJoinsOriginatingTrace is the follow-up+// suggestion regression: generation often runs on a later HTTP request+// (POST .../suggestions) after the chat handler has already ended its root+// span. Without AttachTraceparent, StartGeneration auto-opens an orphan+// root named after the LLM call. With it, the follow-up span and generation+// inherit the originating chat trace id.+func TestAttachTraceparent_FollowUpJoinsOriginatingTrace(t *testing.T) {+ m, exp := newTestManager(t)++ httpCtx, httpTrace := m.StartTrace(context.Background(), TraceOptions{Name: "POST /api/v1/agent-chat/:session_id"})+ traceparent := TraceparentFromContext(httpCtx)+ if traceparent == "" {+ t.Fatal("expected a traceparent on the HTTP trace")+ }+ httpTrace.Finish(nil, nil)++ // Separate request: no *Trace, no OTel span — this is POST /suggestions.+ followCtx := AttachTraceparent(context.Background(), traceparent)+ followCtx, span := m.StartSpan(followCtx, SpanOptions{Name: "follow_up.suggestions"})+ _, gen := m.StartGeneration(followCtx, GenerationOptions{Name: "chat.completion", Model: "m"})+ gen.Finish("qs", nil, nil)+ span.Finish(nil, nil, nil)++ var followSpan, generation tracetest.SpanStub+ var autoRoot bool+ for _, s := range exp.GetSpans() {+ switch {+ case s.Name == "follow_up.suggestions" && spanType(s) == obsTypeSpan:+ followSpan = s+ case s.Name == "chat.completion" && spanType(s) == obsTypeGeneration:+ generation = s+ case s.Name == "chat.completion" && spanType(s) == obsTypeTrace:+ autoRoot = true+ }+ }+ if followSpan.Name == "" {+ t.Fatal("follow_up.suggestions span not exported")+ }+ if generation.Name == "" {+ t.Fatal("chat.completion generation not exported")+ }+ if followSpan.SpanContext.TraceID().String() != httpTrace.ID {+ t.Errorf("follow-up span trace id = %s, want HTTP %s", followSpan.SpanContext.TraceID(), httpTrace.ID)+ }+ if generation.SpanContext.TraceID().String() != httpTrace.ID {+ t.Errorf("generation trace id = %s, want HTTP %s", generation.SpanContext.TraceID(), httpTrace.ID)+ }+ if autoRoot {+ t.Error("StartGeneration opened an orphan chat.completion root; traceparent was not attached")+ }+}++// TestAttachTraceparent_LeavesExistingTrace ensures same-request background+// work (completeAssistantMessage) is not re-parented onto a stale remote+// span when ctx already carries a live *Trace.+func TestAttachTraceparent_LeavesExistingTrace(t *testing.T) {+ m, exp := newTestManager(t)++ otherCtx, other := m.StartTrace(context.Background(), TraceOptions{Name: "other"})+ otherParent := TraceparentFromContext(otherCtx)+ other.Finish(nil, nil)++ ctx, live := m.StartTrace(context.Background(), TraceOptions{Name: "live"})+ ctx = AttachTraceparent(ctx, otherParent)+ _, gen := m.StartGeneration(ctx, GenerationOptions{Name: "chat.completion", Model: "m"})+ gen.Finish("out", nil, nil)+ live.Finish(nil, nil)++ for _, s := range exp.GetSpans() {+ if spanType(s) != obsTypeGeneration {+ continue+ }+ if s.SpanContext.TraceID().String() != live.ID {+ t.Errorf("generation joined foreign trace %s, want live %s", s.SpanContext.TraceID(), live.ID)+ }+ return+ }+ t.Fatal("generation span not exported")+}diff --git a/internal/types/message.go b/internal/types/message.goindex fc0d9d917..a2a2f3505 100644--- a/internal/types/message.go+++ b/internal/types/message.go@@ -337,6 +337,12 @@ type MessageExecutionContext struct {WebSearchEnabled bool `json:"web_search_enabled"`Locale string `json:"locale,omitempty"`SuggestionAttribution *SuggestionAttribution `json:"suggestion_attribution,omitempty"`+ // LangfuseTraceparent is the W3C traceparent of the originating chat+ // request. Follow-up suggestion generation often runs on a later HTTP+ // call (or after the SSE handler has already finished the root span);+ // without this the LLM wrapper auto-creates an orphan chat.completion+ // trace instead of nesting under the agent turn.+ LangfuseTraceparent string `json:"langfuse_traceparent,omitempty"`}func (c MessageExecutionContext) Value() (driver.Value, error) {