Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(sandbox): record product-level Langfuse spans and detach idle sweeps

wizardchen2dc8cdb3341d
diff --git a/internal/application/service/artifact_collector.go b/internal/application/service/artifact_collector.go
index 6b364c73b..af873320e 100644
--- a/internal/application/service/artifact_collector.go
+++ b/internal/application/service/artifact_collector.go
@@ -26,6 +26,7 @@ import (
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/sandbox"
+ "github.com/Tencent/WeKnora/internal/tracing/langfuse"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"github.com/google/uuid"
@@ -255,7 +256,7 @@ func (c *ArtifactCollector) collect(
tenantID uint64,
outputDir string,
notify func(pending int),
-) (types.MessageArtifacts, error) {
+) (artifacts types.MessageArtifacts, err error) {
if c == nil || c.fileService == nil {
logger.Infof(ctx, "[ArtifactCollector] skipped: collector or dependencies nil (session=%s)", sessionID)
return nil, nil
@@ -281,6 +282,20 @@ func (c *ArtifactCollector) collect(
return nil, nil
}
+ ctx, span := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{
+ Name: "sandbox.collect_artifacts",
+ Input: map[string]interface{}{
+ "session_id": sessionID,
+ "message_id": messageID,
+ "output_dir": outputDir,
+ },
+ })
+ defer func() {
+ span.Finish(map[string]interface{}{
+ "artifact_count": len(artifacts),
+ }, nil, err)
+ }()
+
logger.Infof(ctx, "[ArtifactCollector] begin session=%s dir=%s", sessionID, outputDir)
entries, err := source.ListSessionFiles(ctx, sessionID, outputDir)
@@ -318,7 +333,7 @@ func (c *ArtifactCollector) collect(
notify(pending)
}
- artifacts := make(types.MessageArtifacts, 0, pending)
+ artifacts = make(types.MessageArtifacts, 0, pending)
for _, entry := range entries {
art, ok := c.maybePersist(ctx, source, sessionID, messageID, tenantID, entry, known)
if !ok {
diff --git a/internal/logger/logger.go b/internal/logger/logger.go
index d7ff2d45e..e7c9665ad 100644
--- a/internal/logger/logger.go
+++ b/internal/logger/logger.go
@@ -529,3 +529,21 @@ func CloneContext(ctx context.Context) context.Context {
return newCtx
}
+
+// CloneContextWithoutTrace copies the same identity keys as CloneContext but
+// drops the Langfuse *Trace handle and the OpenTelemetry span. Use it for
+// background work that must keep tenant/session identity yet must not attach
+// child spans (Docker Engine HTTP, idle sweeps, image pulls kicked off after
+// a tool has returned) onto the originating chat trace.
+func CloneContextWithoutTrace(ctx context.Context) context.Context {
+ newCtx := context.Background()
+ for _, k := range types.ContextKeysClonedAcrossDetach() {
+ if k == types.LangfuseTraceContextKey {
+ continue
+ }
+ if v := ctx.Value(k); v != nil {
+ newCtx = context.WithValue(newCtx, k, v)
+ }
+ }
+ return newCtx
+}
diff --git a/internal/logger/logger_test.go b/internal/logger/logger_test.go
index ff9663b48..37fa88851 100644
--- a/internal/logger/logger_test.go
+++ b/internal/logger/logger_test.go
@@ -279,3 +279,26 @@ func TestCloneContextKeepsTheNonInteractiveOAuthMark(t *testing.T) {
t.Fatal("IsMCPOAuthNonInteractive(cloned) = true for an unmarked context, want interactive prompts to stay possible")
}
}
+
+func TestCloneContextWithoutTraceDropsTheChatTrace(t *testing.T) {
+ t.Parallel()
+
+ const tenantID uint64 = 42
+ ctx := context.WithValue(context.Background(), types.TenantIDContextKey, tenantID)
+ ctx = context.WithValue(ctx, types.LangfuseTraceContextKey, "trace-handle")
+
+ kept := CloneContext(ctx)
+ if kept.Value(types.LangfuseTraceContextKey) != "trace-handle" {
+ t.Fatal("CloneContext must keep the Langfuse trace so same-request work stays nested")
+ }
+
+ detached := CloneContextWithoutTrace(ctx)
+ if detached.Value(types.LangfuseTraceContextKey) != nil {
+ t.Fatal("CloneContextWithoutTrace must drop the Langfuse trace so " +
+ "background sandbox RPCs do not join the chat tree")
+ }
+ got, _ := detached.Value(types.TenantIDContextKey).(uint64)
+ if got != tenantID {
+ t.Fatalf("TenantID = %d, want %d (identity must survive the detach)", got, tenantID)
+ }
+}
diff --git a/internal/sandbox/docker_idle_sweeper.go b/internal/sandbox/docker_idle_sweeper.go
index 10b4bbf7e..4608b0c63 100644
--- a/internal/sandbox/docker_idle_sweeper.go
+++ b/internal/sandbox/docker_idle_sweeper.go
@@ -27,6 +27,7 @@ import (
"sync"
"time"
+ "github.com/Tencent/WeKnora/internal/logger"
"github.com/moby/moby/client"
)
@@ -78,8 +79,11 @@ func (s *dockerIdleSweeper) trigger(ctx context.Context) {
return
}
go func() {
+ // Drop the chat-trace parent: Engine API list/stat/delete from a
+ // sweep must not appear as siblings of agent.round after the tool
+ // that triggered the sweep has already finished its span.
sweepCtx, cancel := context.WithTimeout(
- context.WithoutCancel(ctx), dockerSweepBudget,
+ logger.CloneContextWithoutTrace(ctx), dockerSweepBudget,
)
defer cancel()
if reclaimed, err := s.sweep(sweepCtx); err != nil {
diff --git a/internal/sandbox/langfuse.go b/internal/sandbox/langfuse.go
new file mode 100644
index 000000000..8cab1e67e
--- /dev/null
+++ b/internal/sandbox/langfuse.go
@@ -0,0 +1,272 @@
+package sandbox
+
+import (
+ "context"
+ "unicode/utf8"
+
+ "github.com/Tencent/WeKnora/internal/tracing/langfuse"
+)
+
+const sandboxSpanPreviewRunes = 256
+
+// wrapLangfuseRemoteClient records provider-neutral sandbox RPCs as Langfuse
+// spans (sandbox.exec / sandbox.connect / …) so LiteFuse shows a product-level
+// tree instead of a pile of Docker Engine HTTP calls parented to whatever
+// agent.round happened to be recording. No-op when Langfuse is disabled.
+//
+// Snapshot capability is forwarded: wrapping must not hide RemoteSnapshotManager
+// from SnapshotManagerFrom.
+func wrapLangfuseRemoteClient(inner RemoteSandboxClient) RemoteSandboxClient {
+ if inner == nil {
+ return nil
+ }
+ if _, ok := inner.(*langfuseRemoteClient); ok {
+ return inner
+ }
+ if _, ok := inner.(*langfuseSnapshotClient); ok {
+ return inner
+ }
+ wrapped := langfuseRemoteClient{inner: inner}
+ if _, ok := inner.(RemoteSnapshotManager); ok {
+ return &langfuseSnapshotClient{langfuseRemoteClient: wrapped}
+ }
+ return &wrapped
+}
+
+type langfuseRemoteClient struct {
+ inner RemoteSandboxClient
+}
+
+func (c *langfuseRemoteClient) Provider() RemoteProvider { return c.inner.Provider() }
+
+func (c *langfuseRemoteClient) Capabilities() RemoteSandboxCapabilities {
+ return c.inner.Capabilities()
+}
+
+func (c *langfuseRemoteClient) Health(ctx context.Context) error {
+ return c.inner.Health(ctx)
+}
+
+func (c *langfuseRemoteClient) Create(
+ ctx context.Context, req RemoteCreateRequest,
+) (RemoteSandboxHandle, error) {
+ ctx, span := startSandboxSpan(ctx, "sandbox.create", map[string]interface{}{
+ "template_id": req.TemplateID,
+ }, nil)
+ handle, err := c.inner.Create(ctx, req)
+ span.Finish(sandboxHandleOut(handle), nil, err)
+ return handle, err
+}
+
+func (c *langfuseRemoteClient) Connect(
+ ctx context.Context, sandboxID string,
+) (RemoteSandboxHandle, error) {
+ ctx, span := startSandboxSpan(ctx, "sandbox.connect", map[string]interface{}{
+ "sandbox_id": sandboxID,
+ }, nil)
+ handle, err := c.inner.Connect(ctx, sandboxID)
+ span.Finish(sandboxHandleOut(handle), nil, err)
+ return handle, err
+}
+
+func (c *langfuseRemoteClient) Get(
+ ctx context.Context, sandboxID string,
+) (*RemoteSandboxSummary, error) {
+ return c.inner.Get(ctx, sandboxID)
+}
+
+func (c *langfuseRemoteClient) List(
+ ctx context.Context, filter RemoteListFilter,
+) ([]RemoteSandboxSummary, error) {
+ return c.inner.List(ctx, filter)
+}
+
+func (c *langfuseRemoteClient) Delete(ctx context.Context, sandboxID string) error {
+ ctx, span := startSandboxSpan(ctx, "sandbox.delete", map[string]interface{}{
+ "sandbox_id": sandboxID,
+ }, nil)
+ err := c.inner.Delete(ctx, sandboxID)
+ span.Finish(nil, nil, err)
+ return err
+}
+
+func (c *langfuseRemoteClient) Exec(
+ ctx context.Context,
+ handle RemoteSandboxHandle,
+ req RemoteExecRequest,
+) (*RemoteExecResult, error) {
+ ctx, span := startSandboxSpan(ctx, "sandbox.exec", map[string]interface{}{
+ "command": truncateSandboxPreview(req.Command),
+ "shell": req.Shell,
+ "work_dir": req.WorkDir,
+ "user": req.User,
+ "timeout_ms": req.Timeout.Milliseconds(),
+ }, sandboxHandleMeta(handle))
+ result, err := c.inner.Exec(ctx, handle, req)
+ out := map[string]interface{}{}
+ if result != nil {
+ out["exit_code"] = result.ExitCode
+ out["killed"] = result.Killed
+ out["duration_ms"] = result.Duration.Milliseconds()
+ out["stdout_bytes"] = len(result.Stdout)
+ out["stderr_bytes"] = len(result.Stderr)
+ }
+ span.Finish(out, nil, err)
+ return result, err
+}
+
+func (c *langfuseRemoteClient) WriteFile(
+ ctx context.Context, handle RemoteSandboxHandle, path string, content []byte,
+) error {
+ ctx, span := startSandboxSpan(ctx, "sandbox.write_file", map[string]interface{}{
+ "path": path,
+ "bytes": len(content),
+ }, sandboxHandleMeta(handle))
+ err := c.inner.WriteFile(ctx, handle, path, content)
+ span.Finish(nil, nil, err)
+ return err
+}
+
+func (c *langfuseRemoteClient) ReadFile(
+ ctx context.Context, handle RemoteSandboxHandle, path string,
+) ([]byte, error) {
+ ctx, span := startSandboxSpan(ctx, "sandbox.read_file", map[string]interface{}{
+ "path": path,
+ }, sandboxHandleMeta(handle))
+ data, err := c.inner.ReadFile(ctx, handle, path)
+ span.Finish(map[string]interface{}{"bytes": len(data)}, nil, err)
+ return data, err
+}
+
+func (c *langfuseRemoteClient) ListDir(
+ ctx context.Context, handle RemoteSandboxHandle, path string,
+) ([]RemoteDirEntry, error) {
+ ctx, span := startSandboxSpan(ctx, "sandbox.list_dir", map[string]interface{}{
+ "path": path,
+ }, sandboxHandleMeta(handle))
+ entries, err := c.inner.ListDir(ctx, handle, path)
+ span.Finish(map[string]interface{}{"entries": len(entries)}, nil, err)
+ return entries, err
+}
+
+func (c *langfuseRemoteClient) MakeDir(
+ ctx context.Context, handle RemoteSandboxHandle, path string,
+) error {
+ ctx, span := startSandboxSpan(ctx, "sandbox.make_dir", map[string]interface{}{
+ "path": path,
+ }, sandboxHandleMeta(handle))
+ err := c.inner.MakeDir(ctx, handle, path)
+ span.Finish(nil, nil, err)
+ return err
+}
+
+func (c *langfuseRemoteClient) Remove(
+ ctx context.Context, handle RemoteSandboxHandle, path string,
+) error {
+ ctx, span := startSandboxSpan(ctx, "sandbox.remove", map[string]interface{}{
+ "path": path,
+ }, sandboxHandleMeta(handle))
+ err := c.inner.Remove(ctx, handle, path)
+ span.Finish(nil, nil, err)
+ return err
+}
+
+func (c *langfuseRemoteClient) Stat(
+ ctx context.Context, handle RemoteSandboxHandle, path string,
+) (*RemoteStatEntry, error) {
+ ctx, span := startSandboxSpan(ctx, "sandbox.stat", map[string]interface{}{
+ "path": path,
+ }, sandboxHandleMeta(handle))
+ stat, err := c.inner.Stat(ctx, handle, path)
+ span.Finish(nil, nil, err)
+ return stat, err
+}
+
+type langfuseSnapshotClient struct {
+ langfuseRemoteClient
+}
+
+func (c *langfuseSnapshotClient) CreateSnapshot(
+ ctx context.Context, sandboxID string, name string,
+) (RemoteSnapshotRef, error) {
+ inner, ok := c.inner.(RemoteSnapshotManager)
+ if !ok {
+ return RemoteSnapshotRef{}, &RemoteError{
+ Kind: RemoteErrorKindUnsupported,
+ Op: "CreateSnapshot",
+ Message: "inner client has no snapshot manager",
+ }
+ }
+ ctx, span := startSandboxSpan(ctx, "sandbox.create_snapshot", map[string]interface{}{
+ "sandbox_id": sandboxID,
+ "name": name,
+ }, nil)
+ ref, err := inner.CreateSnapshot(ctx, sandboxID, name)
+ span.Finish(map[string]interface{}{"snapshot_id": ref.ID}, nil, err)
+ return ref, err
+}
+
+func (c *langfuseSnapshotClient) DeleteSnapshot(ctx context.Context, snapshotID string) error {
+ inner, ok := c.inner.(RemoteSnapshotManager)
+ if !ok {
+ return nil
+ }
+ ctx, span := startSandboxSpan(ctx, "sandbox.delete_snapshot", map[string]interface{}{
+ "snapshot_id": snapshotID,
+ }, nil)
+ err := inner.DeleteSnapshot(ctx, snapshotID)
+ span.Finish(nil, nil, err)
+ return err
+}
+
+func (c *langfuseSnapshotClient) ListSnapshots(
+ ctx context.Context, sandboxID string,
+) ([]RemoteSnapshotRef, error) {
+ inner, ok := c.inner.(RemoteSnapshotManager)
+ if !ok {
+ return nil, nil
+ }
+ return inner.ListSnapshots(ctx, sandboxID)
+}
+
+func startSandboxSpan(
+ ctx context.Context,
+ name string,
+ input, extraMeta map[string]interface{},
+) (context.Context, *langfuse.Span) {
+ return langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{
+ Name: name,
+ Input: input,
+ Metadata: extraMeta,
+ })
+}
+
+func sandboxHandleMeta(handle RemoteSandboxHandle) map[string]interface{} {
+ if handle == nil {
+ return nil
+ }
+ return map[string]interface{}{
+ "sandbox_id": handle.ID(),
+ "provider": string(handle.Provider()),
+ }
+}
+
+func sandboxHandleOut(handle RemoteSandboxHandle) map[string]interface{} {
+ if handle == nil {
+ return nil
+ }
+ return map[string]interface{}{"sandbox_id": handle.ID()}
+}
+
+func truncateSandboxPreview(s string) string {
+ if s == "" || utf8.RuneCountInString(s) <= sandboxSpanPreviewRunes {
+ return s
+ }
+ runes := []rune(s)
+ return string(runes[:sandboxSpanPreviewRunes]) + "…"
+}
+
+var (
+ _ RemoteSandboxClient = (*langfuseRemoteClient)(nil)
+ _ RemoteSnapshotManager = (*langfuseSnapshotClient)(nil)
+)
diff --git a/internal/sandbox/langfuse_test.go b/internal/sandbox/langfuse_test.go
new file mode 100644
index 000000000..84c11d272
--- /dev/null
+++ b/internal/sandbox/langfuse_test.go
@@ -0,0 +1,63 @@
+package sandbox
+
+import (
+ "context"
+ "strings"
+ "testing"
+ "unicode/utf8"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestWrapLangfuseRemoteClientPreservesSnapshotCapability(t *testing.T) {
+ inner := newFakeRemoteClient(SandboxTypeCube)
+ inner.capabilities.SupportsSnapshots = true
+
+ wrapped := wrapLangfuseRemoteClient(inner)
+ mgr, ok := SnapshotManagerFrom(wrapped)
+ require.True(t, ok, "wrapping must not hide RemoteSnapshotManager from SnapshotManagerFrom")
+ require.NotNil(t, mgr)
+
+ ref, err := mgr.CreateSnapshot(context.Background(), "sb-1", "snap-1")
+ require.NoError(t, err)
+ require.NotEmpty(t, ref.ID)
+}
+
+func TestWrapLangfuseRemoteClientDoesNotInventSnapshotSupport(t *testing.T) {
+ inner := &noSnapshotClient{}
+ wrapped := wrapLangfuseRemoteClient(inner)
+ mgr, ok := SnapshotManagerFrom(wrapped)
+ require.False(t, ok)
+ require.Nil(t, mgr)
+}
+
+func TestWrapLangfuseRemoteClientIdempotent(t *testing.T) {
+ inner := newFakeRemoteClient(SandboxTypeDocker)
+ once := wrapLangfuseRemoteClient(inner)
+ twice := wrapLangfuseRemoteClient(once)
+ require.Equal(t, once, twice)
+}
+
+func TestWrapLangfuseRemoteClientExecForwards(t *testing.T) {
+ inner := newFakeRemoteClient(SandboxTypeDocker)
+ handle, err := inner.Create(context.Background(), RemoteCreateRequest{TemplateID: "tpl"})
+ require.NoError(t, err)
+
+ wrapped := wrapLangfuseRemoteClient(inner)
+ result, err := wrapped.Exec(context.Background(), handle, RemoteExecRequest{
+ Command: "echo hi",
+ Shell: true,
+ })
+ require.NoError(t, err)
+ require.NotNil(t, result)
+ require.Len(t, inner.execRequests, 1)
+ require.Equal(t, "echo hi", inner.execRequests[0].Command)
+}
+
+func TestTruncateSandboxPreview(t *testing.T) {
+ require.Equal(t, "short", truncateSandboxPreview("short"))
+ long := strings.Repeat("x", sandboxSpanPreviewRunes+8)
+ got := truncateSandboxPreview(long)
+ require.True(t, strings.HasSuffix(got, "…"))
+ require.Equal(t, sandboxSpanPreviewRunes+1, utf8.RuneCountInString(got))
+}
diff --git a/internal/sandbox/session_manager.go b/internal/sandbox/session_manager.go
index 9c8215662..2bdbc2401 100644
--- a/internal/sandbox/session_manager.go
+++ b/internal/sandbox/session_manager.go
@@ -32,6 +32,7 @@ import (
"sync"
"time"
+ "github.com/Tencent/WeKnora/internal/tracing/langfuse"
"github.com/Tencent/WeKnora/internal/types"
)
@@ -170,8 +171,10 @@ func NewSessionBoundManager(deps SessionBoundManagerConfig) (*SessionBoundManage
)
}
+ client := wrapLangfuseRemoteClient(deps.Client)
+
lifecycle, err := newRemoteSessionLifecycle(
- deps.Client,
+ client,
deps.Store,
deps.Checker,
createRequest,
@@ -185,11 +188,11 @@ func NewSessionBoundManager(deps SessionBoundManagerConfig) (*SessionBoundManage
m := &SessionBoundManager{
config: cfg,
validator: NewScriptValidator(),
- client: deps.Client,
+ client: client,
bindings: deps.Store,
checker: deps.Checker,
lifecycle: lifecycle,
- ephemeral: NewRemoteSandbox(deps.Client, createRequest),
+ ephemeral: NewRemoteSandbox(client, createRequest),
activeType: provider,
}
@@ -301,12 +304,22 @@ func (m *SessionBoundManager) ensureSessionWorkspaceDirs(
return
}
execUser := DefaultSandboxExecUser
+ ctx, span := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{
+ Name: "sandbox.ensure_workspace",
+ Input: map[string]interface{}{
+ "input_dir": SessionInputRoot,
+ "output_dir": outputDir,
+ "user": execUser,
+ },
+ Metadata: sandboxHandleMeta(handle),
+ })
result, err := m.client.Exec(ctx, handle, RemoteExecRequest{
Shell: true,
Command: workspaceBootstrapCommand(SessionInputRoot, outputDir),
User: execUser,
Timeout: sessionArtifactDirBootstrapTimeout,
})
+ span.Finish(nil, nil, err)
switch {
case err != nil:
log.Printf(