Skill: langfuse-trace-logger

Purpose: Log subagent task completions as Langfuse traces for replay, evaluation, and cost analysis.
Scope: Called by Loki at the end of every session wrap (Phase 4) for each significant subagent completion.
Script: /Users/loki/.openclaw/workspace/scripts/langfuse-trace-logger.py

---

⚠️ CRITICAL: Python Version

Always use ~/.chatterbox-venv/bin/python3 (Python 3.11.15)

The langfuse SDK uses pydantic v1, which is incompatible with Python 3.14. Running with system Python (python3) or pyenv Python (3.14.x) causes silent failure — no import error, no exception, trace just doesn't appear in Langfuse UI. This will waste 30+ minutes of debugging.

CODEBLOCK0

---

Basic Invocation

CODEBLOCK1

---

Trace Schema

Field	Type	Purpose	Notes
INLINECODE3	string	Subagent session key	Use actual subagent session key — enables lineage tracing
INLINECODE4

string | Parent session reference | Always "agent:main" unless nested subagent |
| --agent | string | Agent name | Lowercase: kit, archie, sara, finn, quill, etc. |
| --task | string | Task label (kebab-case) | Used for replay grouping: replay-judge.py --tag "task:kit-setup-rebuild" |
| --model | string | Model used | e.g. anthropic/claude-sonnet-4-6, anthropic/claude-haiku-4-5 |
| --status | string | Outcome | completed / partial / failed |
| --input | string | Full task prompt | First 4000 chars — this is what gets replayed against other models in judge runs |
| --output | string | Result summary | Agent's output/result — this is what the judge scores |
| --duration | int | Time in seconds | Used for efficiency analysis and agent routing decisions |
| --tokens | int | Total tokens used | Used for cost analysis and budget governance |
| --project | string | Project slug | Must match projects/<slug>/STATUS.md — enables project-level filtering |
| --skills | string | Comma-separated skills | e.g. "product-tour-capture,ffmpeg-studio" — enables skill effectiveness filtering |

Tag Taxonomy

The logger automatically generates these tags from the fields above:

• - agent:kit — from INLINECODE25
• INLINECODE26 — derived from INLINECODE27
• INLINECODE28 — from INLINECODE29
• INLINECODE30 — one tag per skill in INLINECODE31
• INLINECODE32 — from INLINECODE33
• INLINECODE34 — from INLINECODE35

These tags power the replay-judge filter syntax.

---

Backfill Pattern

For retroactive logging when a session wrap was skipped or traces are missing.

Idempotent: Uses deterministic trace IDs based on date+agent+task hash. Safe to re-run — won't create duplicates.

CODEBLOCK2

Data source: Backfill parses memory/YYYY-MM-DD.md files and extracts structured task outcome blocks. This is why the task outcome block format in memory files must be consistent — inconsistent format breaks parsing silently.

Backfill ID format: backfill-YYYY-MM-DD-<agent>-<task-slug> — deterministic, no duplicate risk.

---

Replay and Judge

CODEBLOCK3

---

Verify Traces Appeared

After logging, verify in Langfuse UI: http://localhost:3100

Or check programmatically:

CODEBLOCK4

Expected output: last 5 trace names + truncated IDs. If blank, Python version issue (see warning above).

---

Langfuse Connection Details

Setting	Value
UI	http://localhost:3100
Public key

pk-lf-openclaw-local |
| Secret key | op://OpenClaw/Langfuse (Local)/credential (1Password) |
| Also in 1Password | op://OpenClaw/Langfuse (Local)/Secret Key |
| Docker | Always running (daemon service) |

---

When to Call This Skill

This skill is called during Phase 4 (Traces) of the session-wrap playbook (playbooks/session-wrap/PLAYBOOK.md).

Call once per significant subagent completion. Use data from the task outcome blocks written in Phase 1 (memory file). Don't reconstruct from memory — read what you just wrote.

Minimum threshold for logging: Any subagent run that produced a deliverable (file written, API called, analysis produced). Skip: simple lookups, 1-line tool calls, failed attempts with no output.

---

Troubleshooting

Symptom	Cause	Fix
Trace doesn't appear in UI	Wrong Python version	Use INLINECODE43
No output, no error

Same — Python 3.14 pydantic v1 incompatibility | Same fix |
| ImportError: langfuse not found | Wrong venv | Same fix |
| Duplicate traces on backfill | Shouldn't happen — backfill is idempotent | Check if running logger + backfill both for same trace |
| op: command not found | 1Password CLI not in PATH | Run from shell with OPSERVICEACCOUNT_TOKEN set, or source ~/.zshrc first |
| Langfuse UI empty after logging | Docker daemon down | docker ps — restart Langfuse container if needed |