Observability: OpenTelemetry GenAI spans for turns + tool calls (closes #41) (#47)

Author: lezama

bin/bench-tracer.php

@@ -0,0 +1,62 @@
+<?php
+/**
+ * Tracer overhead micro-benchmark.
+ *
+ * Drives one synthetic turn + one tool-call through OpenclaWP_Tracer 1000 times
+ * and reports avg/p50/p95/p99/max overhead. Used to assert the <5ms-per-turn
+ * budget from issue #41.
+ *
+ * Run: php bin/bench-tracer.php
+ *
+ * @package OpenclaWP
+ */
+
+require __DIR__ . '/../tests/bootstrap.php';
+
+$GLOBALS['openclawp_test_filters']['openclawp_otel_endpoint'] = static function () {
+	return 'https://collector.example/v1/traces';
+};
+
+$samples = array();
+for ( $i = 0; $i < 1000; $i++ ) {
+	OpenclaWP_Tracer::reset();
+	OpenclaWP_Tracer::set_runtime_context(
+		array(
+			'openclawp.session.id' => 'sess-bench',
+			'openclawp.agent.slug' => 'bench-agent',
+			'openclawp.user.id'    => '1',
+			'openclawp.channel'    => 'chat-block',
+		)
+	);
+	OpenclaWP_Tracer::on_turn_completed(
+		array(
+			'agent_slug'      => 'bench-agent',
+			'session_id'      => 'sess-bench',
+			'provider'        => 'anthropic',
+			'model'           => 'claude-opus-4-7',
+			'token_usage'     => array( 'input' => 1200, 'output' => 350 ),
+			'duration_ms'     => 480,
+			'success'         => true,
+			'error'           => null,
+			'tool_call_count' => 1,
+		)
+	);
+	OpenclaWP_Tracer::on_loop_event( 'tool_call', array( 'turn' => 1, 'tool_name' => 'echo' ) );
+	OpenclaWP_Tracer::on_loop_event( 'tool_result', array( 'turn' => 1, 'tool_name' => 'echo', 'success' => true ) );
+	$samples[] = OpenclaWP_Tracer::overhead_us();
+}
+sort( $samples );
+$n   = count( $samples );
+$p50 = $samples[ (int) ( $n * 0.50 ) ];
+$p95 = $samples[ (int) ( $n * 0.95 ) ];
+$p99 = $samples[ (int) ( $n * 0.99 ) ];
+$avg = array_sum( $samples ) / $n;
+printf(
+	"samples=%d  avg=%.1fus  p50=%dus  p95=%dus  p99=%dus  max=%dus\n",
+	$n,
+	$avg,
+	$p50,
+	$p95,
+	$p99,
+	end( $samples )
+);

includes/class-openclawp-bootstrap.php

@@ -34,6 +34,7 @@ public static function init(): void {
 		OpenclaWP_Routine_Registrar::register();
 		OpenclaWP_Abilities::register();
 		OpenclaWP_Event_Sink::register();
+		OpenclaWP_Tracer::register();
 		OpenclaWP_Usage_Recorder::register();
 		OpenclaWP_Mcp_Rest::register();
 		OpenclaWP_Rest::register();

includes/class-openclawp-runner.php

@@ -121,6 +121,26 @@ public static function run_turn( string $agent_slug, string $message, ?string $s
 			return $result;
 		}
 
+		// Stamp session/agent/user/channel onto every span emitted during
+		// this turn. Tracer is a no-op when no OTLP endpoint is configured,
+		// so this is cheap when disabled.
+		if ( class_exists( 'OpenclaWP_Tracer' ) ) {
+			$channel = '';
+			if ( isset( $runtime_context['channel'] ) && is_string( $runtime_context['channel'] ) ) {
+				$channel = $runtime_context['channel'];
+			} elseif ( isset( $runtime_context['client_context']['channel'] ) && is_string( $runtime_context['client_context']['channel'] ) ) {
+				$channel = $runtime_context['client_context']['channel'];
+			}
+			OpenclaWP_Tracer::set_runtime_context(
+				array(
+					'openclawp.session.id' => $session_id,
+					'openclawp.agent.slug' => $agent_slug,
+					'openclawp.user.id'    => (string) $user_id,
+					'openclawp.channel'    => $channel,
+				)
+			);
+		}
+
 		$messages   = $session['messages'];
 		$messages[] = array(
 			'role'    => 'user',