Skip to content

feat: use GenAI util for Google ADK spans #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sipercai wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: use GenAI util for Google ADK spans #199

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions instrumentation-loongsuite/loongsuite-instrumentation-google-adk/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
65 changes: 58 additions & 7 deletions instrumentation-loongsuite/loongsuite-instrumentation-google-adk/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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": [],
Expand All @@ -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,
Expand All @@ -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\"}]}]"
}
}
```
Expand All @@ -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
Expand Down
Loading
Loading