> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/_mcp/server.

# Google GenAI (tracing)

> Trace Google GenAI SDK calls with Respan — auto-instrumented spans, gateway routing, and full observability.

The official [Google Gen AI](https://googleapis.github.io/python-genai/) SDK (`google-genai`) is the Python client for Gemini models, supporting text, multimodal prompts, streaming, tool use, and structured outputs. Respan gives you full observability over every Gemini generation, streamed response, token count, and model tool call — and gateway routing through the Respan endpoint.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/api/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [Google Gen AI gateway setup](/docs/gateway/google-genai) to route this integration through the Respan gateway.

#### Example projects

* [Example project repository](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-google-genai google-genai
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
# Optional for direct Google calls while still exporting traces to Respan
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
```

If `GOOGLE_API_KEY` is not set, route through the Respan Gemini gateway with `RESPAN_API_KEY`. Gateway calls require Gemini provider credentials or managed credits configured on your Respan account.

#### Initialize and run

```python
import os
from google import genai
from respan import Respan
from respan_instrumentation_google_genai import GoogleGenAIInstrumentor

respan = Respan(instrumentations=[GoogleGenAIInstrumentor()])

client = genai.Client(
    api_key=os.environ.get("GOOGLE_API_KEY") or os.environ["RESPAN_API_KEY"],
    http_options=None if os.environ.get("GOOGLE_API_KEY") else {
        "base_url": "https://api.respan.ai/api/google/gemini"
    },
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Say hello in three languages.",
)
print(response.text)
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your Gemini span with prompt content, completion content, model name, token usage, and tool-call attributes.

## Configuration

| Parameter             | Type           | Default | Description                                                               |
| --------------------- | -------------- | ------- | ------------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.                                   |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.                                  |
| `instrumentations`    | `list`         | `[]`    | Plugin instrumentations to activate, such as `GoogleGenAIInstrumentor()`. |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans.                                |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.                                   |
| `environment`         | `str \| None`  | `None`  | Environment tag, such as `"production"`.                                  |

## Attributes

### In Respan()

Set defaults at initialization — these apply to all generated spans.

```python
from respan import Respan
from respan_instrumentation_google_genai import GoogleGenAIInstrumentor

respan = Respan(
    instrumentations=[GoogleGenAIInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "gemini-api", "version": "1.0.0"},
)
```

### With propagate\_attributes

Override per-request using a context scope.

```python
from google import genai
from respan import Respan, propagate_attributes
from respan_instrumentation_google_genai import GoogleGenAIInstrumentor

respan = Respan(instrumentations=[GoogleGenAIInstrumentor()])
client = genai.Client(
    api_key=os.environ.get("GOOGLE_API_KEY") or os.environ["RESPAN_API_KEY"],
    http_options=None if os.environ.get("GOOGLE_API_KEY") else {
        "base_url": "https://api.respan.ai/api/google/gemini"
    },
)

def handle_request(user_id: str, question: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        response = client.models.generate_content(
            model="gemini-2.5-flash",
            contents=question,
        )
        print(response.text)
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |