Installation
Quick Start
What Gets Traced
- generateContent — input text (user messages only), output, model, token usage (promptTokenCount/candidatesTokenCount)
- Cached tokens —
cached_content_token_countfrom usage metadata →ai.usage.cached_tokens - Thinking tokens —
thoughts_token_countfrom usage metadata (Gemini 2.5) →ai.usage.thoughts_tokens - Finish reason —
candidate.finish_reason(STOP, MAX_TOKENS, SAFETY, RECITATION) →vertex_ai.finish_reason - Errors — captured with error status, re-thrown to caller
Configuration
Projects
Route events to a specific project by passing its slug asprojectId (project_id in Python):
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. Single-project orgs need nothing new.
Multiple projects in one process
Available inraindrop-ai>=0.0.56. When one service wraps several Vertex AI
clients that should report to different projects, create one
RaindropVertexAI 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=:
identify()
track_signal()
Tool catalog capture (ai.prompt.tools)
TypeScript. Every generateContent span records the request’s config.tools as ai.prompt.tools: each functionDeclarations entry becomes a function tool and other keys (googleSearch, codeExecution, …) become provider-defined tools. Pass tools on createRaindropVertexAI(...) to record a different list instead (it replaces the inferred one; tools: [] records an empty catalog).
Python. raindrop-vertex-ai ≥ 0.0.12 reads the list off the request itself (the OpenLLMetry Vertex AI / Google GenAI instrumentations record no tool definitions): every model span under a wrapped generate_content() / generate_content_stream() call (sync and aio) records config.tools, each function_declarations entry as a function tool (parameters or parameters_json_schema recorded as given as inputSchema) and other keys (google_search, code_execution, retrieval, url_context, …) as provider-defined tools; dict configs and GenerateContentConfig / Tool objects are both read. Capture is exact. Pass tools= on RaindropVertexAI(...) / create_raindrop_vertex_ai(...) to record a different list for every call through that wrapper (it replaces the inferred one; tools=[] records an empty catalog; no per-call override). Follows TRACELOOP_TRACE_CONTENT; needs raindrop-ai ≥ 0.0.70 and library instrumentation enabled (disable_auto_instrument=False). See Tool catalog capture for the attribute format, the absent / [] semantics and the override shapes accepted.
Flushing and Shutdown
finish_reason Tracking
The Python wrapper capturescandidate.finish_reason from Vertex AI responses and maps it to vertex_ai.finish_reason in event properties. Possible values: STOP, MAX_TOKENS, SAFETY, RECITATION.
Token Tracking
The following token usage fields are captured fromusage_metadata:
Factory Function
Acreate_raindrop_vertex_ai() factory is also available:
Application Git metadata (Python)
RaindropVertexAI(...) and create_raindrop_vertex_ai(...) 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.
Known Limitations
- Python SDK: No
events.*API — useraindrop.analyticsdirectly.identify()andtrack_signal()are available on the wrapper instance. - Streaming:
generateContentStream()is not instrumented. OnlygenerateContent()is traced.