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
parent
81142dfd17
commit
7fbbaffb9f
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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) {
|
||||
|
|
|
|||
Loading…
Reference in New Issue