feat: use GenAI util for Google ADK spans (#199)

Author: sipercai

instrumentation-loongsuite/loongsuite-instrumentation-google-adk/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Changed
+
+- Route Google ADK `AGENT`, `LLM`, and `TOOL` spans through
+  `opentelemetry-util-genai`, emitting current GenAI attributes such as
+  `gen_ai.input.messages`, `gen_ai.output.messages`,
+  `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`,
+  `gen_ai.span.kind`, and `gen_ai.provider.name=google_adk`.
+  ([#199](https://github.com/alibaba/loongsuite-python-agent/pull/199))
+
+### Fixed
+
+- Keep Google ADK streaming model spans open until the final response and
+  protect same-session concurrent invocations from cross-finishing spans.
+- Ensure Google ADK spans include LoongSuite `gen_ai.span.kind` values such as
+  `AGENT`.
+
 ## Version 0.5.0 (2026-05-11)
 
 There are no changelog entries for this release.

instrumentation-loongsuite/loongsuite-instrumentation-google-adk/README.md

@@ -71,7 +71,8 @@ Here's a simple demonstration of Google ADK instrumentation. The demo uses:
 export DASHSCOPE_API_KEY=your-dashscope-api-key
 
 # Enable content capture (optional, for debugging)
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY
 
 # Run with loongsuite instrumentation
 loongsuite-instrument \
@@ -87,7 +88,8 @@ loongsuite-instrument \
 export DASHSCOPE_API_KEY=your-dashscope-api-key
 
 # Configure OTLP exporter
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY
 export OTEL_TRACES_EXPORTER=otlp
 export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
@@ -98,6 +100,51 @@ loongsuite-instrument \
   python examples/main.py
 ```
 
+#### Option 3: Local otel-gui smoke scenarios
+
+`examples/otelgui_smoke.py` produces real non-streaming, SSE streaming, and
+concurrent Google ADK calls for local trace validation.
+
+```bash
+export DASHSCOPE_API_KEY=your-dashscope-api-key
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:5173
+export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:5173/v1/traces
+export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY
+export OTEL_SERVICE_NAME=loongsuite-google-adk-smoke
+export GOOGLE_ADK_SMOKE_CONFIGURE_OTLP=1
+export GOOGLE_ADK_SMOKE_DISABLE_NATIVE_AGENT_SPAN=1
+
+python examples/otelgui_smoke.py --scenario all
+```
+
+`GOOGLE_ADK_SMOKE_DISABLE_NATIVE_AGENT_SPAN=1` uses a private ADK telemetry
+monkey-patch during smoke validation to remove ADK's native wrapper span, making
+the LoongSuite GenAI span tree easier to inspect in otel-gui. Keep it limited to
+local smoke tests because private ADK internals may change.
+
+When using the local `loongsuite-otelgui-plugin-verify` helper, select the
+GenAI util agent trace explicitly because Google ADK also emits an `invocation`
+trace:
+
+```bash
+python /path/to/run_loongsuite_plugin_smoke.py \
+  --repo-root /path/to/loongsuite-python-agent \
+  --base-url http://127.0.0.1:5173 \
+  --service-name loongsuite-google-adk-non-stream \
+  --root-span-contains invoke_agent \
+  --capture-message-content SPAN_ONLY \
+  --expect-span-kind AGENT \
+  --expect-span-kind LLM \
+  --expect-span-kind TOOL \
+  --expect-content \
+  --env GOOGLE_ADK_SMOKE_CONFIGURE_OTLP=1 \
+  --env GOOGLE_ADK_SMOKE_DISABLE_NATIVE_AGENT_SPAN=1 \
+  --env OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:5173/v1/traces \
+  --run "python examples/otelgui_smoke.py --scenario non-stream"
+```
+
 ### Expected Results
 
 The instrumentation will generate traces showing the Google ADK operations:
@@ -121,10 +168,11 @@ The instrumentation will generate traces showing the Google ADK operations:
     },
     "attributes": {
         "gen_ai.operation.name": "execute_tool",
+        "gen_ai.span.kind": "TOOL",
         "gen_ai.tool.name": "get_current_time",
         "gen_ai.tool.description": "xxx",
-        "input.value": "{xxx}",
-        "output.value": "{xxx}"
+        "gen_ai.tool.call.arguments": "{xxx}",
+        "gen_ai.tool.call.result": "{xxx}"
     },
     "events": [],
     "links": [],
@@ -148,6 +196,7 @@ The instrumentation will generate traces showing the Google ADK operations:
     "kind": "SpanKind.CLIENT",
     "attributes": {
         "gen_ai.operation.name": "chat",
+        "gen_ai.span.kind": "LLM",
         "gen_ai.request.model": "qwen-max",
         "gen_ai.response.model": "qwen-max",
         "gen_ai.usage.input_tokens": 150,
@@ -164,9 +213,10 @@ The instrumentation will generate traces showing the Google ADK operations:
     "kind": "SpanKind.CLIENT",
     "attributes": {
         "gen_ai.operation.name": "invoke_agent",
+        "gen_ai.span.kind": "AGENT",
         "gen_ai.agent.name": "ToolAgent",
-        "input.value": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"现在几点了？\"}]}]",
-        "output.value": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"当前时间是 2025-11-27 14:36:33\"}]}]"
+        "gen_ai.input.messages": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"What time is it?\"}]}]",
+        "gen_ai.output.messages": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"The current time is 2025-11-27 14:36:33\"}]}]"
     }
 }
 ```
@@ -183,7 +233,8 @@ The following environment variables can be used to configure the Google ADK inst
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Capture message content in traces | `false` |
+| `OTEL_SEMCONV_STABILITY_OPT_IN` | Enable latest experimental GenAI semantic conventions | - |
+| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Capture message content in traces (`NO_CONTENT`, `SPAN_ONLY`, `SPAN_AND_EVENT`) | `NO_CONTENT` |
 | `DASHSCOPE_API_KEY` | DashScope API key (required for demo) | - |
 
 ### Programmatic Configuration