Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

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.go
index 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.Count
if count < 1 {
count = 3
@@ -269,7 +293,6 @@ func (s *messageSuggestionService) generate(
}
var generated types.SuggestionItems
var knowledge types.SuggestionItems
- var usage types.TokenUsage
var modelErr error
if 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.go
index 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, modelOverride
diff --git a/internal/tracing/langfuse/context.go b/internal/tracing/langfuse/context.go
index 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.go
index 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.go
index 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) {