Files
Enterprise-Knowledge-Base/internal/tracing/langfuse/tracer_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

196 lines
5.9 KiB
Go

package langfuse
import (
"context"
"encoding/json"
"errors"
"io"
"net/http"
"net/http/httptest"
"sync"
"testing"
"time"
)
// newTestServer spins up a fake Langfuse ingestion endpoint and returns the
// collected events + a cleanup func.
func newTestServer(t *testing.T) (*httptest.Server, func() []ingestionEvent) {
t.Helper()
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(`{}`))
}))
drain := func() []ingestionEvent {
mu.Lock()
defer mu.Unlock()
var out []ingestionEvent
for _, b := range batches {
out = append(out, b.Batch...)
}
return out
}
return srv, drain
}
func newTestManager(t *testing.T, host string) *Manager {
t.Helper()
m, err := Init(Config{
Enabled: true,
Host: host,
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)
}
return m
}
// TestSpan_NestedHierarchy verifies that nested StartSpan calls produce a
// trace → span₁ → span₂ → generation hierarchy, with parentObservationId
// pointing to the direct ancestor at each level.
func TestSpan_NestedHierarchy(t *testing.T) {
srv, drain := newTestServer(t)
defer srv.Close()
m := newTestManager(t, srv.URL)
ctx, trace := m.StartTrace(context.Background(), TraceOptions{Name: "root"})
ctx, outer := m.StartSpan(ctx, SpanOptions{Name: "outer"})
ctx, inner := m.StartSpan(ctx, SpanOptions{Name: "inner"})
_, gen := m.StartGeneration(ctx, GenerationOptions{Name: "llm", Model: "m"})
gen.Finish("out", &TokenUsage{Input: 1, Output: 2, Total: 3}, nil)
inner.Finish("inner-out", nil, nil)
outer.Finish("outer-out", nil, nil)
trace.Finish("root-out", nil)
if err := m.Shutdown(context.Background()); err != nil {
t.Fatalf("shutdown: %v", err)
}
events := drain()
parentOf := map[string]string{}
traceOf := map[string]string{}
kindOf := map[string]string{}
for _, ev := range events {
if ev.Type != "span-create" && ev.Type != "generation-create" {
continue
}
b, _ := json.Marshal(ev.Body)
var ob observationBody
_ = json.Unmarshal(b, &ob)
parentOf[ob.ID] = ob.ParentObservationID
traceOf[ob.ID] = ob.TraceID
kindOf[ob.ID] = ob.Type
}
if traceOf[outer.ID] != trace.ID || parentOf[outer.ID] != "" {
t.Errorf("outer span should sit directly under the trace, got parent=%q trace=%q", parentOf[outer.ID], traceOf[outer.ID])
}
if parentOf[inner.ID] != outer.ID {
t.Errorf("inner span parent mismatch: got %q want %q", parentOf[inner.ID], outer.ID)
}
if parentOf[gen.ID] != inner.ID {
t.Errorf("generation should nest under inner span, got parent=%q want %q", parentOf[gen.ID], inner.ID)
}
if kindOf[outer.ID] != "SPAN" || kindOf[inner.ID] != "SPAN" {
t.Errorf("expected both wrappers to be SPAN observations, got outer=%q inner=%q", kindOf[outer.ID], kindOf[inner.ID])
}
if kindOf[gen.ID] != "GENERATION" {
t.Errorf("expected generation kind, got %q", kindOf[gen.ID])
}
}
// TestSpan_FinishWithError records an error status on the span so failures in
// asynq handlers surface as red observations in Langfuse.
func TestSpan_FinishWithError(t *testing.T) {
srv, drain := newTestServer(t)
defer srv.Close()
m := newTestManager(t, srv.URL)
ctx, _ := m.StartTrace(context.Background(), TraceOptions{Name: "root"})
_, span := m.StartSpan(ctx, SpanOptions{Name: "boom"})
span.Finish(nil, nil, errors.New("kaboom"))
if err := m.Shutdown(context.Background()); err != nil {
t.Fatalf("shutdown: %v", err)
}
var sawError bool
for _, ev := range drain() {
if ev.Type != "span-update" {
continue
}
b, _ := json.Marshal(ev.Body)
var ob observationBody
_ = json.Unmarshal(b, &ob)
if ob.Level == "ERROR" && ob.StatusMessage == "kaboom" {
sawError = true
}
}
if !sawError {
t.Fatal("expected span-update with ERROR level and status message")
}
}
// TestResumeTrace_NoTraceCreateEvent verifies that ResumeTrace does NOT
// emit a trace-create event — the originating HTTP handler already did,
// and a duplicate would register as an orphan root in the Langfuse UI.
func TestResumeTrace_NoTraceCreateEvent(t *testing.T) {
srv, drain := newTestServer(t)
defer srv.Close()
m := newTestManager(t, srv.URL)
ctx, trace := m.ResumeTrace(context.Background(), "upstream-trace", "upstream-span")
if trace == nil || trace.ID != "upstream-trace" {
t.Fatalf("expected resumed trace with id upstream-trace, got %+v", trace)
}
if pid, ok := parentObservationFromCtx(ctx); !ok || pid != "upstream-span" {
t.Errorf("expected parent observation upstream-span on ctx, got %q (ok=%v)", pid, ok)
}
// Emit one child so there's *something* to flush, proving only child
// observations reach the wire, not a trace-create for the resume.
_, span := m.StartSpan(ctx, SpanOptions{Name: "child"})
span.Finish(nil, nil, nil)
if err := m.Shutdown(context.Background()); err != nil {
t.Fatalf("shutdown: %v", err)
}
for _, ev := range drain() {
if ev.Type == "trace-create" {
t.Fatalf("ResumeTrace must not emit trace-create events, got %+v", ev)
}
}
}
// TestResumeTrace_DisabledIsSafe guards against nil deref when Langfuse is
// off: ResumeTrace should return a nil *Trace and the original ctx unchanged.
func TestResumeTrace_DisabledIsSafe(t *testing.T) {
m, err := Init(Config{Enabled: false})
if err != nil {
t.Fatalf("init: %v", err)
}
ctx, trace := m.ResumeTrace(context.Background(), "x", "y")
if trace != nil {
t.Errorf("expected nil trace when disabled, got %+v", trace)
}
if _, ok := parentObservationFromCtx(ctx); ok {
t.Error("disabled ResumeTrace should not attach parent observation")
}
}