Skip to content

Commit 0dbc37d

Browse files
google-genai-botcopybara-github
authored andcommitted
feat(telemetry): Add script execution instrumentation
PiperOrigin-RevId: 971725267
1 parent c300b8d commit 0dbc37d

24 files changed

Lines changed: 2476 additions & 184 deletions

‎src/google/adk/code_executors/code_execution_utils.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,12 @@ class CodeExecutionResult:
8383
The output files from the code execution.
8484
"""
8585

86+
exit_code: int | None = None
87+
"""
88+
The status the executed process exited with, or None when the executor could
89+
not report one.
90+
"""
91+
8692

8793
class CodeExecutionUtils:
8894
"""Utility functions for code execution."""

‎src/google/adk/code_executors/container_code_executor.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -272,6 +272,7 @@ def execute_code(
272272
stdout=output,
273273
stderr=error,
274274
output_files=[],
275+
exit_code=exec_result.exit_code,
275276
)
276277

277278
def _build_docker_image(self) -> None:

‎src/google/adk/code_executors/gke_code_executor.py‎

Lines changed: 61 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,10 @@
4545

4646
logger = logging.getLogger("google_adk." + __name__)
4747

48+
# Name of the Job container that runs the user's code, and so the one whose
49+
# termination status is the status of the execution.
50+
_CODE_CONTAINER_NAME = "code-runner"
51+
4852

4953
class GkeCodeExecutor(BaseCodeExecutor):
5054
"""Executes Python code in a secure gVisor-sandboxed Pod on GKE.
@@ -187,7 +191,11 @@ def _execute_in_sandbox(self, code: str) -> CodeExecutionResult:
187191
sandbox.write("script.py", code)
188192
result = sandbox.run("python3 script.py")
189193

190-
return CodeExecutionResult(stdout=result.stdout, stderr=result.stderr)
194+
return CodeExecutionResult(
195+
stdout=result.stdout,
196+
stderr=result.stderr,
197+
exit_code=result.exit_code,
198+
)
191199
except RuntimeError as e:
192200
logger.error(
193201
"SandboxClient failed to initialize or find gateway", exc_info=True
@@ -272,7 +280,7 @@ def _create_job_manifest(
272280
"""Creates the complete V1Job object with security best practices."""
273281
# Define the container that will run the code.
274282
container = k8s.client.V1Container(
275-
name="code-runner",
283+
name=_CODE_CONTAINER_NAME,
276284
image=self.image,
277285
command=["python3", "/app/code.py"],
278286
volume_mounts=[
@@ -350,16 +358,25 @@ def _watch_job_completion(self, job_name: str) -> CodeExecutionResult:
350358
timeout_seconds=self.timeout_seconds,
351359
):
352360
job = event["object"]
361+
# The Job reports only whether the pod succeeded, so the status the
362+
# container terminated with is read from the pod itself. It is absent
363+
# when the pod never reached a terminated state, and only then is the
364+
# code narrowed to the one the Job's outcome implies.
353365
if job.status.succeeded:
354366
watch.stop()
355367
logger.info(f"Job '{job_name}' succeeded.")
356-
logs = self._get_pod_logs(job_name)
357-
return CodeExecutionResult(stdout=logs)
368+
logs, exit_code = self._get_pod_logs_and_exit_code(job_name)
369+
return CodeExecutionResult(
370+
stdout=logs, exit_code=0 if exit_code is None else exit_code
371+
)
358372
if job.status.failed:
359373
watch.stop()
360374
logger.error(f"Job '{job_name}' failed.")
361-
logs = self._get_pod_logs(job_name)
362-
return CodeExecutionResult(stderr=f"Job failed. Logs:\n{logs}")
375+
logs, exit_code = self._get_pod_logs_and_exit_code(job_name)
376+
return CodeExecutionResult(
377+
stderr=f"Job failed. Logs:\n{logs}",
378+
exit_code=1 if exit_code is None else exit_code,
379+
)
363380

364381
# If the loop finishes without returning, the watch timed out.
365382
raise TimeoutError(
@@ -371,6 +388,25 @@ def _watch_job_completion(self, job_name: str) -> CodeExecutionResult:
371388
def _get_pod_logs(self, job_name: str) -> str:
372389
"""Retrieves logs from the pod created by the specified job.
373390
391+
Raises:
392+
RuntimeError: If the pod cannot be found or logs cannot be fetched.
393+
"""
394+
logs, _ = self._get_pod_logs_and_exit_code(job_name)
395+
return logs
396+
397+
def _get_pod_logs_and_exit_code(
398+
self, job_name: str
399+
) -> tuple[str, int | None]:
400+
"""Retrieves the logs and exit code of the pod created by the given job.
401+
402+
Both are read from a single pod lookup, since the status a container
403+
terminated with is only available for as long as the pod its logs come
404+
from.
405+
406+
Returns:
407+
The pod's logs, and the status the code container exited with, or None
408+
when the pod reports no terminated container to read it from.
409+
374410
Raises:
375411
RuntimeError: If the pod cannot be found or logs cannot be fetched.
376412
"""
@@ -385,18 +421,34 @@ def _get_pod_logs(self, job_name: str) -> str:
385421
f"Could not find Pod for Job '{job_name}' to retrieve logs."
386422
)
387423

388-
pod_name = pods.items[0].metadata.name
389-
return cast(
424+
pod = pods.items[0]
425+
logs = cast(
390426
str,
391427
self._core_v1.read_namespaced_pod_log(
392-
name=pod_name, namespace=self.namespace
428+
name=pod.metadata.name, namespace=self.namespace
393429
),
394430
)
431+
return logs, self._get_container_exit_code(pod)
395432
except ApiException as e:
396433
raise RuntimeError(
397434
f"API error retrieving logs for job '{job_name}': {e.reason}"
398435
) from e
399436

437+
def _get_container_exit_code(self, pod: k8s.client.V1Pod) -> int | None:
438+
"""Reads the status the code container of the given pod exited with.
439+
440+
Returns:
441+
The exit code, or None when the container is absent from the pod's
442+
status or has not reached a terminated state.
443+
"""
444+
for container_status in pod.status.container_statuses or []:
445+
if container_status.name != _CODE_CONTAINER_NAME:
446+
continue
447+
state = container_status.state
448+
terminated = state.terminated if state else None
449+
return terminated.exit_code if terminated else None
450+
return None
451+
400452
def _create_code_configmap(self, name: str, code: str) -> None:
401453
"""Creates a ConfigMap to hold the Python code."""
402454
body = k8s.client.V1ConfigMap(

‎src/google/adk/code_executors/unsafe_local_code_executor.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,4 +196,5 @@ def execute_code(
196196
stdout=output,
197197
stderr=error,
198198
output_files=[],
199+
exit_code=process.returncode,
199200
)

‎src/google/adk/integrations/cloud_run/_cloud_run_sandbox_code_executor.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
from __future__ import annotations
1616

1717
import logging
18+
import signal
1819
import subprocess
1920
import sys
2021
from typing import Optional
@@ -29,6 +30,12 @@
2930

3031
logger = logging.getLogger('google_adk.' + __name__)
3132

33+
# `subprocess.run` kills the sandbox before re-raising `TimeoutExpired`, so the
34+
# run does have a status even though the exception carries none: SIGKILL on
35+
# POSIX, reported as a negative signal number the way `UnsafeLocalCodeExecutor`
36+
# reports its own timeouts, and `TerminateProcess`'s 1 on Windows.
37+
_TIMEOUT_EXIT_CODE = -signal.SIGKILL if hasattr(signal, 'SIGKILL') else 1
38+
3239

3340
def _filter_stderr(stderr: str | None) -> str:
3441
"""Filters out harmless sandbox warning messages from stderr."""
@@ -146,6 +153,7 @@ def execute_code(
146153
stdout=result.stdout,
147154
stderr=stderr_filtered,
148155
output_files=[],
156+
exit_code=result.returncode,
149157
)
150158

151159
except subprocess.TimeoutExpired as e:
@@ -169,6 +177,7 @@ def execute_code(
169177
stderr=stderr_filtered
170178
or f'Code execution timed out after {self.timeout_seconds} seconds.',
171179
output_files=[],
180+
exit_code=_TIMEOUT_EXIT_CODE,
172181
)
173182
except FileNotFoundError as e:
174183
logger.error('Sandbox binary not found: %s', e)

‎src/google/adk/telemetry/_adk_attributes.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,13 @@
3333
)
3434
ADK_EXPERIMENTAL_SKILL_SOURCE_URI = 'adk.experimental.skill.source.uri'
3535
ADK_EXPERIMENTAL_SKILL_RESOURCE_PATH = 'adk.experimental.skill.resource.path'
36+
ADK_EXPERIMENTAL_SKILL_SCRIPT_PATH = 'adk.experimental.skill.script.path'
37+
ADK_EXPERIMENTAL_SKILL_SCRIPT_ENDED_WITH_ERROR = (
38+
'adk.experimental.skill.script.ended_with_error'
39+
)
40+
ADK_EXPERIMENTAL_SKILL_SCRIPT_EXIT_CODE = (
41+
'adk.experimental.skill.script.exit_code'
42+
)
3643

3744
ADK_EXPERIMENTAL_CONTEXT_CACHE_HIT = 'adk.experimental.context_cache.hit'
3845
ADK_EXPERIMENTAL_CONTEXT_CACHE_FINGERPRINT = (
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Utilities for type-safe handling of potentially hallucinated values generated by LLMs."""
16+
17+
from __future__ import annotations
18+
19+
import dataclasses
20+
from typing import cast
21+
from typing import Generic
22+
from typing import TypeVar
23+
24+
from typing_extensions import Literal
25+
26+
_T = TypeVar("_T")
27+
28+
29+
@dataclasses.dataclass(frozen=True)
30+
class MaybeHallucinated(Generic[_T]):
31+
"""A value the model supplied that is not yet confirmed to be valid.
32+
33+
Attributes:
34+
maybe_hallucinated_value: The value as the model wrote it.
35+
"""
36+
37+
maybe_hallucinated_value: _T
38+
39+
def bounded(self) -> _T | Literal["<hallucinated>"]:
40+
"""Reduces this value to a set of correct values.
41+
42+
Returns:
43+
The value itself if it is confirmed to be valid, and the replacement
44+
value otherwise.
45+
"""
46+
if isinstance(self, ConfirmedNotHallucinated):
47+
return cast(_T, self.maybe_hallucinated_value)
48+
return "<hallucinated>"
49+
50+
51+
@dataclasses.dataclass(frozen=True)
52+
class ConfirmedNotHallucinated(MaybeHallucinated[_T]):
53+
"""A value the model supplied that is confirmed to be valid."""
54+
55+
@property
56+
def value(self) -> _T:
57+
return self.maybe_hallucinated_value

0 commit comments

Comments
 (0)