Files
Enterprise-Knowledge-Base/internal/tracing/langfuse/asynq_test.go
T
wizardchen beca2b89a3 feat(observability): extend Langfuse tracing across asynq pipeline
Previously the Langfuse integration only traced in-process HTTP requests
(chat / search / eval), so file uploads and every downstream asynq task
(document parse, chunk embedding, OCR/VLM, summary / question gen, wiki
ingest, datasource sync, etc.) produced either disconnected shallow
traces or no observation at all.

This change threads one trace end-to-end:

- tracer: add SPAN observation type and StartSpan; add ResumeTrace so a
  worker can attach to an upstream trace without emitting a duplicate
  trace-create; StartGeneration now auto-picks parentObservationId from
  ctx so nested trace -> span -> generation trees render correctly.
- types.TracingContext + LangfuseTracingCarrier: embed on all 17 asynq
  payloads so trace_id / parent_obs_id / user_id / session_id serialise
  into every job.
- langfuse.InjectTracing: injected at 28 enqueue sites before json.Marshal
  so the HTTP-layer trace survives the Redis hop.
- langfuse.AsynqMiddleware: mux.Use hook that peeks the payload, either
  resumes the upstream trace or opens a standalone asynq.<type> trace
  for scheduled jobs, and wraps the handler in a SPAN with task metadata
  (id / queue / retry / payload_bytes) plus ERROR level on failure.
- GinMiddleware.shouldTrace: whitelist ingestion / knowledge-mutation /
  FAQ / wiki / datasource endpoints so the root trace actually starts.
- Tests: tracer_test.go covers span nesting, error status, and
  ResumeTrace no-trace-create guarantee; asynq_test.go covers
  InjectTracing round-trip, middleware resume path, and standalone
  trace fallback.
- Docs: docs/Langfuse\u96c6\u6210.md now lists the covered task types
  and documents the cross-process propagation model.

No behavioural change when Langfuse is disabled (all new code paths are
no-ops and carriers serialise to empty strings with omitempty).
2026-04-24 13:16:47 +08:00

273 lines
8.1 KiB
Go

package langfuse
import (
"context"
"encoding/json"
"io"
"net/http"
"net/http/httptest"
"sync"
"testing"
"time"
"github.com/Tencent/WeKnora/internal/types"
"github.com/hibiken/asynq"
)
// dummyPayload is a minimal payload that embeds TracingContext, mirroring
// how real asynq payloads opt into trace propagation.
type dummyPayload struct {
types.TracingContext
KnowledgeID string `json:"knowledge_id"`
}
// TestInjectTracing_DisabledIsZero verifies InjectTracing is a no-op when
// Langfuse is disabled: no panics, no trace fields written.
func TestInjectTracing_DisabledIsZero(t *testing.T) {
// Explicitly install a disabled manager to shadow any globally-enabled
// one from a previous test in the same package.
_, _ = Init(Config{Enabled: false})
p := &dummyPayload{KnowledgeID: "k1"}
InjectTracing(context.Background(), p)
if p.LangfuseTraceID != "" || p.LangfuseParentObservationID != "" {
t.Fatalf("expected no tracing fields on disabled manager, got %+v", p.TracingContext)
}
}
// TestInjectTracing_PopulatesFromContext checks that when a trace is active
// on the context, its id is copied onto the payload and a subsequent
// peekTracingContext round-trips it correctly.
func TestInjectTracing_PopulatesFromContext(t *testing.T) {
// Stand up a fake ingestion endpoint — Init starts a real flush worker
// and we don't want it to panic on connection refused during the test.
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, _ = io.Copy(io.Discard, r.Body)
w.WriteHeader(200)
_, _ = w.Write([]byte(`{}`))
}))
defer srv.Close()
m, err := Init(Config{
Enabled: true,
Host: srv.URL,
PublicKey: "pk",
SecretKey: "sk",
FlushAt: 16,
FlushInterval: 50 * time.Millisecond,
QueueSize: 16,
RequestTimeout: 2 * time.Second,
SampleRate: 1.0,
})
if err != nil {
t.Fatalf("init: %v", err)
}
defer m.Shutdown(context.Background())
ctx, trace := m.StartTrace(context.Background(), TraceOptions{Name: "parent"})
ctx, span := m.StartSpan(ctx, SpanOptions{Name: "wrap"})
if span == nil || span.ID == "" {
t.Fatalf("expected a span with id, got %+v", span)
}
p := &dummyPayload{KnowledgeID: "k1"}
InjectTracing(ctx, p)
if p.LangfuseTraceID != trace.ID {
t.Errorf("trace id mismatch: got %q want %q", p.LangfuseTraceID, trace.ID)
}
if p.LangfuseParentObservationID != span.ID {
t.Errorf("parent observation id mismatch: got %q want %q", p.LangfuseParentObservationID, span.ID)
}
// Round-trip the payload through JSON, which is what asynq does on the
// wire, and make sure peekTracingContext recovers the ids.
b, err := json.Marshal(p)
if err != nil {
t.Fatalf("marshal: %v", err)
}
got := peekTracingContext(b)
if got.LangfuseTraceID != trace.ID || got.LangfuseParentObservationID != span.ID {
t.Errorf("peek round-trip lost ids: %+v", got)
}
}
// TestAsynqMiddleware_ResumeTrace asserts the middleware grafts a resumed
// trace onto the child handler's context, and that the ingestion endpoint
// receives span-create / span-update events for the wrapper — without
// emitting a duplicate trace-create (which would split the Langfuse UI
// tree into two disconnected roots).
func TestAsynqMiddleware_ResumeTrace(t *testing.T) {
var mu sync.Mutex
var batches []ingestionRequest
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
var req ingestionRequest
_ = json.Unmarshal(body, &req)
mu.Lock()
batches = append(batches, req)
mu.Unlock()
w.WriteHeader(200)
_, _ = w.Write([]byte(`{}`))
}))
defer srv.Close()
m, err := Init(Config{
Enabled: true,
Host: srv.URL,
PublicKey: "pk",
SecretKey: "sk",
FlushAt: 1,
FlushInterval: 5 * time.Millisecond,
QueueSize: 32,
RequestTimeout: 2 * time.Second,
SampleRate: 1.0,
})
if err != nil {
t.Fatalf("init: %v", err)
}
// Build a payload that already carries a trace id (as if the HTTP layer
// injected one at enqueue time).
payload := &dummyPayload{KnowledgeID: "k1"}
payload.LangfuseTraceID = "trace-xyz"
payload.LangfuseParentObservationID = "parent-span-abc"
raw, _ := json.Marshal(payload)
var receivedTraceID, receivedParentID string
var sawTrace bool
handler := asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error {
if tr, ok := TraceFromContext(ctx); ok && tr != nil {
sawTrace = true
receivedTraceID = tr.ID
}
if pid, ok := parentObservationFromCtx(ctx); ok {
receivedParentID = pid
}
return nil
})
mw := AsynqMiddleware()
wrapped := mw(handler)
task := asynq.NewTask("test:type", raw)
if err := wrapped.ProcessTask(context.Background(), task); err != nil {
t.Fatalf("handler err: %v", err)
}
if !sawTrace {
t.Fatal("expected handler ctx to carry a resumed trace")
}
if receivedTraceID != "trace-xyz" {
t.Errorf("trace id mismatch: got %q want trace-xyz", receivedTraceID)
}
if receivedParentID == "" {
t.Error("expected parent observation to be set to the wrapper span id")
}
if err := m.Shutdown(context.Background()); err != nil {
t.Fatalf("shutdown: %v", err)
}
mu.Lock()
defer mu.Unlock()
var sawSpanCreate, sawSpanUpdate, sawTraceCreate bool
for _, b := range batches {
for _, ev := range b.Batch {
switch ev.Type {
case "span-create":
sawSpanCreate = true
// Resumed span should attach to the supplied trace id, not
// a fresh one we made up in the worker.
body, _ := json.Marshal(ev.Body)
var ob observationBody
_ = json.Unmarshal(body, &ob)
if ob.TraceID != "trace-xyz" {
t.Errorf("span-create trace id = %q, want trace-xyz", ob.TraceID)
}
if ob.ParentObservationID != "parent-span-abc" {
t.Errorf("span-create parentObservationId = %q, want parent-span-abc", ob.ParentObservationID)
}
case "span-update":
sawSpanUpdate = true
case "trace-create":
sawTraceCreate = true
}
}
}
if !sawSpanCreate {
t.Error("missing span-create event")
}
if !sawSpanUpdate {
t.Error("missing span-update event")
}
if sawTraceCreate {
t.Error("resumed trace should not emit trace-create events (parent owns them)")
}
}
// TestAsynqMiddleware_StandaloneTrace asserts that when the payload carries
// NO upstream trace id (e.g. a scheduled job), the middleware opens a
// standalone trace tagged with the task type, so the worker-side work
// still shows up in Langfuse.
func TestAsynqMiddleware_StandaloneTrace(t *testing.T) {
var mu sync.Mutex
var batches []ingestionRequest
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
var req ingestionRequest
_ = json.Unmarshal(body, &req)
mu.Lock()
batches = append(batches, req)
mu.Unlock()
w.WriteHeader(200)
_, _ = w.Write([]byte(`{}`))
}))
defer srv.Close()
m, err := Init(Config{
Enabled: true, Host: srv.URL, PublicKey: "pk", SecretKey: "sk",
FlushAt: 1, FlushInterval: 5 * time.Millisecond, QueueSize: 32,
RequestTimeout: 2 * time.Second, SampleRate: 1.0,
})
if err != nil {
t.Fatalf("init: %v", err)
}
payload := &dummyPayload{KnowledgeID: "kX"}
raw, _ := json.Marshal(payload)
handler := asynq.HandlerFunc(func(ctx context.Context, task *asynq.Task) error { return nil })
wrapped := AsynqMiddleware()(handler)
if err := wrapped.ProcessTask(context.Background(), asynq.NewTask("scheduled:ping", raw)); err != nil {
t.Fatalf("handler err: %v", err)
}
if err := m.Shutdown(context.Background()); err != nil {
t.Fatalf("shutdown: %v", err)
}
mu.Lock()
defer mu.Unlock()
// Langfuse uses trace-create events both on open and on update (the
// server merges by id), so we filter to the initial event that carries
// the Name — the finalizing update has no name.
var sawNamedTraceCreate bool
for _, b := range batches {
for _, ev := range b.Batch {
if ev.Type != "trace-create" {
continue
}
body, _ := json.Marshal(ev.Body)
var tb traceBody
_ = json.Unmarshal(body, &tb)
if tb.Name == "asynq.scheduled:ping" {
sawNamedTraceCreate = true
}
}
}
if !sawNamedTraceCreate {
t.Error("standalone run should emit a trace-create with name=asynq.scheduled:ping")
}
}