{"id":2168,"library":"opentelemetry-instrumentation-vertexai","title":"OpenTelemetry Vertex AI Instrumentation","description":"This library provides OpenTelemetry instrumentation for Google Cloud's Vertex AI, allowing developers to trace prompts, completions, and embeddings from Vertex AI models. It integrates with the official Vertex AI Python client library. The current version is 0.58.0, with frequent releases, often multiple times a month, reflecting active development.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-vertexai","tags":["opentelemetry","instrumentation","vertexai","google cloud","llm","ai","generative ai","observability","tracing"],"install":[{"cmd":"pip install opentelemetry-instrumentation-vertexai","lang":"bash","label":"Install library"},{"cmd":"pip install opentelemetry-sdk google-cloud-aiplatform google-generativeai","lang":"bash","label":"Install OpenTelemetry SDK and Vertex AI dependencies"}],"dependencies":[{"reason":"Required Python version","package":"python","version":">=3.10, <4"},{"reason":"Core OpenTelemetry API","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK for exporters and processors","package":"opentelemetry-sdk","optional":false},{"reason":"Base OpenTelemetry instrumentation package","package":"opentelemetry-instrumentation","optional":false},{"reason":"OpenTelemetry general semantic conventions","package":"opentelemetry-semantic-conventions","optional":false},{"reason":"OpenTelemetry semantic conventions for AI","package":"opentelemetry-semantic-conventions-ai","optional":false},{"reason":"The underlying Vertex AI client library being instrumented","package":"google-cloud-aiplatform","version":">=1.38","optional":false},{"reason":"Required for Gemini model support and related instrumentation","package":"google-generativeai","optional":false}],"imports":[{"note":"Import the instrumentor class to enable tracing for Vertex AI.","symbol":"VertexAIInstrumentor","correct":"from opentelemetry.instrumentation.vertexai import VertexAIInstrumentor"}],"quickstart":{"code":"import os\nimport vertexai\nfrom vertexai.generative_models import GenerativeModel\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.vertexai import VertexAIInstrumentor\n\n# Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": \"vertexai-app-example\"})\ntracer_provider = TracerProvider(resource=resource)\ntracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(tracer_provider)\n\n# Instrument Vertex AI\nVertexAIInstrumentor().instrument()\n\n# Initialize Vertex AI (ensure GOOGLE_APPLICATION_CREDENTIALS or gcloud auth is set)\n# For a real application, consider explicit project/location via env vars or arguments\nproject_id = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id')\nlocation = os.environ.get('GCP_LOCATION', 'us-central1')\nvertexai.init(project=project_id, location=location)\n\n# Use Vertex AI GenerativeModel\nmodel = GenerativeModel(\"gemini-1.5-flash\")\n\nprint(f\"\\n--- Invoking Vertex AI model ({model.model_name}) ---\\n\")\nresponse = model.generate_content(\"Explain the importance of OpenTelemetry in AI observability.\")\n\nprint(\"Response from model:\")\nfor part in response.candidates[0].content.parts:\n    print(part.text)\nprint(\"\\n--- Traces should be visible in console output ---\\n\")\n","lang":"python","description":"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`)."},"warnings":[{"fix":"Review 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.","message":"The 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.","severity":"breaking","affected_versions":"0.53.0 and later (due to ongoing GenAI SemConv updates)"},{"fix":"Set the environment variable `TRACELOOP_TRACE_CONTENT=false` before running your application to prevent the logging of sensitive content to span attributes.","message":"By 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer 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`.","message":"This 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}