Choosing an integration path
Openlayer supports two ways to instrument Google ADK. Both land traces in the same Openlayer pipeline; pick the one that fits your stack.
The rest of this page walks through each path. If you’re not sure, start with the Openlayer tracer.
Do not enable both paths in the same process. See Don’t combine both paths.
Path 1 — Openlayer tracer (recommended)
A singleinit() call auto-instruments Google ADK (it runs trace_google_adk() under the hood) along with any other installed LLM SDKs.
Monitoring
To use the monitoring mode, you must instrument your code to publish the requests your AI system receives to the Openlayer platform. To set it up, you must follow the steps in the code snippet below:Python
See full Python example
- Agent execution with agent names, descriptions, and instructions
- LLM calls to Gemini models with messages and configurations
- Token usage including prompt tokens, completion tokens, and totals
- Tool calls with function names, arguments, and results
- Agent transfers and handoffs between sub-agents with proper hierarchy
- Session context including user IDs, session IDs, and invocation tracking
- Metadata such as latency and timestamps for all operations
The Google ADK integration automatically captures the full agent workflow,
including sub-agent handoffs and tool usage. You can use this together with
tracing to monitor complex multi-agent systems as part
of larger AI workflows. Make sure to call
init() before creating any
agents.Path 2 — ADK OpenTelemetry
As of ADK 1.17.0, the framework ships its own OpenTelemetry instrumentation (ADK traces, Cloud Observability) and can export traces over OTLP to any backend — including Openlayer. This is the path to use when you already run an OTel collector, or when application code is not allowed to depend on a vendor tracing SDK. Openlayer ingests the spans via its OpenTelemetry endpoint. ADK emits GenAI semantic-convention spans such asinvoke_agent, execute_tool, and generate_content, which Openlayer maps onto agent, tool, and chat-completion steps.
Install packages
Openlayer’s OTel endpoint accepts OTLP HTTP/protobuf (not gRPC). Install
opentelemetry-exporter-otlp-proto-http, not the gRPC exporter Google’s Cloud
Trace samples use. See the OpenTelemetry integration
page for the full endpoint reference.Configure the environment
Set the following environment variables before constructing any ADK agents. You can put them in the process environment, a dotenv file, oros.environ at process start.
YOUR_OPENLAYER_API_KEY and YOUR_OPENLAYER_PIPELINE_ID with values from your Openlayer workspace. The x-bt-parent header is what routes traces to the correct inference pipeline — not OTEL_SERVICE_NAME.
Google’s Cloud Observability docs recommend
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=EVENT_ONLY and
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false, which keep prompts and responses
off span attributes (they go to log records instead). Openlayer’s OTel
endpoint ingests traces, not logs, and tests need Input / Output on those
traces. Use SPAN_ONLY and ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true so
content lands on the spans Openlayer maps (gen_ai.input.messages /
gen_ai.output.messages and ADK’s own span attributes).OTEL_LOGS_EXPORTER=none and OTEL_METRICS_EXPORTER=none avoid failed export attempts. Google’s OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED setting is for Cloud Logging and is not needed here.
Wire the exporter
Call ADK’smaybe_set_otel_providers() before importing or constructing agents. It reads the OTEL_EXPORTER_OTLP_* environment variables and installs HTTP OTLP exporters.
Python
TracerProvider (for example via opentelemetry-instrument or an in-process collector), skip maybe_set_otel_providers() — ADK will use the provider that is already set. If you call Vertex AI through the vertexai SDK rather than google.genai, also run VertexAIInstrumentor().instrument() from opentelemetry.instrumentation.vertexai.
To send traces through an existing OpenTelemetry Collector instead of exporting from the app, keep ADK pointed at the collector and add an OTLP/HTTP exporter on the collector to https://api.openlayer.com/v1/otel/v1/traces with the same Authorization and x-bt-parent headers.
adk web / adk api_server
You do not need Google’s --otel_to_cloud flag. That flag wires GCP exporters specifically. For an arbitrary OTLP backend, set the environment variables above and run:
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (or OTEL_EXPORTER_OTLP_ENDPOINT) and exports spans over OTLP HTTP.
What the traces look like
A typical ADK OTel trace is hierarchical, not flat:
Sub-agents appear as nested
invoke_agent spans under the parent agent. That maps onto Openlayer’s agent-trace hierarchy the same way other GenAI OTel sources do.
Don’t combine both paths
The Openlayer tracer replaces ADK’s own OpenTelemetry tracer with a no-op so ADK does not emit a second copy of agent and tool spans. The Google GenAI / Vertex AI instrumentors patch the model SDK independently, so LLM spans can still be duplicated. Enable eitherinit() or ADK’s OTel exporters pointed at Openlayer — not both. init() already calls trace_google_adk(), so running it together with Path 2 duplicates traces in Openlayer. If you switch from the native tracer to OTel, call unpatch_google_adk() (or restart the process without init()).
Comparison: which path produces what
Development
In development mode, Openlayer becomes a step in your CI/CD pipeline, and your tests get automatically evaluated after being triggered by some events. Openlayer tests often rely on your AI system’s outputs on a validation dataset. As discussed in the Configuring output generation guide, you have two options:- either provide a way for Openlayer to run your AI system on your datasets, or
- before pushing, generate the model outputs yourself and push them alongside your artifacts.
GOOGLE_API_KEY or appropriate service account credentials).
If you don’t add the required API credentials, you’ll encounter a “Missing API key” error when Openlayer tries to run your AI system to get its outputs.