docs: Revise README for Google ADK instrumentation

Change-Id: If5dbb7ad8f67a9e51ff95398b79f59982020bf5a
Co-developed-by: Cursor <[email protected]>

Author: ralf0131

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

@@ -1,62 +1,125 @@
 # OpenTelemetry Google ADK Instrumentation
 
-Google ADK (Agent Development Kit) Python Agent provides observability for Google ADK applications.  
-This document provides examples of usage and results in the Google ADK instrumentation.  
-For details on usage and installation of LoongSuite and Jaeger, please refer to [LoongSuite Documentation](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md).
+[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-GenAI_Semantic_Conventions-blue)](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/)
+
+Google ADK (Agent Development Kit) Python Agent provides comprehensive observability for Google ADK applications using OpenTelemetry.
+
+## Features
+
+- ✅ **Automatic Instrumentation**: Zero-code integration via `opentelemetry-instrument`
+- ✅ **Manual Instrumentation**: Programmatic control via `GoogleAdkInstrumentor`
+- ✅ **GenAI Semantic Conventions**: Full compliance with OpenTelemetry GenAI standards
+- ✅ **Comprehensive Spans**: `invoke_agent`, `chat`, `execute_tool`
+- ✅ **Standard Metrics**: Operation duration and token usage
+- ✅ **Content Capture**: Optional message and response content capture
+- ✅ **Google ADK native instrumentation Compatible**: Works seamlessly with ADK native instrumentation
+
+## Quick Start
+
+```bash
+# Install
+pip install google-adk litellm
+pip install ./instrumentation-loongsuite/loongsuite-instrumentation-google-adk
+
+# Configure
+export DASHSCOPE_API_KEY=your-api-key
+
+# Run with auto instrumentation
+opentelemetry-instrument \
+  --traces_exporter console \
+  --service_name my-adk-app \
+  python your_app.py
+```
+
+For details on LoongSuite and Jaeger setup, refer to [LoongSuite Documentation](https://github.com/alibaba/loongsuite-python-agent/blob/main/README.md).
 
 ## Installing Google ADK Instrumentation
 
 ```shell
-# Open Telemetry
+# OpenTelemetry Core
 pip install opentelemetry-distro opentelemetry-exporter-otlp
 opentelemetry-bootstrap -a install
 
-# google-adk
+# Google ADK and LLM Dependencies
 pip install google-adk>=0.1.0
 pip install litellm
 
+# Demo Application Dependencies (optional, only if running examples)
+pip install fastapi uvicorn pydantic
+
 # GoogleAdkInstrumentor
 git clone https://github.com/alibaba/loongsuite-python-agent.git
 cd loongsuite-python-agent
-pip install ./instrumentation-genai/opentelemetry-instrumentation-google-adk
+pip install ./instrumentation-loongsuite/loongsuite-instrumentation-google-adk
 ```
 
 ## Collect Data
 
 Here's a simple demonstration of Google ADK instrumentation. The demo uses:
 
-- A [Google ADK application](examples/simple_adk_app.py) that demonstrates agent interactions
+- A [Google ADK application](examples/main.py) that demonstrates agent interactions with multiple tools
 
 ### Running the Demo
 
-#### Option 1: Using OpenTelemetry
+> **Note**: The demo uses DashScope (Alibaba Cloud LLM service) by default. You need to set the `DASHSCOPE_API_KEY` environment variable.
+
+#### Option 1: Using OpenTelemetry Auto Instrumentation
 
 ```bash
+# Set your DashScope API key
+export DASHSCOPE_API_KEY=your-dashscope-api-key
+
+# Enable content capture (optional, for debugging)
 export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
 
+# Run with auto instrumentation
 opentelemetry-instrument \
---traces_exporter console \
---service_name demo-google-adk \
-python examples/main.py
+  --traces_exporter console \
+  --service_name demo-google-adk \
+  python examples/main.py
 ```
 
 #### Option 2: Using Loongsuite
 
 ```bash
-export DASHSCOPE_API_KEY=xxxx
+# Set your DashScope API key
+export DASHSCOPE_API_KEY=your-dashscope-api-key
+
+# Enable content capture (optional, for debugging)
 export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
 
+# Run with loongsuite instrumentation
 loongsuite-instrument \
---traces_exporter console \
---service_name demo-google-adk \
-python examples/main.py
+  --traces_exporter console \
+  --service_name demo-google-adk \
+  python examples/main.py
 ```
 
-### Results
+#### Option 3: Export to Jaeger
+
+```bash
+# Set your DashScope API key
+export DASHSCOPE_API_KEY=your-dashscope-api-key
+
+# Configure OTLP exporter
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+export OTEL_TRACES_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+# Run the application
+opentelemetry-instrument \
+  --service_name demo-google-adk \
+  python examples/main.py
+```
+
+### Expected Results
 
 The instrumentation will generate traces showing the Google ADK operations:
 
-```bash
+#### Tool Execution Span Example
+
+```json
 {
     "name": "execute_tool get_current_time",
     "context": {
@@ -73,15 +136,10 @@ The instrumentation will generate traces showing the Google ADK operations:
     },
     "attributes": {
         "gen_ai.operation.name": "execute_tool",
-        "gen_ai.tool.description": "xxx",
         "gen_ai.tool.name": "get_current_time",
-        "gen_ai.tool.type": "FunctionTool",
-        "gcp.vertex.agent.llm_request": "{}",
-        "gcp.vertex.agent.llm_response": "{}",
-        "gcp.vertex.agent.tool_call_args": "{}",
-        "gen_ai.tool.call.id": "xxx",
-        "gcp.vertex.agent.event_id": "xxxx",
-        "gcp.vertex.agent.tool_response": "xxx"
+        "gen_ai.tool.description": "xxx",
+        "input.value": "{xxx}",
+        "output.value": "{xxx}"
     },
     "events": [],
     "links": [],
@@ -90,30 +148,47 @@ The instrumentation will generate traces showing the Google ADK operations:
             "telemetry.sdk.language": "python",
             "telemetry.sdk.name": "opentelemetry",
             "telemetry.sdk.version": "1.37.0",
-            "service.name": "demo-google-adk",
-            "telemetry.auto.version": "0.59b0"
+            "service.name": "demo-google-adk"
         },
         "schema_url": ""
     }
 }
 ```
 
-After [setting up jaeger](https://www.jaegertracing.io/docs/1.6/getting-started/) and exporting data to it by following these commands:
+#### LLM Chat Span Example
 
-```bash
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
-
-loongsuite-instrument \
---exporter_otlp_protocol grpc \
---traces_exporter otlp \
---exporter_otlp_insecure true \
---exporter_otlp_endpoint YOUR-END-POINT \
-python examples/main.py
+```json
+{
+    "name": "chat qwen-max",
+    "kind": "SpanKind.CLIENT",
+    "attributes": {
+        "gen_ai.operation.name": "chat",
+        "gen_ai.request.model": "qwen-max",
+        "gen_ai.response.model": "qwen-max",
+        "gen_ai.usage.input_tokens": 150,
+        "gen_ai.usage.output_tokens": 45
+    }
+}
 ```
 
-You can see traces on the jaeger UI:  
+#### Agent Invocation Span Example
+
+```json
+{
+    "name": "invoke_agent ToolAgent",
+    "kind": "SpanKind.CLIENT",
+    "attributes": {
+        "gen_ai.operation.name": "invoke_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\"}]}]"
+    }
+}
+```
 
+### Viewing in Jaeger
 
+After [setting up Jaeger](https://www.jaegertracing.io/docs/latest/getting-started/), you can visualize the complete trace hierarchy in the Jaeger UI, showing the relationships between Runner, Agent, LLM, and Tool spans  
 
 ## Configuration
 
@@ -124,6 +199,7 @@ 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` |
+| `DASHSCOPE_API_KEY` | DashScope API key (required for demo) | - |
 
 ### Programmatic Configuration
 
@@ -225,11 +301,28 @@ This instrumentation follows the OpenTelemetry GenAI semantic conventions:
 
 ### Common Issues
 
-1. **Module Import Error**: If you encounter `No module named 'google.adk.runners'`, ensure that `google-adk` is properly installed.
+1. **Module Import Error**: If you encounter `No module named 'google.adk.runners'`, ensure that `google-adk` is properly installed:
+   ```bash
+   pip install google-adk>=0.1.0
+   ```
+
+2. **DashScope API Error**: If you see authentication errors, verify your API key is correctly set:
+   ```bash
+   export DASHSCOPE_API_KEY=your-api-key
+   # Verify it's set
+   echo $DASHSCOPE_API_KEY
+   ```
+
+3. **Instrumentation Not Working**: 
+   - Check that the instrumentation is enabled and the Google ADK application is using the `Runner` class
+   - Verify you see the log message: `Plugin 'opentelemetry_adk_observability' registered`
+   - For manual instrumentation, ensure you call `GoogleAdkInstrumentor().instrument()` before creating the Runner
 
-2. **Instrumentation Not Working**: Check that the instrumentation is enabled and the Google ADK application is using the `Runner` class.
+4. **Missing Traces**: 
+   - Verify that the OpenTelemetry exporters are properly configured
+   - Check the `OTEL_TRACES_EXPORTER` environment variable is set (e.g., `console`, `otlp`)
+   - For OTLP exporter, ensure the endpoint is reachable
 
-3. **Missing Traces**: Verify that the OpenTelemetry exporters are properly configured.
 
 ## References