Registry /
observability / opentelemetry-instrumentation-vertexai
Install & Compatibility
Where this runs
tested against v0.62.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
531MB installed
● package 531MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VertexAIInstrumentor
✓ from opentelemetry.instrumentation.vertexai import VertexAIInstrumentor
✗ from opentelemetry.instrumentation.vertexai import VertexAIInstrumentor
This quickstart demonstrates how to set up a basic OpenTelemetry SDK with a console exporter and enable the `opentelemetry-instrumentation-vertexai` library. It then makes a call to a Vertex AI GenerativeModel. Traces capturing the LLM interaction will be printed to the console. Ensure your Google Cloud authentication is configured (e.g., via `gcloud auth application-default login` or `GOOGLE_APPLICATION_CREDENTIALS`).
import os
import vertexai
from vertexai.generative_models import GenerativeModel
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.vertexai import VertexAIInstrumentor
# Configure OpenTelemetry SDK
resource = Resource.create({"service.name": "vertexai-app-example"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)
# Instrument Vertex AI
VertexAIInstrumentor().instrument()
# Initialize Vertex AI (ensure GOOGLE_APPLICATION_CREDENTIALS or gcloud auth is set)
# For a real application, consider explicit project/location via env vars or arguments
project_id = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id')
location = os.environ.get('GCP_LOCATION', 'us-central1')
vertexai.init(project=project_id, location=location)
# Use Vertex AI GenerativeModel
model = GenerativeModel("gemini-1.5-flash")
print(f"\n--- Invoking Vertex AI model ({model.model_name}) ---\n")
response = model.generate_content("Explain the importance of OpenTelemetry in AI observability.")
print("Response from model:")
for part in response.candidates[0].content.parts:
print(part.text)
print("\n--- Traces should be visible in console output ---\n")
Debug
Known issues
breakingThe library frequently updates to conform with evolving OpenTelemetry Generative AI Semantic Conventions (GenAI SemConv). This may lead to changes in span attribute names and data structures across minor versions, requiring adjustments in how you query or analyze your traces.fixReview the changelog and OpenTelemetry GenAI Semantic Conventions documentation for each upgrade to understand changes in attribute naming and structure. Adapt your observability queries or dashboards accordingly.
affects: 0.53.0 and later (due to ongoing GenAI SemConv updates)
gotchaBy default, this instrumentation logs prompts, completions, and embeddings to span attributes, which may contain sensitive user data. For privacy reasons or to reduce trace size, you might want to disable this behavior.fixSet the environment variable `TRACELOOP_TRACE_CONTENT=false` before running your application to prevent the logging of sensitive content to span attributes.
affects: All versions
gotchaThis instrumentation relies on the `google-cloud-aiplatform` and `google-generativeai` libraries. Ensure that compatible versions of these libraries are installed alongside the instrumentation to avoid runtime errors or incomplete tracing. Specific compatibility requirements may evolve.fixRefer to the `pyproject.toml` or `setup.py` of the `opentelemetry-instrumentation-vertexai` project on GitHub for precise version constraints. A common requirement is `google-cloud-aiplatform >= 1.38`.
affects: All versions
Upgrade
Version history
0.62.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
pythonrequiredRequired Python version
opentelemetry-apirequiredCore OpenTelemetry API
opentelemetry-sdkrequiredCore OpenTelemetry SDK for exporters and processors
opentelemetry-instrumentationrequiredBase OpenTelemetry instrumentation package
opentelemetry-semantic-conventionsrequiredOpenTelemetry general semantic conventions
opentelemetry-semantic-conventions-airequiredOpenTelemetry semantic conventions for AI
google-cloud-aiplatformrequiredThe underlying Vertex AI client library being instrumented
google-generativeairequiredRequired for Gemini model support and related instrumentation