fix(observability): nest follow-up completions under the chat trace

POST /suggestions often wins the race to generate follow-ups and has no
Langfuse parent, so chat.completion auto-creates an orphan root. Stamp
the originating W3C traceparent on the assistant message and resume it
before the extra LLM call.
main
wizardchen 2026-08-31 19:24:06 +08:00 committed by lyingbug
parent 81142dfd17
commit 7fbbaffb9f
5 changed files with 162 additions and 10 deletions

View File

@ -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"

View File

@ -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

View File

@ -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
}

View File

@ -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")
}

View File

@ -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) {