beca2b89a3
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).
335 lines
9.5 KiB
Go
335 lines
9.5 KiB
Go
package langfuse
|
|
|
|
import (
|
|
"context"
|
|
"time"
|
|
)
|
|
|
|
// Trace represents an active root observation. A Trace is conceptually one
|
|
// "request" (e.g. a chat turn). Generations and spans attached to it roll up
|
|
// as children in the Langfuse UI.
|
|
type Trace struct {
|
|
ID string
|
|
manager *Manager
|
|
sampled bool
|
|
}
|
|
|
|
// Generation represents a single model invocation (LLM / embedding / VLM).
|
|
type Generation struct {
|
|
ID string
|
|
TraceID string
|
|
ParentObservationID string
|
|
manager *Manager
|
|
sampled bool
|
|
startTime time.Time
|
|
model string
|
|
name string
|
|
}
|
|
|
|
// Span represents a logical unit of work that isn't itself an LLM call — for
|
|
// example an asynq task execution, a pipeline stage, or a document-processing
|
|
// step. Generations and nested spans attach to it via parentObservationId.
|
|
type Span struct {
|
|
ID string
|
|
TraceID string
|
|
ParentObservationID string
|
|
manager *Manager
|
|
sampled bool
|
|
startTime time.Time
|
|
name string
|
|
}
|
|
|
|
// TraceOptions configures a new trace.
|
|
type TraceOptions struct {
|
|
Name string
|
|
UserID string
|
|
SessionID string
|
|
Input interface{}
|
|
Metadata map[string]interface{}
|
|
Tags []string
|
|
Environment string
|
|
Release string
|
|
}
|
|
|
|
// GenerationOptions configures a new generation observation.
|
|
type GenerationOptions struct {
|
|
Name string
|
|
Model string
|
|
Input interface{}
|
|
Metadata map[string]interface{}
|
|
ModelParameters map[string]interface{}
|
|
}
|
|
|
|
// SpanOptions configures a new SPAN observation.
|
|
type SpanOptions struct {
|
|
Name string
|
|
Input interface{}
|
|
Metadata map[string]interface{}
|
|
}
|
|
|
|
// StartTrace opens a new trace, stores its ID in the returned ctx, and returns
|
|
// a handle callers can finish with FinishTrace. When the manager is disabled
|
|
// or sampling excludes the trace, the returned *Trace is non-nil but all
|
|
// methods are no-ops so callers don't need nil checks.
|
|
func (m *Manager) StartTrace(ctx context.Context, opts TraceOptions) (context.Context, *Trace) {
|
|
if m == nil || !m.cfg.Enabled {
|
|
return ctx, &Trace{}
|
|
}
|
|
sampled := m.sample()
|
|
id := newID()
|
|
t := &Trace{ID: id, manager: m, sampled: sampled}
|
|
|
|
if sampled {
|
|
env := opts.Environment
|
|
if env == "" {
|
|
env = m.cfg.Environment
|
|
}
|
|
release := opts.Release
|
|
if release == "" {
|
|
release = m.cfg.Release
|
|
}
|
|
body := traceBody{
|
|
ID: id,
|
|
Timestamp: isoTime(time.Now()),
|
|
Name: opts.Name,
|
|
UserID: opts.UserID,
|
|
SessionID: opts.SessionID,
|
|
Input: opts.Input,
|
|
Metadata: opts.Metadata,
|
|
Tags: opts.Tags,
|
|
Environment: env,
|
|
Release: release,
|
|
}
|
|
m.enqueue(ingestionEvent{
|
|
ID: newID(),
|
|
Timestamp: isoTime(time.Now()),
|
|
Type: "trace-create",
|
|
Body: body,
|
|
})
|
|
}
|
|
return withTrace(ctx, t), t
|
|
}
|
|
|
|
// Finish updates the trace with its final output. Safe to call on a disabled
|
|
// trace (no-op).
|
|
func (t *Trace) Finish(output interface{}, metadata map[string]interface{}) {
|
|
if t == nil || t.manager == nil || !t.sampled {
|
|
return
|
|
}
|
|
// "trace-create" events are also used to update traces in Langfuse —
|
|
// the server merges repeated events by ID. See the ingestion API docs.
|
|
body := traceBody{
|
|
ID: t.ID,
|
|
Output: output,
|
|
Metadata: metadata,
|
|
}
|
|
t.manager.enqueue(ingestionEvent{
|
|
ID: newID(),
|
|
Timestamp: isoTime(time.Now()),
|
|
Type: "trace-create",
|
|
Body: body,
|
|
})
|
|
}
|
|
|
|
// ResumeTrace reconstructs a *Trace handle from an upstream-provided trace id
|
|
// (and optional parent observation id), without emitting a new trace-create
|
|
// event. Used by the asynq middleware to graft async work onto the HTTP-level
|
|
// trace that originated it: the HTTP layer already issued trace-create, and
|
|
// the worker only needs to add child observations.
|
|
//
|
|
// When traceID is empty the returned *Trace is nil, signalling the caller
|
|
// should fall back to StartTrace if it wants a standalone root.
|
|
func (m *Manager) ResumeTrace(ctx context.Context, traceID, parentObservationID string) (context.Context, *Trace) {
|
|
if m == nil || !m.cfg.Enabled || traceID == "" {
|
|
return ctx, nil
|
|
}
|
|
t := &Trace{ID: traceID, manager: m, sampled: true}
|
|
ctx = withTrace(ctx, t)
|
|
if parentObservationID != "" {
|
|
ctx = withParentObservation(ctx, parentObservationID)
|
|
}
|
|
return ctx, t
|
|
}
|
|
|
|
// StartSpan opens a SPAN observation under the trace (and optional parent
|
|
// observation) carried by ctx. When no trace is present, a shallow trace is
|
|
// auto-created, mirroring StartGeneration's behaviour. Returns a ctx whose
|
|
// parentObservationId is set to this span's id, so any nested span or
|
|
// generation will properly attach as a child.
|
|
func (m *Manager) StartSpan(ctx context.Context, opts SpanOptions) (context.Context, *Span) {
|
|
if m == nil || !m.cfg.Enabled {
|
|
return ctx, &Span{}
|
|
}
|
|
trace, ok := traceFromCtx(ctx)
|
|
if !ok || trace == nil {
|
|
newCtx, t := m.StartTrace(ctx, TraceOptions{Name: opts.Name})
|
|
ctx = newCtx
|
|
trace = t
|
|
}
|
|
if !trace.sampled {
|
|
return ctx, &Span{}
|
|
}
|
|
parent, _ := parentObservationFromCtx(ctx)
|
|
now := time.Now()
|
|
s := &Span{
|
|
ID: newID(),
|
|
TraceID: trace.ID,
|
|
ParentObservationID: parent,
|
|
manager: m,
|
|
sampled: true,
|
|
startTime: now,
|
|
name: opts.Name,
|
|
}
|
|
body := observationBody{
|
|
ID: s.ID,
|
|
TraceID: s.TraceID,
|
|
ParentObservationID: parent,
|
|
Type: "SPAN",
|
|
Name: opts.Name,
|
|
StartTime: isoTime(now),
|
|
Input: opts.Input,
|
|
Metadata: opts.Metadata,
|
|
}
|
|
m.enqueue(ingestionEvent{
|
|
ID: newID(),
|
|
Timestamp: isoTime(now),
|
|
Type: "span-create",
|
|
Body: body,
|
|
})
|
|
ctx = withParentObservation(ctx, s.ID)
|
|
return ctx, s
|
|
}
|
|
|
|
// Finish updates a span with its final output, extra metadata and any error.
|
|
// A non-nil err marks the span as ERROR level in Langfuse.
|
|
func (s *Span) Finish(output interface{}, metadata map[string]interface{}, err error) {
|
|
if s == nil || s.manager == nil || !s.sampled {
|
|
return
|
|
}
|
|
level := "DEFAULT"
|
|
var statusMsg string
|
|
if err != nil {
|
|
level = "ERROR"
|
|
statusMsg = err.Error()
|
|
}
|
|
body := observationBody{
|
|
ID: s.ID,
|
|
TraceID: s.TraceID,
|
|
Type: "SPAN",
|
|
EndTime: isoTime(time.Now()),
|
|
Output: output,
|
|
Metadata: metadata,
|
|
Level: level,
|
|
StatusMessage: statusMsg,
|
|
}
|
|
s.manager.enqueue(ingestionEvent{
|
|
ID: newID(),
|
|
Timestamp: isoTime(time.Now()),
|
|
Type: "span-update",
|
|
Body: body,
|
|
})
|
|
}
|
|
|
|
// StartGeneration opens a generation observation under the trace carried by
|
|
// ctx (or a newly auto-created trace if none is present). If a parent span
|
|
// is present on ctx, the generation attaches under it via parentObservationId
|
|
// so the Langfuse tree shows: trace → span → generation.
|
|
func (m *Manager) StartGeneration(ctx context.Context, opts GenerationOptions) (context.Context, *Generation) {
|
|
if m == nil || !m.cfg.Enabled {
|
|
return ctx, &Generation{}
|
|
}
|
|
// If the caller hasn't opened a trace yet, create a shallow auto-trace so
|
|
// the generation has a parent. This keeps single-shot internal callers
|
|
// (e.g. test connections) observable.
|
|
trace, ok := traceFromCtx(ctx)
|
|
if !ok || trace == nil {
|
|
newCtx, t := m.StartTrace(ctx, TraceOptions{Name: opts.Name})
|
|
ctx = newCtx
|
|
trace = t
|
|
}
|
|
if !trace.sampled {
|
|
return ctx, &Generation{}
|
|
}
|
|
parent, _ := parentObservationFromCtx(ctx)
|
|
now := time.Now()
|
|
g := &Generation{
|
|
ID: newID(),
|
|
TraceID: trace.ID,
|
|
ParentObservationID: parent,
|
|
manager: m,
|
|
sampled: true,
|
|
startTime: now,
|
|
model: opts.Model,
|
|
name: opts.Name,
|
|
}
|
|
body := observationBody{
|
|
ID: g.ID,
|
|
TraceID: g.TraceID,
|
|
ParentObservationID: parent,
|
|
Type: "GENERATION",
|
|
Name: opts.Name,
|
|
StartTime: isoTime(now),
|
|
Input: opts.Input,
|
|
Metadata: opts.Metadata,
|
|
Model: opts.Model,
|
|
ModelParameters: opts.ModelParameters,
|
|
}
|
|
m.enqueue(ingestionEvent{
|
|
ID: newID(),
|
|
Timestamp: isoTime(now),
|
|
Type: "generation-create",
|
|
Body: body,
|
|
})
|
|
return ctx, g
|
|
}
|
|
|
|
// Finish updates a generation with its final output, token usage and any
|
|
// error. A non-nil err marks the observation as ERROR level in Langfuse.
|
|
func (g *Generation) Finish(output interface{}, usage *TokenUsage, err error) {
|
|
if g == nil || g.manager == nil || !g.sampled {
|
|
return
|
|
}
|
|
level := "DEFAULT"
|
|
var statusMsg string
|
|
if err != nil {
|
|
level = "ERROR"
|
|
statusMsg = err.Error()
|
|
}
|
|
body := observationBody{
|
|
ID: g.ID,
|
|
TraceID: g.TraceID,
|
|
Type: "GENERATION",
|
|
EndTime: isoTime(time.Now()),
|
|
Output: output,
|
|
Usage: usage,
|
|
Level: level,
|
|
StatusMessage: statusMsg,
|
|
}
|
|
g.manager.enqueue(ingestionEvent{
|
|
ID: newID(),
|
|
Timestamp: isoTime(time.Now()),
|
|
Type: "generation-update",
|
|
Body: body,
|
|
})
|
|
}
|
|
|
|
// MarkCompletionStart records the time at which the first token was received
|
|
// in a streaming generation. Langfuse surfaces this as time-to-first-token.
|
|
func (g *Generation) MarkCompletionStart(t time.Time) {
|
|
if g == nil || g.manager == nil || !g.sampled {
|
|
return
|
|
}
|
|
body := observationBody{
|
|
ID: g.ID,
|
|
TraceID: g.TraceID,
|
|
Type: "GENERATION",
|
|
CompletionStart: isoTime(t),
|
|
}
|
|
g.manager.enqueue(ingestionEvent{
|
|
ID: newID(),
|
|
Timestamp: isoTime(time.Now()),
|
|
Type: "generation-update",
|
|
Body: body,
|
|
})
|
|
}
|