Gemini SDK Integration

SDK

Traccia automatically instruments Google's Gemini SDK for full observability of LLM calls.

Traccia automatically detects and instruments Google's Gemini SDK (google-genai in Python, @google/genaiin TypeScript) when it's installed. No extra code or configuration is required—just call init() and your Gemini calls are traced automatically, with prompt, completion, token usage, and cost captured on every span.

1Install Traccia and the Gemini SDK

Install both packages:

bash
pip install traccia google-genai

2Initialize Traccia

Initialize Traccia at the start of your application. Gemini tracing is auto-enabled when google-genai (Python) or @google/genai (TypeScript) is installed:

main.py
python
from traccia import init


# Minimal initialization
init()


# With API key
init(api_key="tr_live_xxxxxxxxxxxx")


# With custom config
init(
    endpoint="http://localhost:4318/v1/traces",
    agent_id="my-agent",
    sample_rate=0.1
)

3Call Gemini as Usual

Use the Gemini client's interactions.create() method as usual. Traccia captures the prompt, model, streaming flag, and (on non-streaming calls) usage, completion text, and interaction ID automatically:

gemini_call.py
python
from traccia import init
from google import genai


init()  # Automatically enables Gemini tracing


client = genai.Client(api_key="GEMINI_API_KEY")


# This call is automatically traced
response = client.interactions.create(
    model="gemini-2.5-flash",
    input="Write a haiku about recursion",
)
print(response.output_text)

Traccia monkey-patches GeminiNextGenInteractions.create (sync and async) during init(), wrapping every call in an llm.gemini.interaction span.

What Gets Traced

Every llm.gemini.interaction span captures:

llm.vendor / llm.model

Set to google_gemini and the requested model

llm.prompt

The interaction's input field, truncated to 4KB

llm.completion

The response's output_text, truncated to 4KB

llm.usage.prompt_tokens / completion_tokens / total_tokens

OpenAI-compatible token aliases for downstream processors

llm.usage.thought_tokens / cached_tokens / tool_use_tokens

Gemini-specific usage breakdown, when returned

llm.interaction_id / llm.previous_interaction_id

For multi-turn interaction chaining

llm.streaming

True when stream: true is passed

Streaming calls

For streaming requests, the span for the create()call resolves almost immediately with a stream object—before usage and output text exist. Traccia records llm.streaming: true but does not populate usage/completion attributes for streaming calls, to avoid recording near-zero duration and missing data.

Configuration

Gemini instrumentation is enabled by default when the SDK is installed and is covered by Traccia's global patching switch:

python
# Disable all auto-patching (including Gemini)
init(enable_patching=False)

Or via environment variable:

bash
export TRACCIA_ENABLE_PATCHING=false

Complete Example

movie_recommender.py
python
from traccia import init, span, stop_tracing
from google import genai


init()


client = genai.Client(api_key="GEMINI_API_KEY")


with span("recommendation_session") as session_span:
    session_span.set_attribute("user.preference.genre", "sci-fi")


    response = client.interactions.create(
        model="gemini-2.5-flash",
        input="Recommend 5 sci-fi movies for someone who liked Blade Runner",
    )


    session_span.set_attribute("recommendations.text_length", len(response.output_text))


print(response.output_text)


# Flush traces before exit
stop_tracing(flush_timeout=1.0)

Next Steps

Auto-Instrumentation

See all automatically traced libraries

OpenAI Agents SDK

Integrate Traccia with the OpenAI Agents SDK

Python SDK Reference

Full traccia.init() API reference

© 2026 Traccia.