Trace Vertex AI Gemini requests

Trace Gemini requests on Vertex AI in Future AGI using traceAI-google-genai and the Google Gen AI SDK.

Before you start

You need Python 3.11–3.13, a Google Cloud project with the Vertex AI API enabled, access to your chosen model in its location, and Future AGI API keys.

Install the SDK and instrumentation

pip install traceAI-google-genai google-genai

Do not install the separate vertexai distribution. GoogleGenAIInstrumentor instruments the Google Gen AI SDK, including clients configured with vertexai=True.

Configure credentials

Use Application Default Credentials for Google Cloud. For local development:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_MODEL="your-enabled-model-id"
export FI_API_KEY="your-future-agi-api-key"
export FI_SECRET_KEY="your-future-agi-secret-key"

Replace the model ID with one available to your project and location. If your model requires a region, use that region instead of global. In a deployed application, use its service account or another supported Application Default Credentials configuration instead of interactive login.

The instrumentor captures request and response content by default. Before initializing tracing, set FI_HIDE_INPUTS=true and FI_HIDE_OUTPUTS=true if you need to redact inputs, outputs, and messages. These switches do not redact all model configuration or custom attributes; review the field-specific masking controls before sending sensitive data.

Send a traced request

Save this as vertexai_example.py. Initialize tracing once, before making requests:

import os

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from google import genai
from traceai_google_genai import GoogleGenAIInstrumentor


def main():
    trace_provider = register(
        project_type=ProjectType.OBSERVE,
        project_name="vertexai_app",
    )
    GoogleGenAIInstrumentor().instrument(tracer_provider=trace_provider)
    try:
        client = genai.Client(
            vertexai=True,
            project=os.environ["GOOGLE_CLOUD_PROJECT"],
            location=os.environ["GOOGLE_CLOUD_LOCATION"],
        )
        response = client.models.generate_content(
            model=os.environ["GOOGLE_GENAI_MODEL"],
            contents="Write a haiku about a mountain trail.",
        )
        print(response.text)
    finally:
        trace_provider.force_flush()


if __name__ == "__main__":
    main()

python vertexai_example.py

Open Observe → Traces in Future AGI and select the vertexai_app project. Inspect the generation span, input and output content unless masked, and token usage returned by the SDK.

Migrate an existing Vertex AI SDK app

Google removed the legacy generative AI modules from SDK releases after June 24, 2026. traceAI-vertexai supports google-cloud-aiplatform>=1.61.0,<=1.101.0; it does not instrument google-genai.

While migrating an existing app that imports vertexai.generative_models, keep the legacy SDK within that supported range:

pip install traceAI-vertexai 'google-cloud-aiplatform==1.101.0'

Keep VertexAIInstrumentor().instrument(tracer_provider=trace_provider) before importing vertexai so the legacy clients are wrapped when created. Use a supported region such as us-central1, not global, with the legacy SDK. Pinning the SDK preserves its modules; it does not restore retired models or service endpoints.

Follow Google’s SDK migration guide to replace the application’s imports, client construction, and calls. Then replace VertexAIInstrumentor with GoogleGenAIInstrumentor as shown above. Do not enable both instrumentors for the same SDK call. The Google Gen AI integration covers additional generation examples.

Troubleshooting

• ModuleNotFoundError: vertexai.generative_models: migrate to google-genai, or use the bounded legacy dependency above while migrating. Installing vertexai separately is not the migration.
• No spans after switching to google-genai: replace VertexAIInstrumentor with GoogleGenAIInstrumentor and initialize it before requests. Keep force_flush() before a short-lived script exits.
• Authentication, model, or location errors: check Application Default Credentials, Vertex AI permissions, and the model’s availability in your project and location. Changing the tracing package does not restore retired models.