Installation
Quick Start
What Gets Traced
The Google ADK integration automatically captures:- Runner invocations — input message, user_id, session_id, app_name
- Agent responses — final output text from the agent
- Token usage — prompt_tokens, completion_tokens, total_tokens from usage metadata
- Tool calls — individual tool spans with name, input, output, duration, and error
- Model info — model version when available (e.g.,
gemini-2.5-flash) - Agent identity — agent name, author from events
- Finish reason — why generation stopped (e.g., STOP, SAFETY, MAX_TOKENS)
- Errors — captured (with error message) and re-raised to the caller
- Async support — both
run()(sync) andrun_async()(async) are instrumented
Configuration
Auto-instrumentation (recommended)
Usesetup_google_adk() to automatically patch all ADK Runner instances:
Manual wrapping
Usecreate_raindrop_google_adk() to wrap specific Runner instances:
Class-based API
Debug Mode
Enable verbose logging to troubleshoot integration issues:debug=True, internal telemetry operations (event extraction, interaction lifecycle) are logged at the DEBUG level via Python’s standard logging module.
Projects
Route events to a specific project by passing its slug asproject_id:
project_id sets the X-Raindrop-Project-Id header on every event. Omit it (or pass "default") to use your org’s default Production project, which is the existing behavior. The same option is accepted by create_raindrop_google_adk(...) and RaindropGoogleADK(...). Invalid slugs are ignored with a warning and no header is sent.
Multiple projects in one process
Available inraindrop-ai>=0.0.56. When one service runs several ADK runners
that should report to different projects, create one RaindropGoogleADK
wrapper per project. Each wrapper owns its own raindrop.Raindrop client, so
the two route independently — there is no shared module-level state:
raindrop.Raindrop yourself and pass
it via client=:
Use
wrap() — not setup() — for multiple projects. setup_google_adk() /
RaindropGoogleADK.setup() patches the ADK Runner class process-globally,
so only the first setup()’s project owns class-wide auto-instrumentation; a
second setup() with a different project keeps routing to the first and emits a
warning. wrap(runner) instruments a specific runner with that wrapper’s own
client, taking precedence over any class-level setup() patch for that runner —
so per-runner routing stays correct even if setup() ran earlier in the process.Identify
Associate a user with traits for downstream analysis:Track Signal
Track feedback, edits, or custom signals tied to a specific event:Tool Call Tracking
When your agent uses tools, individual tool spans are captured automatically with name, input, output, duration, and error status:Multi-Agent Workflows
Google ADK supports complex agent topologies — sequential agents, parallel agents, and nested sub-agents. The integration captures the top-level Runner invocations regardless of agent complexity:ai_generation event per Runner.run() invocation.
ADK can mark one final response per participating agent, so for multi-agent
invocations the event output is the last non-empty final agent response. Earlier
agent responses are not merged into the displayed conversation output.
Output-specific metadata such as model, author, agent name, branch, and finish
reason comes from that selected response, while token and tool counts cover the
full invocation.
Async Usage
The wrapper supports both sync and async runner usage:Finish Reason Tracking
The integration captures thefinish_reason from model responses, indicating why generation stopped. Common values include:
This is available in event properties as
google_adk.finish_reason.
Token Tracking
Token usage is accumulated across all model calls within a singleRunner.run() invocation. The following fields are captured:
Captured Properties
Each event includes the following properties when available:Flushing and Shutdown
Always callshutdown() before your process exits to ensure all telemetry is shipped:
Application Git metadata (Python)
RaindropGoogleADK(...), create_raindrop_google_adk(...), and setup_google_adk(...) accept the keyword-only app_git option. It defaults to True: explicit Raindrop Git environment or deployment context is applied immediately, and the base SDK may perform one bounded background local-Git lookup from the process working directory. Event capture, flush, and shutdown never wait for that lookup. Pass False to disable enrichment, or pass an AppGitOptions mapping with commit_sha, commit_dirty, branch, source_directory, detect_branch, and/or auto_detect. Automatic branch discovery remains opt-in through detect_branch=True (or RAINDROP_GIT_DETECT_BRANCH=true).
For an ordinary in-process application, the process working directory is treated as the application-under-test checkout. A remote, coding, workflow, or observer process must not rely on its own checkout: pass app_git=False, provide explicit revision values, or set source_directory to the actual application checkout. Canonical per-operation properties remain authoritative. When supplying client=, configure app_git while constructing that Raindrop client; the supplied client is authoritative and the wrapper’s app_git argument does not reconfigure it.
Release order is deliberate: first publish the base SDK feature, then publish the wrapper feature release with its minimum dependency coordinated to that base release. The existing raindrop-ai lower bound remains compatible, but application Git metadata is unavailable on an older core and must not be claimed complete until the base is upgraded. Until coordination assigns a released version, the wrapper checks for an explicit base app_git parameter and omits the option when unsupported. Explicit non-default configuration is debug-logged and omitted. Unsupported app_git is determined by signature inspection before construction, not by retrying initialization after a TypeError; Git configuration adds no initialization attempts and does not change any existing framework-specific initialization fallback.
Factory Function (backward compat)
Thesetup_google_adk() and create_raindrop_google_adk() factory functions return RaindropGoogleADK instances and accept the same parameters: