fix: show exported tool results in trace viewers (#101371)

amknight · web-flow · commit d09469c7a6b4 · 2026-07-07T17:14:30.000+10:00
* fix: show exported tool results in trace viewers

* fix(diagnostics-otel): emit semconv response key and execute_tool identity so trace viewers show tool results

---------

Co-authored-by: Alex Knight &lt;15041791+amknight@users.noreply.github.com&gt;
diff --git a/docs/gateway/opentelemetry.md b/docs/gateway/opentelemetry.md
@@ -162,11 +162,15 @@ Boolean `captureContent: true` enables `inputMessages`, `outputMessages`, `toolI
 </Note>
 
 `toolInputs`/`toolOutputs` content is captured for the built-in agent
-runtime's tool executions (`openclaw.content.tool_input` on
-completed/error spans, `openclaw.content.tool_output` on completed spans).
-External harness tool calls (Codex, Claude CLI) emit `tool.execution.*` spans
-without content payloads. Captured content travels on a trusted,
-listener-only channel and is never placed on the public diagnostic event bus.
+runtime's tool executions (`openclaw.content.tool_input` and
+`gen_ai.tool.call.arguments` on completed/error spans;
+`openclaw.content.tool_output` and `gen_ai.tool.call.result` on completed
+spans). The `openclaw.content.*` names remain the stable OpenClaw attribute
+names; the `gen_ai.tool.call.*` copies mirror them for semconv-native viewers.
+External harness tool calls (Codex, Claude CLI) emit
+`tool.execution.*` spans without content payloads. Captured content travels on a
+trusted, listener-only channel and is never placed on the public diagnostic event
+bus.
 
 ## Sampling and flushing
 
@@ -346,7 +350,7 @@ Liveness warnings also emit:
   - On completion: `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active`
   - On error: `openclaw.harness.phase`, `openclaw.errorCategory`, optional `openclaw.harness.cleanup_failed`
 - `openclaw.tool.execution`
-  - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.tool.source`, optional `openclaw.tool.owner`, `openclaw.tool.params.*`
+  - `gen_ai.tool.name`, `gen_ai.operation.name` (`execute_tool`), `openclaw.toolName`, `openclaw.tool.source`, optional `gen_ai.tool.call.id`, `openclaw.tool.owner`, `openclaw.tool.params.*`
   - Optional `openclaw.errorCategory`/`openclaw.errorCode` on errors, `openclaw.deniedReason` and `openclaw.outcome=blocked` when denied by policy or sandbox
 - `openclaw.exec`
   - `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`, `openclaw.exec.command_length`, `openclaw.exec.exit_code`, `openclaw.exec.exit_signal`, `openclaw.exec.timed_out`
diff --git a/extensions/diagnostics-otel/src/service.test.ts b/extensions/diagnostics-otel/src/service.test.ts
@@ -4827,6 +4827,10 @@ describe("diagnostics-otel service", () => {
     expect(Object.hasOwn(toolOptions?.attributes ?? {}, "openclaw.content.tool_output")).toBe(
       false,
     );
+    expect(Object.hasOwn(toolOptions?.attributes ?? {}, "gen_ai.tool.call.arguments")).toBe(false);
+    expect(Object.hasOwn(toolOptions?.attributes ?? {}, "gen_ai.tool.call.result")).toBe(false);
+    expect(toolOptions?.attributes?.["gen_ai.tool.call.id"]).toBe("tool-1");
+    expect(toolOptions?.attributes?.["gen_ai.operation.name"]).toBe("execute_tool");
     expect(toolOptions?.startTime).toBeTypeOf("number");
     await service.stop?.(ctx);
   });
@@ -4892,10 +4896,19 @@ describe("diagnostics-otel service", () => {
       "sk-1234567890abcdef1234567890abcdef", // pragma: allowlist secret
     );
     expect(toolAttrs?.["openclaw.content.tool_input"]).toBe("tool input");
+    expect(toolAttrs?.["gen_ai.tool.call.id"]).toBe("tool-1");
+    expect(toolAttrs?.["gen_ai.operation.name"]).toBe("execute_tool");
+    expect(toolAttrs?.["gen_ai.tool.call.arguments"]).toBe(
+      toolAttrs?.["openclaw.content.tool_input"],
+    );
+    expect(typeof toolAttrs?.["openclaw.content.tool_output"]).toBe("string");
     expect(String(toolAttrs?.["openclaw.content.tool_output"]).length).toBeLessThanOrEqual(
       MAX_TEST_OTEL_CONTENT_ATTRIBUTE_CHARS + OTEL_TRUNCATED_SUFFIX_MAX_CHARS,
     );
     expect(String(toolAttrs?.["openclaw.content.tool_output"])).not.toContain("a".repeat(11));
+    expect(toolAttrs?.["gen_ai.tool.call.result"]).toBe(
+      toolAttrs?.["openclaw.content.tool_output"],
+    );
     await service.stop?.(ctx);
   });
 
@@ -5011,7 +5024,7 @@ describe("diagnostics-otel service", () => {
       },
       {
         role: "tool",
-        parts: [{ type: "tool_call_response", id: "call-1", result: { rows: 1 } }],
+        parts: [{ type: "tool_call_response", id: "call-1", response: { rows: 1 } }],
       },
     ]);
     expect(JSON.parse(stringAttribute(attrs, "gen_ai.output.messages"))).toEqual([
@@ -5034,6 +5047,130 @@ describe("diagnostics-otel service", () => {
     await service.stop?.(ctx);
   });
 
+  test("emits semconv response text for tool response parts", async () => {
+    const service = createDiagnosticsOtelService();
+    const ctx = createOtelContext(OTEL_TEST_ENDPOINT, {
+      traces: true,
+      captureContent: {
+        enabled: true,
+        inputMessages: true,
+        outputMessages: false,
+      },
+    });
+    await service.start(ctx);
+
+    emitTrustedModelCallCompletedWithContent(
+      {
+        runId: "run-1",
+        callId: "call-1",
+        provider: "openai",
+        model: "gpt-5.4",
+        durationMs: 80,
+      },
+      {
+        inputMessages: [
+          {
+            role: "tool",
+            parts: [
+              {
+                type: "tool_call_response",
+                id: "call-1",
+                result: [
+                  { type: "text", text: "first line" },
+                  { type: "text", text: "second line" },
+                ],
+              },
+            ],
+          },
+          {
+            role: "toolResult",
+            toolCallId: "call-2",
+            content: [
+              { type: "text", text: "alpha" },
+              { type: "text", text: "beta" },
+            ],
+          },
+        ],
+      },
+    );
+    await flushDiagnosticEvents();
+
+    const modelCall = telemetryState.tracer.startSpan.mock.calls.find(
+      (call) => call[0] === "openclaw.model.call",
+    );
+    const attrs = (modelCall?.[1] as { attributes?: Record<string, unknown> } | undefined)
+      ?.attributes;
+    expect(JSON.parse(stringAttribute(attrs, "gen_ai.input.messages"))).toEqual([
+      {
+        role: "tool",
+        parts: [
+          {
+            type: "tool_call_response",
+            id: "call-1",
+            response: "first line\nsecond line",
+          },
+        ],
+      },
+      {
+        role: "tool",
+        parts: [
+          {
+            type: "tool_call_response",
+            id: "call-2",
+            response: "alpha\nbeta",
+          },
+        ],
+      },
+    ]);
+    await service.stop?.(ctx);
+  });
+
+  test("flattens oversized pure-text tool results with a truncation marker", async () => {
+    const service = createDiagnosticsOtelService();
+    const ctx = createOtelContext(OTEL_TEST_ENDPOINT, {
+      traces: true,
+      captureContent: {
+        enabled: true,
+        inputMessages: true,
+        outputMessages: false,
+      },
+    });
+    await service.start(ctx);
+
+    const textParts = Array.from({ length: 201 }, (_, index) => ({
+      type: "text",
+      text: `line-${index}`,
+    }));
+    emitTrustedModelCallCompletedWithContent(
+      {
+        runId: "run-1",
+        callId: "call-1",
+        provider: "openai",
+        model: "gpt-5.4",
+        durationMs: 80,
+      },
+      {
+        inputMessages: [{ role: "toolResult", toolCallId: "call-1", content: textParts }],
+      },
+    );
+    await flushDiagnosticEvents();
+
+    const modelCall = telemetryState.tracer.startSpan.mock.calls.find(
+      (call) => call[0] === "openclaw.model.call",
+    );
+    const attrs = (modelCall?.[1] as { attributes?: Record<string, unknown> } | undefined)
+      ?.attributes;
+    const messages = JSON.parse(stringAttribute(attrs, "gen_ai.input.messages")) as {
+      parts: { response?: unknown }[];
+    }[];
+    const expected = `${textParts
+      .slice(0, 200)
+      .map((part) => part.text)
+      .join("\n")}\n...(1 more text parts omitted)`;
+    expect(messages[0]?.parts[0]?.response).toBe(expected);
+    await service.stop?.(ctx);
+  });
+
   test("normalizes snake_case tool_call parts the same as camelCase toolCall parts", async () => {
     const service = createDiagnosticsOtelService();
     const ctx = createOtelContext(OTEL_TEST_ENDPOINT, {
diff --git a/extensions/diagnostics-otel/src/service.ts b/extensions/diagnostics-otel/src/service.ts
@@ -30,7 +30,11 @@ import {
   ATTR_GEN_AI_INPUT_MESSAGES,
   ATTR_GEN_AI_OUTPUT_MESSAGES,
   ATTR_GEN_AI_SYSTEM_INSTRUCTIONS,
+  ATTR_GEN_AI_TOOL_CALL_ARGUMENTS,
+  ATTR_GEN_AI_TOOL_CALL_ID,
+  ATTR_GEN_AI_TOOL_CALL_RESULT,
   ATTR_GEN_AI_TOOL_DEFINITIONS,
+  GEN_AI_OPERATION_NAME_VALUE_EXECUTE_TOOL,
 } from "@opentelemetry/semantic-conventions/incubating";
 import { waitForDiagnosticEventsDrained } from "openclaw/plugin-sdk/diagnostic-runtime";
 import { createNodeProxyAgent } from "openclaw/plugin-sdk/fetch-runtime";
@@ -912,11 +916,53 @@ function textPart(content: string): Record<string, unknown> {
   return { type: "text", content };
 }
 
+// Shared text-part reading for gen_ai message normalization: OpenClaw emits
+// {type:"text", text}; some harness shapes carry {type:"text", content}.
+function textPartContent(part: Record<string, unknown>): string | undefined {
+  if (part.type !== "text") {
+    return undefined;
+  }
+  if (typeof part.text === "string") {
+    return part.text;
+  }
+  return typeof part.content === "string" ? part.content : undefined;
+}
+
+// Tool results usually arrive as arrays of text parts. Flatten pure-text arrays
+// into one plain string so the part's `response` renders as readable text in
+// trace viewers; mixed/structured results keep their raw (bounded, redacted) shape.
+function toolCallResponseValue(value: unknown): unknown {
+  if (!Array.isArray(value)) {
+    return value;
+  }
+  const textItems: string[] = [];
+  for (const item of value) {
+    const text =
+      typeof item === "string" ? item : isRecord(item) ? textPartContent(item) : undefined;
+    if (typeof text !== "string") {
+      return value;
+    }
+    textItems.push(text);
+  }
+  const kept = textItems.slice(0, MAX_OTEL_CONTENT_ARRAY_ITEMS);
+  const joined = kept.filter((text) => text.length > 0).join("\n");
+  if (joined.length === 0) {
+    return value;
+  }
+  const omitted = textItems.length - kept.length;
+  return omitted > 0 ? `${joined}\n...(${omitted} more text parts omitted)` : joined;
+}
+
 function toolCallResponsePart(part: Record<string, unknown>): Record<string, unknown> {
   return {
     type: "tool_call_response",
     ...(typeof part.id === "string" ? { id: part.id } : {}),
-    result: part.result ?? part.response ?? part.content ?? part.details ?? "",
+    // Semconv gen_ai.*.messages requires the `response` key on tool_call_response
+    // parts (gen-ai-input-messages.json, since v1.37). Schema-validating viewers
+    // (e.g. Phoenix) silently drop parts keyed `result`, hiding tool output.
+    response: toolCallResponseValue(
+      part.response ?? part.result ?? part.content ?? part.details ?? "",
+    ),
   };
 }
 
@@ -945,10 +991,9 @@ function contentParts(value: unknown): Record<string, unknown>[] {
     if (!isRecord(part)) {
       continue;
     }
-    if (part.type === "text" && typeof part.text === "string") {
-      parts.push(textPart(part.text));
-    } else if (part.type === "text" && typeof part.content === "string") {
-      parts.push(textPart(part.content));
+    const text = textPartContent(part);
+    if (text !== undefined) {
+      parts.push(textPart(text));
     } else if (part.type === "thinking" && typeof part.thinking === "string") {
       parts.push({ type: "reasoning", content: part.thinking });
     } else if (part.type === "toolCall" && typeof part.name === "string") {
@@ -1002,7 +1047,7 @@ function normalizeGenAiMessage(
         : [
             toolCallResponsePart({
               id: value.toolCallId,
-              result: value.content ?? value.details ?? "",
+              response: value.content ?? value.details ?? "",
             }),
           ];
   } else {
@@ -1113,6 +1158,20 @@ function assignOtelContentAttribute(
   }
 }
 
+function assignOtelToolIdentityAttributes(
+  attributes: Record<string, string | number | boolean>,
+  evt: { toolCallId?: string },
+): void {
+  // Semconv execute_tool identity, span-only by design: metric attrs must stay
+  // low-cardinality, and unlike the dropped openclaw.toolCallId passthrough keys
+  // (DROPPED_OTEL_ATTRIBUTE_KEYS) the semconv id is a deliberate per-span export.
+  attributes["gen_ai.operation.name"] = GEN_AI_OPERATION_NAME_VALUE_EXECUTE_TOOL;
+  const toolCallId = evt.toolCallId?.trim();
+  if (toolCallId) {
+    attributes[ATTR_GEN_AI_TOOL_CALL_ID] = toolCallId;
+  }
+}
+
 function assignOtelModelContentAttributes(
   attributes: Record<string, string | number | boolean>,
   content: OtelModelCallContent | undefined,
@@ -1150,11 +1209,21 @@ function assignOtelToolContentAttributes(
   content: OtelToolCallContent | undefined,
   policy: OtelContentCapturePolicy,
 ): void {
+  // Mirror captured content onto the semconv keys next to the shipped
+  // openclaw.content.* names; normalize once so both copies stay byte-identical.
   if (policy.toolInputs) {
-    assignOtelContentAttribute(attributes, "openclaw.content.tool_input", content?.toolInput);
+    const toolInput = normalizeOtelContentValue(content?.toolInput);
+    if (toolInput) {
+      attributes[ATTR_GEN_AI_TOOL_CALL_ARGUMENTS] = toolInput;
+      attributes["openclaw.content.tool_input"] = toolInput;
+    }
   }
   if (policy.toolOutputs) {
-    assignOtelContentAttribute(attributes, "openclaw.content.tool_output", content?.toolOutput);
+    const toolOutput = normalizeOtelContentValue(content?.toolOutput);
+    if (toolOutput) {
+      attributes[ATTR_GEN_AI_TOOL_CALL_RESULT] = toolOutput;
+      attributes["openclaw.content.tool_output"] = toolOutput;
+    }
   }
 }
 
@@ -3556,10 +3625,12 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
         if (!tracesEnabled || !metadata.trusted) {
           return;
         }
+        const spanAttrs = toolExecutionBaseAttrs(evt);
+        assignOtelToolIdentityAttributes(spanAttrs, evt);
         trackTrustedSpan(
           evt,
           metadata,
-          spanWithDuration("openclaw.tool.execution", toolExecutionBaseAttrs(evt), undefined, {
+          spanWithDuration("openclaw.tool.execution", spanAttrs, undefined, {
             parentContext: activeTrustedParentContext(evt, metadata),
             startTimeMs: evt.ts,
           }),
@@ -3576,10 +3647,9 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
         if (!tracesEnabled) {
           return;
         }
-        const spanAttrs: Record<string, string | number | boolean> = {
-          ...toolExecutionBaseAttrs(evt),
-        };
+        const spanAttrs: Record<string, string | number | boolean> = { ...attrs };
         addRunAttrs(spanAttrs, evt);
+        assignOtelToolIdentityAttributes(spanAttrs, evt);
         assignOtelToolContentAttributes(spanAttrs, toolContent, contentCapturePolicy);
         const span =
           takeTrackedTrustedSpan(evt, metadata) ??
@@ -3604,11 +3674,9 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
         if (!tracesEnabled) {
           return;
         }
-        const spanAttrs: Record<string, string | number | boolean> = {
-          ...toolExecutionBaseAttrs(evt),
-          "openclaw.errorCategory": lowCardinalityAttr(evt.errorCategory, "other"),
-        };
+        const spanAttrs: Record<string, string | number | boolean> = { ...attrs };
         addRunAttrs(spanAttrs, evt);
+        assignOtelToolIdentityAttributes(spanAttrs, evt);
         if (evt.errorCode) {
           spanAttrs["openclaw.errorCode"] = lowCardinalityAttr(evt.errorCode, "other");
         }
@@ -3644,6 +3712,7 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
           "openclaw.deniedReason": lowCardinalityAttr(evt.deniedReason, "other"),
         };
         addRunAttrs(spanAttrs, evt);
+        assignOtelToolIdentityAttributes(spanAttrs, evt);
         const span = spanWithDuration("openclaw.tool.execution", spanAttrs, 0, {
           parentContext: activeTrustedParentContext(evt, metadata),
           endTimeMs: evt.ts,
