Add a generative AI observability folder, with sample code for instrumenting the Gen AI SDK.

.github/CODEOWNERS

@@ -42,6 +42,9 @@
 /monitoring/prometheus                 @yuriatgoogle @GoogleCloudPlatform/python-samples-reviewers @GoogleCloudPlatform/cloud-samples-reviewers
 /trace/**/*                            @GoogleCloudPlatform/python-samples-reviewers @GoogleCloudPlatform/cloud-samples-reviewers
 
+# Cloud Observability + AI
+/generative_ai_observability/**/*      @GoogleCloudPlatform/opentelemetry-ops @GoogleCloudPlatform/generative-ai-devrel @GoogleCloudPlatform/python-samples-reviewers @GoogleCloudPlatform/cloud-samples-reviewers
+
 # DEE Data & AI
 /speech/**/*                           @GoogleCloudPlatform/cloud-speech-eng @GoogleCloudPlatform/python-samples-reviewers @GoogleCloudPlatform/cloud-samples-reviewers
 

generative_ai_observability/README.md

@@ -0,0 +1,3 @@
+# Generative AI Observability Samples
+
+These samples are intended to highlight how to use Google Cloud Observability (Cloud Logging, Cloud Monitoring, Cloud Trace) to provide observability for generative AI workloads, including on Google Cloud (Vertex, GKE, Cloud Run, etc.) and outside of Google Cloud.

generative_ai_observability/genaisdk/.gitignore

@@ -0,0 +1 @@
+venv

generative_ai_observability/genaisdk/Makefile

@@ -0,0 +1,11 @@
+.PHONY: all deps run
+
+all: deps run
+
+deps:
+	mkdir -p venv
+	python3 -m venv venv
+	bash -c 'source venv/bin/activate && pip install -r requirements.txt'
+
+run:
+	bash -c 'source venv/bin/activate && python3 main.py'

generative_ai_observability/genaisdk/README.md

@@ -0,0 +1,3 @@
+# Gen AI SDK Observability Sample
+
+This sample app demonstrates how to add observability to the Gen AI SDK, using Google Cloud Observability (Cloud Trace, Cloud Logging, Cloud Monitoring) as the observability backends for receiving the telemetry.

generative_ai_observability/genaisdk/main.py

@@ -0,0 +1,62 @@
+import logging
+
+from dotenv import load_dotenv
+from google.genai import Client
+from otel_setup import setup_otel_instrumentation, setup_otel_to_gcp_wiring
+
+
+# [START main_logic_support_snippet]
+def setup_telemetry() -> None:
+    """Initializes Open Telemetry instrumentation and wiring.
+
+    This ensures that:
+
+      1. The Gen AI SDK and its relevant dependencies collect and
+         emit telemetry data to the Open Telemetry API (library).
+
+      2. The Open Telemetry library is configured and initialized
+         so that the API is wired up with the Google Cloud Observability
+         suite rather than the default no-op implementation.
+    """
+    setup_otel_to_gcp_wiring()
+    setup_otel_instrumentation()
+
+
+def use_google_genai_sdk() -> None:
+    """An example function using the Gen AI SDK."""
+    client = Client()
+    response = client.models.generate_content(
+        model="gemini-2.0-flash-lite-001",
+        contents="Write a poem about the Google Gen AI SDK and observability.",
+    )
+    print(response.text)
+
+
+# [END main_logic_support_snippet]
+
+
+def main() -> None:
+    """Main program entrypoint.
+
+    This does the following:
+
+      1. Loads relevant configuration, including
+         initializing the environment from *.env
+         files as needed. Some of these environment
+         configurations affect telemetry behavior.
+
+      2. Initializes the telemetry instrumentation.
+
+      3. Actually does the core program logic (involving
+         some use of the Google Gen AI SDK).
+    """
+    load_dotenv()
+    # [START main_logic_snippet]
+    setup_telemetry()
+    use_google_genai_sdk()
+    # [END main_logic_snippet]
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    main()

generative_ai_observability/genaisdk/otel_setup/__init__.py

@@ -0,0 +1,4 @@
+from .setup_otel_instrumentation import setup_otel_instrumentation
+from .setup_otel_to_gcp_wiring import setup_otel_to_gcp_wiring
+
+__all__ = ["setup_otel_instrumentation", "setup_otel_to_gcp_wiring"]

generative_ai_observability/genaisdk/otel_setup/setup_otel_instrumentation.py

@@ -0,0 +1,46 @@
+"""Configures Open Telemetry instrumentation for Gen AI SDK.
+
+Configuring observability for the Gen AI SDK involves two steps:
+
+  1. Ensuring that data is written to Open Telemetry APIs when
+     the Gen AI SDK is used.
+
+  2. Ensuring that the Open Telemetry APIs route data to some
+     observability backend(s) for storing the data.
+
+This file addresses #1. This also means that this file can be used
+for observability of the Gen AI SDK in cases where you choose an
+observability backend other than those of Google Cloud Observability.\
+
+See also:
+ - https://github.com/open-telemetry/opentelemetry-python-contrib/
+      - /instrumentation-genai/opentelemetry-instrumentation-google-genai
+         - /examples/manual
+"""
+
+# [START setup_otel_instrumentation_snippet]
+from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+
+
+def setup_otel_instrumentation() -> None:
+    """Add telemetry collection and instrumentation to key libraries.
+
+    This function is responsible for monkey-patching multiple libraries of
+    interest to inject telemetry collection and instrumentation, routing
+    relevant telemetry information to the Open Telemetry library.
+    """
+    # Instrument the Gen AI SDK library (PyPi: "google-genai"). This
+    # monkey-patches that library to inject Open Telemetry instrumentation.
+    GoogleGenAiSdkInstrumentor().instrument()
+
+    # Instrument the Python Requests library (PyPi: "requests"). This
+    # monkey-patches that library to inject Open Telemetry instrumentation.
+    # The requests library is a dependency of the Gen AI SDK library; it is
+    # used to invoke the Vertex AI API or the Gemini API. Instrumenting this
+    # lower-level dependency of the Gen AI SDK provides more information
+    # about the timing and operation at lower layers of the stack.
+    RequestsInstrumentor().instrument()
+
+
+# [END setup_otel_instrumentation_snippet]