oclaw/docs/runtime-trace-taxonomy.md

oclaw trace taxonomy

Trace events share a common payload shape across components. Prefer joining on trace_id, pipeline, and oc_stage.

Stable keys

Key	Meaning
trace_id	Correlates all events for one gateway turn
pipeline	Which subsystem emitted the event (oclaw_gateway, oclaw_agent_core, oclaw_direct_loop, oclaw_skill_executor)
oc_stage	Normalized lifecycle stage (see tables below)
lang	Request language when known
run_id	Agent core run UUID (retry container)
attempt_no	1-based attempt index inside run_id
oclaw_task_id	Async worker task id when present
oclaw_worker_id	Worker thread id when present

Gateway (pipeline=oclaw_gateway)

event_type	oc_stage
gateway_received	ingress
gateway_normalized	normalize
skill_manifest	skills_manifest
memory_retrieval_started	memory_start
memory_retrieval_finished	memory_done
router_decision	route
task_enqueued	async_enqueue
runtime_config	runtime_config
response_sent	response

gateway_received payload now includes relay pointer stats:

• relay_pointer_count: number of direct pointer attachments on inbound message
• relay_envelope_present: whether metadata.relay_share_envelope exists
• relay_envelope_pointer_count: pointer count inside envelope manifest

Agent core (pipeline=oclaw_agent_core)

event_type	oc_stage
run_started	run_start
attempt_started	attempt
attempt_finished	attempt_done
run_finished	run_done
run_compact	compact
run_retry	retry

Direct loop (pipeline=oclaw_direct_loop)

event_type	oc_stage
tool_wire_filter	wire_filter
tool_result_context_guard	tool_context_guard

Both include trace_id and, when provided by the parent attempt, run_id and attempt_no.

Skill executor (pipeline=oclaw_skill_executor)

event_type	oc_stage
skill_selected	skill_select
skill_executed	skill_done

The payload includes run_id and attempt_no when available, so skill execution can be joined back to run_started/attempt_started.

Attempt memory hook (pipeline=oclaw_agent_core)

event_type	oc_stage
after_turn_memory	memory_done