google-agents-cli-extensions 1.14.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. core/claude/README.md +35 -0
  2. core/claude/template/.agents/skills/agents-cli-claude/SKILL.md +106 -0
  3. core/claude/template/.agents/skills/agents-cli-claude/references/claude.md +386 -0
  4. core/claude/template/.agents/skills/agents-cli-claude/references/migrate-claude-agent.md +318 -0
  5. core/claude/template/.agents/skills/agents-cli-claude/references/migrate-from-aws.md +132 -0
  6. core/claude/template/.dockerignore +28 -0
  7. core/claude/template/.env +18 -0
  8. core/claude/template/.env.example +17 -0
  9. core/claude/template/.template/templateconfig.yaml +31 -0
  10. core/claude/template/AGENTS.md +33 -0
  11. core/claude/template/Dockerfile +55 -0
  12. core/claude/template/agent_config/README.md +9 -0
  13. core/claude/template/agents-cli-extension.yaml +49 -0
  14. core/claude/template/app/__init__.py +15 -0
  15. core/claude/template/app/agent.py +49 -0
  16. core/claude/template/app/app_utils/a2a.py +245 -0
  17. core/claude/template/app/app_utils/bq_analytics/__init__.py +124 -0
  18. core/claude/template/app/app_utils/bq_analytics/recorder.py +593 -0
  19. core/claude/template/app/app_utils/bq_analytics/redaction.py +209 -0
  20. core/claude/template/app/app_utils/bq_analytics/schema.py +394 -0
  21. core/claude/template/app/app_utils/bq_analytics/tables.py +104 -0
  22. core/claude/template/app/app_utils/bq_analytics/uploader.py +188 -0
  23. core/claude/template/app/app_utils/claude.py +297 -0
  24. core/claude/template/app/app_utils/completions.py +225 -0
  25. core/claude/template/app/app_utils/conversation.py +29 -0
  26. core/claude/template/app/app_utils/memory_bank.py +308 -0
  27. core/claude/template/app/app_utils/project_settings.py +91 -0
  28. core/claude/template/app/app_utils/reasoning_engine.py +237 -0
  29. core/claude/template/app/app_utils/remote_agents.py +349 -0
  30. core/claude/template/app/app_utils/remote_auth.py +159 -0
  31. core/claude/template/app/app_utils/replies.py +143 -0
  32. core/claude/template/app/app_utils/session_store.py +174 -0
  33. core/claude/template/app/app_utils/settings.py +24 -0
  34. core/claude/template/app/app_utils/telemetry/__init__.py +114 -0
  35. core/claude/template/app/app_utils/telemetry/call_counts.py +44 -0
  36. core/claude/template/app/app_utils/telemetry/cli_relay.py +266 -0
  37. core/claude/template/app/app_utils/telemetry/config.py +133 -0
  38. core/claude/template/app/app_utils/telemetry/logs.py +175 -0
  39. core/claude/template/app/app_utils/telemetry/metrics.py +270 -0
  40. core/claude/template/app/app_utils/telemetry/request_flush.py +104 -0
  41. core/claude/template/app/app_utils/telemetry/subagent_spans.py +80 -0
  42. core/claude/template/app/app_utils/telemetry/traces.py +166 -0
  43. core/claude/template/app/app_utils/turn_events.py +463 -0
  44. core/claude/template/app/app_utils/turn_options.py +219 -0
  45. core/claude/template/app/app_utils/workspaces.py +65 -0
  46. core/claude/template/app/fast_api_app.py +71 -0
  47. core/claude/template/app/feature_tools.py +27 -0
  48. core/claude/template/pyproject.toml +100 -0
  49. core/claude/template/scripts/eval_generate.py +340 -0
  50. core/claude/template/scripts/publish.py +66 -0
  51. core/claude/template/scripts/run.py +85 -0
  52. core/claude/template/scripts/unsupported.py +48 -0
  53. core/claude/template/tests/eval/datasets/basic-dataset.json +31 -0
  54. core/claude/template/tests/eval/eval_config.yaml +17 -0
  55. core/claude/template/tests/eval/response_quality.py +60 -0
  56. core/claude/template/tests/integration/test_server_e2e.py +168 -0
  57. core/claude/template/tests/load_test/.results/.placeholder +0 -0
  58. core/claude/template/tests/load_test/README.md +24 -0
  59. core/claude/template/tests/load_test/load_test.py +118 -0
  60. core/claude/template/tests/unit/conftest.py +63 -0
  61. core/claude/template/tests/unit/helpers.py +32 -0
  62. core/claude/template/tests/unit/test_a2a.py +432 -0
  63. core/claude/template/tests/unit/test_bq_analytics.py +928 -0
  64. core/claude/template/tests/unit/test_bq_redaction.py +89 -0
  65. core/claude/template/tests/unit/test_claude.py +825 -0
  66. core/claude/template/tests/unit/test_completions.py +369 -0
  67. core/claude/template/tests/unit/test_fast_api_app.py +59 -0
  68. core/claude/template/tests/unit/test_feature_tools.py +55 -0
  69. core/claude/template/tests/unit/test_memory_bank.py +625 -0
  70. core/claude/template/tests/unit/test_reasoning_engine.py +295 -0
  71. core/claude/template/tests/unit/test_remote_agents.py +517 -0
  72. core/claude/template/tests/unit/test_telemetry.py +991 -0
  73. core/claude/template/tests/unit/test_turn_events.py +309 -0
  74. core/claude/template/tests/unit/test_turn_options.py +394 -0
  75. core/claude/template/uv.lock +3029 -0
  76. core/langchain/README.md +54 -0
  77. core/langchain/template/.agents/skills/agents-cli-langchain/SKILL.md +84 -0
  78. core/langchain/template/.agents/skills/agents-cli-langchain/references/langchain.md +120 -0
  79. core/langchain/template/.agents/skills/agents-cli-langchain/references/samples.md +42 -0
  80. core/langchain/template/.template/templateconfig.yaml +32 -0
  81. core/langchain/template/AGENTS.md +35 -0
  82. core/langchain/template/agents-cli-extension.yaml +54 -0
  83. core/langchain/template/app/__init__.py +19 -0
  84. core/langchain/template/app/agent.py +61 -0
  85. core/langchain/template/app/app_utils/a2a.py +176 -0
  86. core/langchain/template/app/app_utils/content.py +37 -0
  87. core/langchain/template/app/app_utils/telemetry.py +154 -0
  88. core/langchain/template/app/fast_api_app.py +68 -0
  89. core/langchain/template/langgraph.json +7 -0
  90. core/langchain/template/pyproject.toml +102 -0
  91. core/langchain/template/scripts/_content.py +40 -0
  92. core/langchain/template/scripts/eval_generate.py +202 -0
  93. core/langchain/template/scripts/publish.py +59 -0
  94. core/langchain/template/scripts/run.py +59 -0
  95. core/langchain/template/scripts/unsupported.py +48 -0
  96. core/langchain/template/tests/eval/datasets/basic-dataset.json +16 -0
  97. core/langchain/template/tests/eval/eval_config.yaml +32 -0
  98. core/langchain/template/tests/eval/response_quality.py +60 -0
  99. core/langchain/template/tests/integration/test_server_e2e.py +173 -0
  100. core/langchain/template/tests/load_test/.results/.placeholder +0 -0
  101. core/langchain/template/tests/load_test/README.md +20 -0
  102. core/langchain/template/tests/load_test/load_test.py +82 -0
  103. core/langchain/template/uv.lock +3820 -0
  104. google_agents_cli_extensions-1.14.2.dist-info/METADATA +133 -0
  105. google_agents_cli_extensions-1.14.2.dist-info/RECORD +107 -0
  106. google_agents_cli_extensions-1.14.2.dist-info/WHEEL +4 -0
  107. google_agents_cli_extensions-1.14.2.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,991 @@
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
+ """What `app/app_utils/telemetry/` exports, and what it keeps out of spans."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import concurrent.futures
20
+ import dataclasses
21
+ import gzip
22
+ import logging
23
+ import threading
24
+ import urllib.error
25
+ import urllib.request
26
+ from dataclasses import dataclass
27
+ from http.server import BaseHTTPRequestHandler, HTTPServer, ThreadingHTTPServer
28
+ from unittest.mock import MagicMock, patch
29
+
30
+ import pytest
31
+ import requests
32
+ from claude_agent_sdk import AssistantMessage, StreamEvent, TextBlock, ToolUseBlock
33
+ from fastapi import FastAPI
34
+ from fastapi.testclient import TestClient
35
+ from google.auth.credentials import AnonymousCredentials
36
+ from openinference.instrumentation import OITracer, get_tool_attributes
37
+ from openinference.semconv.trace import OpenInferenceSpanKindValues
38
+ from opentelemetry import propagate, trace
39
+ from opentelemetry._logs import LogRecord, SeverityNumber
40
+ from opentelemetry.sdk._logs.export import InMemoryLogRecordExporter
41
+ from opentelemetry.sdk.metrics.export import MetricExporter, MetricExportResult
42
+ from opentelemetry.sdk.trace import TracerProvider
43
+ from opentelemetry.sdk.trace.export import SimpleSpanProcessor
44
+ from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
45
+ InMemorySpanExporter,
46
+ )
47
+
48
+ from app.app_utils import settings, telemetry
49
+ from app.app_utils.telemetry import (
50
+ cli_relay,
51
+ config,
52
+ logs,
53
+ metrics,
54
+ request_flush,
55
+ traces,
56
+ )
57
+ from app.app_utils.telemetry.call_counts import CallCounts
58
+ from app.app_utils.turn_events import TurnEnded, TurnParser
59
+
60
+ _ENV_VARS = (
61
+ "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY",
62
+ "GOOGLE_CLOUD_PROJECT",
63
+ "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT",
64
+ "OTEL_RESOURCE_ATTRIBUTES",
65
+ "OTEL_SERVICE_NAME",
66
+ "K_SERVICE",
67
+ "GOOGLE_CLOUD_AGENT_ENGINE_ID",
68
+ "GOOGLE_CLOUD_AGENT_ENGINE_LOCATION",
69
+ "GOOGLE_CLOUD_AGENT_ENGINE_RUNTIME_REVISION_ID",
70
+ "GOOGLE_CLOUD_LOCATION",
71
+ "GCP_DEFAULT_LOG_NAME",
72
+ "OTEL_TRACES_SAMPLER",
73
+ "OTEL_LOG_USER_PROMPTS",
74
+ "OPENINFERENCE_ENABLE_GENAI_SEMCONV",
75
+ "OPENINFERENCE_HIDE_INPUTS",
76
+ "OPENINFERENCE_HIDE_OUTPUTS",
77
+ *cli_relay._USER_CLI_TELEMETRY_VARS,
78
+ )
79
+
80
+
81
+ @pytest.fixture(autouse=True)
82
+ def _clean(monkeypatch):
83
+ for var in _ENV_VARS:
84
+ monkeypatch.delenv(var, raising=False)
85
+ for module, name, value in (
86
+ (telemetry, "_initialized", False),
87
+ (cli_relay, "_cli_export", None),
88
+ (metrics, "_instruments", None),
89
+ (request_flush, "_request_flush", None),
90
+ (logs, "_logger_provider", None),
91
+ (metrics, "_metrics_failing", False),
92
+ (request_flush, "_last_collect", float("-inf")),
93
+ ):
94
+ monkeypatch.setattr(module, name, value)
95
+ # Keep a developer's .env, and a workstation's client certificate, out of
96
+ # the tests.
97
+ monkeypatch.setattr(telemetry, "load_dotenv", lambda: None)
98
+ monkeypatch.setenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false")
99
+ # setup_telemetry() adds handlers to these loggers.
100
+ loggers = [logging.getLogger(), logging.getLogger("uvicorn")]
101
+ handlers = [list(logger.handlers) for logger in loggers]
102
+ yield
103
+ for logger, saved in zip(loggers, handlers, strict=True):
104
+ logger.handlers[:] = saved
105
+
106
+
107
+ class _CapturedMetrics(MetricExporter):
108
+ """Keeps what a metric export would have sent; can be told to fail."""
109
+
110
+ def __init__(self):
111
+ super().__init__()
112
+ self.batches: list = []
113
+ self.fail: str | None = None
114
+
115
+ def export(self, metrics_data, timeout_millis=10_000, **kwargs):
116
+ if self.fail == "raise":
117
+ raise ConnectionError("telemetry.googleapis.com unreachable")
118
+ if self.fail == "reject":
119
+ return MetricExportResult.FAILURE
120
+ self.batches.append(metrics_data)
121
+ return MetricExportResult.SUCCESS
122
+
123
+ def force_flush(self, timeout_millis=10_000):
124
+ return True
125
+
126
+ def shutdown(self, timeout_millis=30_000, **kwargs):
127
+ pass
128
+
129
+ def points(self, name: str) -> list:
130
+ """(attributes, data point) for each point of metric `name`, last batch."""
131
+ return [
132
+ (dict(point.attributes), point)
133
+ for resource in self.batches[-1].resource_metrics
134
+ for scope in resource.scope_metrics
135
+ for metric in scope.metrics
136
+ if metric.name == name
137
+ for point in metric.data.data_points
138
+ ]
139
+
140
+
141
+ @dataclass
142
+ class _Cloud:
143
+ """The Cloud Logging and Cloud Monitoring exporters setup_telemetry() made."""
144
+
145
+ log_exporter: MagicMock
146
+ logs: InMemoryLogRecordExporter
147
+ metric_exporter: MagicMock
148
+ metrics: _CapturedMetrics
149
+ meter_providers: list
150
+
151
+ def flush_logs(self):
152
+ for handler in logging.getLogger().handlers:
153
+ handler.flush()
154
+ return self.logs.get_finished_logs()
155
+
156
+ def flush_metrics(self):
157
+ [provider] = self.meter_providers
158
+ provider.force_flush()
159
+ return self.metrics
160
+
161
+
162
+ @pytest.fixture(autouse=True)
163
+ def cloud(monkeypatch):
164
+ cloud = _Cloud(
165
+ log_exporter=MagicMock(),
166
+ logs=InMemoryLogRecordExporter(),
167
+ metric_exporter=MagicMock(),
168
+ metrics=_CapturedMetrics(),
169
+ meter_providers=[],
170
+ )
171
+ cloud.log_exporter.return_value = cloud.logs
172
+ cloud.metric_exporter.return_value = cloud.metrics
173
+ monkeypatch.setattr(
174
+ "opentelemetry.exporter.otlp.proto.http._log_exporter.OTLPLogExporter",
175
+ cloud.log_exporter,
176
+ )
177
+ monkeypatch.setattr(
178
+ "opentelemetry.exporter.otlp.proto.http.metric_exporter.OTLPMetricExporter",
179
+ cloud.metric_exporter,
180
+ )
181
+ monkeypatch.setattr(
182
+ "opentelemetry.metrics.set_meter_provider", cloud.meter_providers.append
183
+ )
184
+ yield cloud
185
+ # Rather than at exit, where a provider's final export would still run.
186
+ cloud.metrics.fail = None
187
+ for provider in cloud.meter_providers:
188
+ provider.shutdown()
189
+
190
+
191
+ @pytest.fixture
192
+ def setup(monkeypatch):
193
+ """setup_telemetry() with fake ADC and no global side effects.
194
+
195
+ Returns the mocked OTLP exporter class and the tracer provider that would
196
+ have been installed (None if none was).
197
+ """
198
+
199
+ @patch(
200
+ "openinference.instrumentation.claude_agent_sdk.ClaudeAgentSDKInstrumentor.instrument"
201
+ )
202
+ @patch("opentelemetry.trace.set_tracer_provider")
203
+ @patch("opentelemetry.exporter.otlp.proto.http.trace_exporter.OTLPSpanExporter")
204
+ @patch("google.auth.default")
205
+ def run(adc_project, auth, exporter, set_provider, instrument):
206
+ auth.return_value = (AnonymousCredentials(), adc_project)
207
+ telemetry.setup_telemetry()
208
+ provider = set_provider.call_args.args[0] if set_provider.called else None
209
+ return exporter, provider
210
+
211
+ return lambda adc_project="adc-project": run(adc_project)
212
+
213
+
214
+ def _finished_spans(provider: TracerProvider, *starts: dict) -> list:
215
+ """End one span per attribute set; return them as exported.
216
+
217
+ Spans with an OpenInference span kind go through OpenInference's tracer.
218
+ """
219
+ memory = InMemorySpanExporter()
220
+ provider.add_span_processor(SimpleSpanProcessor(memory))
221
+ plain = provider.get_tracer(__name__)
222
+ openinference = OITracer(plain, config=traces._trace_config())
223
+ for attributes in starts:
224
+ oi = "openinference.span.kind" in attributes
225
+ (openinference if oi else plain).start_span("span", attributes=attributes).end()
226
+ return [dict(span.attributes or {}) for span in memory.get_finished_spans()]
227
+
228
+
229
+ def test_server_spans_go_over_otlp_with_their_resource(setup, monkeypatch):
230
+ monkeypatch.setenv("GOOGLE_CLOUD_PROJECT", "my-project")
231
+ monkeypatch.setenv("K_SERVICE", "weather-agent")
232
+ exporter, provider = setup()
233
+
234
+ kwargs = exporter.call_args.kwargs
235
+ assert kwargs["endpoint"] == "https://telemetry.googleapis.com/v1/traces"
236
+ assert isinstance(kwargs["session"], requests.Session)
237
+ resource = provider.resource.attributes
238
+ assert resource["service.name"] == "weather-agent"
239
+ # The Telemetry API rejects spans without it.
240
+ assert resource["gcp.project_id"] == "my-project"
241
+ assert resource["service.instance.id"]
242
+
243
+
244
+ _ENGINE = "//aiplatform.googleapis.com/projects/137/locations/us-central1/reasoningEngines/123"
245
+
246
+
247
+ @pytest.mark.parametrize(
248
+ ("env", "service_name", "resource_id"),
249
+ [
250
+ ({"GOOGLE_CLOUD_AGENT_ENGINE_LOCATION": "us-central1"}, "123", _ENGINE),
251
+ (
252
+ {
253
+ "GOOGLE_CLOUD_AGENT_ENGINE_LOCATION": "us-central1",
254
+ "OTEL_SERVICE_NAME": "weather-agent",
255
+ },
256
+ "weather-agent",
257
+ _ENGINE,
258
+ ),
259
+ # Without a location the engine can't be named.
260
+ ({}, "123", None),
261
+ ],
262
+ )
263
+ def test_on_agent_runtime_spans_name_the_engine(
264
+ setup, monkeypatch, env, service_name, resource_id
265
+ ):
266
+ """The Agent Runtime console finds an engine's traces by cloud.resource_id."""
267
+ monkeypatch.setenv("GOOGLE_CLOUD_PROJECT", "137")
268
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", "123")
269
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_RUNTIME_REVISION_ID", "7")
270
+ for var, value in env.items():
271
+ monkeypatch.setenv(var, value)
272
+ _, provider = setup()
273
+
274
+ resource = provider.resource.attributes
275
+ assert resource.get("cloud.resource_id") == resource_id
276
+ assert resource["cloud.platform"] == "gcp.agent_engine"
277
+ assert resource["service.name"] == service_name
278
+ assert resource["service.version"] == "7"
279
+ assert resource["gcp.project_id"] == "137"
280
+
281
+
282
+ def test_with_a_client_certificate_spans_go_over_mtls(setup, monkeypatch):
283
+ """Agent Identity tokens are bound to its certificate: only mTLS takes them."""
284
+ monkeypatch.setenv("GOOGLE_API_USE_CLIENT_CERTIFICATE", "true")
285
+
286
+ def configure_mtls_channel(self, client_cert_callback=None):
287
+ self._is_mtls = True
288
+
289
+ with patch(
290
+ "google.auth.transport.requests.AuthorizedSession.configure_mtls_channel",
291
+ configure_mtls_channel,
292
+ ):
293
+ exporter, _ = setup()
294
+
295
+ kwargs = exporter.call_args.kwargs
296
+ assert kwargs["endpoint"] == "https://telemetry.mtls.googleapis.com/v1/traces"
297
+ assert kwargs["session"].is_mtls
298
+
299
+
300
+ def test_without_a_project_nothing_is_exported(setup, cloud):
301
+ exporter, provider = setup(adc_project=None)
302
+ exporter.assert_not_called()
303
+ assert provider is None
304
+ assert telemetry.cli_telemetry_env() == {}
305
+ cloud.log_exporter.assert_not_called()
306
+ assert cloud.meter_providers == []
307
+
308
+
309
+ def test_agent_spans_carry_the_agent_name_setting(setup, monkeypatch):
310
+ monkeypatch.setattr(settings, "AGENT_NAME", "weather_agent")
311
+ _, provider = setup()
312
+ agent, tool, subagent, other = _finished_spans(
313
+ provider,
314
+ {"openinference.span.kind": "AGENT"},
315
+ {"openinference.span.kind": "TOOL"},
316
+ {"openinference.span.kind": "AGENT", "agent.name": "Task"},
317
+ {"mcp.method.name": "tools/list"},
318
+ )
319
+ for span in (agent, tool):
320
+ assert span["gen_ai.agent.name"] == "weather_agent"
321
+ # A subagent's span keeps naming the subagent.
322
+ assert subagent["gen_ai.agent.name"] == "Task"
323
+ assert "gen_ai.agent.name" not in other
324
+
325
+
326
+ def test_mcp_and_bigquery_client_spans_are_not_recorded(setup):
327
+ """The MCP SDK's duplicate OpenInference's tool spans; BigQuery's are noise.
328
+
329
+ A span started under one, like an A2A call from a tool, keeps the enclosing
330
+ span as its parent rather than pointing at a span that was never exported.
331
+ """
332
+ exporter, provider = setup()
333
+ tracer = provider.get_tracer("openinference.instrumentation.claude_agent_sdk")
334
+ with tracer.start_as_current_span("execute_tool") as tool:
335
+ for scope in ("mcp-python-sdk", "google.cloud.bigquery.opentelemetry_tracing"):
336
+ with provider.get_tracer(scope).start_as_current_span(scope):
337
+ provider.get_tracer("a2a-python-sdk").start_span("a2a call").end()
338
+ provider.force_flush()
339
+
340
+ exported = [
341
+ span
342
+ for call in exporter.return_value.export.call_args_list
343
+ for span in call.args[0]
344
+ ]
345
+ assert sorted(span.name for span in exported) == [
346
+ "a2a call",
347
+ "a2a call",
348
+ "execute_tool",
349
+ ]
350
+ tool_id = tool.get_span_context().span_id
351
+ assert all(s.parent.span_id == tool_id for s in exported if s.name == "a2a call")
352
+
353
+
354
+ def test_an_unrendered_agent_name_falls_back_to_the_service_name(setup, monkeypatch):
355
+ monkeypatch.setattr(settings, "AGENT_NAME", "{{cookiecutter.root_agent_name}}")
356
+ monkeypatch.setenv("OTEL_SERVICE_NAME", "weather-agent")
357
+ _, provider = setup()
358
+ [agent] = _finished_spans(provider, {"openinference.span.kind": "AGENT"})
359
+ assert agent["gen_ai.agent.name"] == "weather-agent"
360
+
361
+
362
+ def test_cli_exports_to_the_forwarder_without_content(setup, monkeypatch):
363
+ monkeypatch.setenv("GOOGLE_CLOUD_PROJECT", "my-project")
364
+ monkeypatch.setenv("OTEL_RESOURCE_ATTRIBUTES", "team=agents")
365
+ setup()
366
+
367
+ env = telemetry.cli_telemetry_env()
368
+ assert env["OTEL_EXPORTER_OTLP_ENDPOINT"].startswith("http://127.0.0.1:")
369
+ assert env["OTEL_EXPORTER_OTLP_PROTOCOL"] == "http/protobuf"
370
+ assert env["OTEL_TRACES_EXPORTER"] == "otlp"
371
+ assert env["CLAUDE_CODE_ENHANCED_TELEMETRY_BETA"] == "1"
372
+ assert env["OTEL_METRICS_EXPORTER"] == env["OTEL_LOGS_EXPORTER"] == "none"
373
+ assert env["OTEL_RESOURCE_ATTRIBUTES"] == "team=agents,gcp.project_id=my-project"
374
+ assert "OTEL_LOG_USER_PROMPTS" not in env
375
+
376
+
377
+ def test_cli_spans_carry_the_cloud_run_service_name(setup, monkeypatch):
378
+ monkeypatch.setenv("K_SERVICE", "weather-agent")
379
+ setup()
380
+
381
+ assert telemetry.cli_telemetry_env()["OTEL_SERVICE_NAME"] == "weather-agent"
382
+
383
+
384
+ def test_on_agent_runtime_cli_spans_name_the_engine(setup, monkeypatch):
385
+ monkeypatch.setenv("GOOGLE_CLOUD_PROJECT", "137")
386
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", "123")
387
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION", "us-central1")
388
+ monkeypatch.setenv("K_SERVICE", "reasoning-engine-123")
389
+ setup()
390
+
391
+ env = telemetry.cli_telemetry_env()
392
+ assert env["OTEL_SERVICE_NAME"] == "123"
393
+ assert env["OTEL_RESOURCE_ATTRIBUTES"] == (
394
+ "cloud.provider=gcp,cloud.platform=gcp.agent_engine,"
395
+ f"cloud.region=us-central1,cloud.resource_id={_ENGINE},gcp.project_id=137"
396
+ )
397
+
398
+
399
+ def test_capture_on_logs_cli_content(setup, monkeypatch):
400
+ monkeypatch.setenv("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "true")
401
+ setup()
402
+ env = telemetry.cli_telemetry_env()
403
+ assert env["OTEL_LOG_USER_PROMPTS"] == "1"
404
+ assert env["OTEL_LOG_TOOL_DETAILS"] == "1"
405
+ # The ADC project when GOOGLE_CLOUD_PROJECT is unset.
406
+ assert env["OTEL_RESOURCE_ATTRIBUTES"] == "gcp.project_id=adc-project"
407
+
408
+
409
+ def test_switch_off_exports_nothing(setup, cloud, monkeypatch):
410
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY", "false")
411
+ exporter, _ = setup()
412
+ exporter.assert_not_called()
413
+ assert telemetry.cli_telemetry_env() == {}
414
+ cloud.log_exporter.assert_not_called()
415
+ cloud.metric_exporter.assert_not_called()
416
+ assert cloud.meter_providers == []
417
+
418
+
419
+ def test_spans_under_an_unsampled_traceparent_are_recorded(setup):
420
+ """Cloud Run's and Agent Runtime's front ends mark their traceparent not sampled."""
421
+ _, provider = setup()
422
+ parent = propagate.extract(
423
+ {"traceparent": "00-00000000000000002e9787a365705b7c-1111111111111111-00"}
424
+ )
425
+ tracer = OITracer(provider.get_tracer(__name__), config=traces._trace_config())
426
+ span = tracer.start_span(
427
+ "turn",
428
+ context=parent,
429
+ openinference_span_kind=OpenInferenceSpanKindValues.AGENT,
430
+ )
431
+ assert span.is_recording()
432
+ span.end()
433
+
434
+
435
+ def test_a_turn_the_users_sampler_drops_ends_cleanly_unexported(setup, monkeypatch):
436
+ monkeypatch.setenv("OTEL_TRACES_SAMPLER", "always_off")
437
+ exporter, provider = setup()
438
+ tracer = OITracer(
439
+ provider.get_tracer("openinference.instrumentation.claude_agent_sdk"),
440
+ config=traces._trace_config(),
441
+ )
442
+ tracer.start_span(
443
+ "turn", openinference_span_kind=OpenInferenceSpanKindValues.AGENT
444
+ ).end()
445
+ provider.force_flush()
446
+ exporter.return_value.export.assert_not_called()
447
+
448
+
449
+ def test_with_export_off_an_agent_span_ends_cleanly(setup, monkeypatch):
450
+ """With no tracer provider every span is non-recording; ending one must not raise."""
451
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY", "false")
452
+ setup()
453
+ tracer = OITracer(trace.NoOpTracer(), config=traces._trace_config())
454
+ tracer.start_span(
455
+ "turn", openinference_span_kind=OpenInferenceSpanKindValues.AGENT
456
+ ).end()
457
+
458
+
459
+ def test_users_own_cli_telemetry_wins(setup, monkeypatch):
460
+ monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://collector:4318")
461
+ exporter, _ = setup()
462
+ exporter.assert_called_once()
463
+ assert telemetry.cli_telemetry_env() == {}
464
+
465
+
466
+ class _Upstream:
467
+ """A fake Telemetry API that records what it receives."""
468
+
469
+ def __init__(self, status: int = 200):
470
+ self.requests: list[tuple[str, dict[str, str], bytes]] = []
471
+ self.status = status
472
+ upstream = self
473
+
474
+ class Handler(BaseHTTPRequestHandler):
475
+ def do_POST(self):
476
+ body = self.rfile.read(int(self.headers["Content-Length"]))
477
+ upstream.requests.append((self.path, dict(self.headers), body))
478
+ self.send_response(upstream.status)
479
+ self.send_header("Content-Length", "0")
480
+ self.end_headers()
481
+
482
+ def log_message(self, format, *args):
483
+ pass
484
+
485
+ self._server = HTTPServer(("127.0.0.1", 0), Handler)
486
+ threading.Thread(target=self._server.serve_forever, daemon=True).start()
487
+ self.url = f"http://127.0.0.1:{self._server.server_port}"
488
+
489
+ def close(self):
490
+ self._server.shutdown()
491
+ self._server.server_close()
492
+
493
+
494
+ @pytest.fixture
495
+ def upstream():
496
+ servers: list[_Upstream] = []
497
+
498
+ def make(status: int = 200) -> _Upstream:
499
+ servers.append(_Upstream(status))
500
+ return servers[-1]
501
+
502
+ yield make
503
+ for server in servers:
504
+ server.close()
505
+
506
+
507
+ def _post(url: str, body: bytes) -> int:
508
+ request = urllib.request.Request(
509
+ url, data=body, headers={"Content-Type": "application/x-protobuf"}
510
+ )
511
+ try:
512
+ with urllib.request.urlopen(request, timeout=5) as response:
513
+ return response.status
514
+ except urllib.error.HTTPError as e:
515
+ return e.code
516
+
517
+
518
+ def test_forwarder_relays_traces_unchanged(upstream):
519
+ fake = upstream()
520
+ endpoint = cli_relay.start_trace_forwarder(lambda: (requests.Session(), fake.url))
521
+
522
+ assert _post(f"{endpoint}/v1/traces", b"\x0a\x01spans") == 200
523
+ [(path, headers, body)] = fake.requests
524
+ assert path == "/v1/traces"
525
+ assert body == b"\x0a\x01spans"
526
+ assert headers["Content-Type"] == "application/x-protobuf"
527
+
528
+
529
+ def _cli_llm_span_export(model: str = "claude-haiku-4-5", **counts: int) -> bytes:
530
+ from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
531
+ ExportTraceServiceRequest,
532
+ )
533
+ from opentelemetry.proto.common.v1.common_pb2 import AnyValue, KeyValue
534
+
535
+ request = ExportTraceServiceRequest()
536
+ scope = request.resource_spans.add().scope_spans.add()
537
+ scope.spans.add(name="claude_code.tool")
538
+ span = scope.spans.add(name="claude_code.llm_request")
539
+ span.attributes.append(KeyValue(key="model", value=AnyValue(string_value=model)))
540
+ span.attributes.extend(
541
+ KeyValue(key=k, value=AnyValue(int_value=v)) for k, v in counts.items()
542
+ )
543
+ return request.SerializeToString()
544
+
545
+
546
+ def _span_attributes(body: bytes, name: str) -> dict:
547
+ from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
548
+ ExportTraceServiceRequest,
549
+ )
550
+
551
+ request = ExportTraceServiceRequest.FromString(body)
552
+ [span] = [
553
+ s
554
+ for rs in request.resource_spans
555
+ for ss in rs.scope_spans
556
+ for s in ss.spans
557
+ if s.name == name
558
+ ]
559
+ return {
560
+ kv.key: kv.value.int_value or kv.value.string_value for kv in span.attributes
561
+ }
562
+
563
+
564
+ @pytest.mark.parametrize("compress", [False, True])
565
+ def test_forwarder_adds_adk_style_usage_to_cli_model_calls(upstream, compress):
566
+ fake = upstream()
567
+ endpoint = cli_relay.start_trace_forwarder(lambda: (requests.Session(), fake.url))
568
+ body = _cli_llm_span_export(
569
+ input_tokens=100, output_tokens=7, cache_read_tokens=20, cache_creation_tokens=5
570
+ )
571
+ request = urllib.request.Request(
572
+ f"{endpoint}/v1/traces",
573
+ data=gzip.compress(body) if compress else body,
574
+ headers={
575
+ "Content-Type": "application/x-protobuf",
576
+ **({"Content-Encoding": "gzip"} if compress else {}),
577
+ },
578
+ )
579
+ with urllib.request.urlopen(request, timeout=5) as response:
580
+ assert response.status == 200
581
+
582
+ [(_, headers, forwarded)] = fake.requests
583
+ assert "Content-Encoding" not in headers
584
+ attributes = _span_attributes(forwarded, "claude_code.llm_request")
585
+ # Cache tokens fold into the input count.
586
+ assert attributes["gen_ai.usage.input_tokens"] == 125
587
+ assert attributes["gen_ai.usage.output_tokens"] == 7
588
+ assert attributes["gen_ai.usage.cache_read.input_tokens"] == 20
589
+ assert attributes["gen_ai.usage.cache_creation.input_tokens"] == 5
590
+ assert attributes["gen_ai.operation.name"] == "generate_content"
591
+ assert attributes["input_tokens"] == 100 # the CLI's own names stay
592
+ assert "gen_ai.usage.input_tokens" not in _span_attributes(
593
+ forwarded, "claude_code.tool"
594
+ )
595
+
596
+
597
+ def test_forwarder_relays_concurrent_exports_at_once():
598
+ # Answers only once two exports are in flight together.
599
+ both_in_flight = threading.Barrier(2, timeout=2)
600
+
601
+ class Handler(BaseHTTPRequestHandler):
602
+ def do_POST(self):
603
+ self.rfile.read(int(self.headers["Content-Length"]))
604
+ try:
605
+ both_in_flight.wait()
606
+ status = 200
607
+ except threading.BrokenBarrierError:
608
+ status = 500
609
+ self.send_response(status)
610
+ self.send_header("Content-Length", "0")
611
+ self.end_headers()
612
+
613
+ def log_message(self, format, *args):
614
+ pass
615
+
616
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
617
+ threading.Thread(target=server.serve_forever, daemon=True).start()
618
+ url = f"http://127.0.0.1:{server.server_port}"
619
+ sessions: list[requests.Session] = []
620
+
621
+ def new_session():
622
+ sessions.append(requests.Session())
623
+ return sessions[-1], url
624
+
625
+ try:
626
+ endpoint = cli_relay.start_trace_forwarder(new_session)
627
+ with concurrent.futures.ThreadPoolExecutor(2) as pool:
628
+ statuses = list(
629
+ pool.map(lambda _: _post(f"{endpoint}/v1/traces", b"x"), range(2))
630
+ )
631
+ finally:
632
+ server.shutdown()
633
+ server.server_close()
634
+ assert statuses == [200, 200]
635
+ # Each request had a session of its own.
636
+ assert len(sessions) == 2
637
+
638
+
639
+ def test_forwarder_relays_rejections_and_only_forwards_traces(upstream):
640
+ fake = upstream(status=400)
641
+ endpoint = cli_relay.start_trace_forwarder(lambda: (requests.Session(), fake.url))
642
+
643
+ assert _post(f"{endpoint}/v1/traces", b"x") == 400
644
+ assert _post(f"{endpoint}/v1/metrics", b"x") == 404
645
+ assert [path for path, _, _ in fake.requests] == ["/v1/traces"]
646
+
647
+
648
+ def _tool_span_attributes() -> dict:
649
+ exporter = InMemorySpanExporter()
650
+ provider = TracerProvider()
651
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
652
+ tracer = OITracer(provider.get_tracer(__name__), config=traces._trace_config())
653
+ span = tracer.start_span(
654
+ "get_weather",
655
+ openinference_span_kind=OpenInferenceSpanKindValues.TOOL,
656
+ attributes=get_tool_attributes(
657
+ name="get_weather", parameters={"city": "San Francisco"}
658
+ ),
659
+ )
660
+ span.end()
661
+ [finished] = exporter.get_finished_spans()
662
+ return dict(finished.attributes or {})
663
+
664
+
665
+ def test_tool_arguments_are_redacted_by_default():
666
+ attributes = _tool_span_attributes()
667
+ assert attributes["tool.parameters"] == "__REDACTED__"
668
+ assert attributes["gen_ai.tool.name"] == "get_weather"
669
+ assert not any("San Francisco" in str(v) for v in attributes.values())
670
+
671
+
672
+ def test_tool_arguments_are_kept_when_capture_is_on(monkeypatch):
673
+ monkeypatch.setenv("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "true")
674
+ attributes = _tool_span_attributes()
675
+ assert "San Francisco" in attributes["tool.parameters"]
676
+ assert "San Francisco" in attributes["gen_ai.tool.call.arguments"]
677
+
678
+
679
+ @pytest.mark.parametrize(
680
+ ("env", "log_name", "resource_type"),
681
+ [
682
+ ({}, "adk-otel", None),
683
+ (
684
+ {
685
+ "GOOGLE_CLOUD_AGENT_ENGINE_ID": "123",
686
+ "GOOGLE_CLOUD_AGENT_ENGINE_LOCATION": "us-central1",
687
+ },
688
+ "aiplatform.googleapis.com/reasoning_engine_stdout",
689
+ "aiplatform.googleapis.com/ReasoningEngine",
690
+ ),
691
+ ({"GCP_DEFAULT_LOG_NAME": "my-agent"}, "my-agent", None),
692
+ ],
693
+ )
694
+ def test_log_records_go_to_cloud_logging_under_the_active_span(
695
+ setup, cloud, monkeypatch, env, log_name, resource_type
696
+ ):
697
+ for var, value in env.items():
698
+ monkeypatch.setenv(var, value)
699
+ monkeypatch.setenv("GOOGLE_CLOUD_PROJECT", "my-project")
700
+ _, provider = setup()
701
+
702
+ with provider.get_tracer(__name__).start_as_current_span("turn") as span:
703
+ try:
704
+ raise TimeoutError("model call timed out")
705
+ except TimeoutError:
706
+ logging.getLogger("app.test").exception(
707
+ "Turn failed: %s", "boom", extra={"prompt": "secret"}
708
+ )
709
+ [record] = cloud.flush_logs()
710
+
711
+ log = record.log_record
712
+ assert log.severity_number == SeverityNumber.ERROR
713
+ assert log.severity_text == "ERROR"
714
+ assert log.trace_id == span.get_span_context().trace_id
715
+ assert log.span_id == span.get_span_context().span_id
716
+ assert str(log.body).startswith("Turn failed: boom\nTraceback")
717
+ assert log.attributes["exception.type"] == "TimeoutError"
718
+ assert log.attributes["gcp.log_name"] == log_name
719
+ # Fields a caller attaches to a record don't leave the process.
720
+ assert "secret" not in str(dict(log.attributes))
721
+ assert record.resource.attributes.get("gcp.resource_type") == resource_type
722
+ # The span-only Agent Runtime attributes would remap the records.
723
+ assert "cloud.resource_id" not in record.resource.attributes
724
+ if resource_type:
725
+ assert record.resource.attributes["reasoning_engine_id"] == "123"
726
+ assert record.resource.attributes["location"] == "us-central1"
727
+ assert record.resource.attributes["resource_container"] == (
728
+ "projects/my-project"
729
+ )
730
+ endpoint = cloud.log_exporter.call_args.kwargs["endpoint"]
731
+ assert endpoint == "https://telemetry.googleapis.com/v1/logs"
732
+
733
+
734
+ @pytest.mark.parametrize(
735
+ ("env", "log_name"),
736
+ [
737
+ ({}, "gen_ai.client.inference.operation.details"),
738
+ (
739
+ {"GOOGLE_CLOUD_AGENT_ENGINE_ID": "123"},
740
+ "aiplatform.googleapis.com/reasoning_engine_stdout",
741
+ ),
742
+ ],
743
+ )
744
+ def test_genai_events_go_where_adk_puts_them(setup, cloud, monkeypatch, env, log_name):
745
+ for var, value in env.items():
746
+ monkeypatch.setenv(var, value)
747
+ event = {"event.name": "gen_ai.client.inference.operation.details"}
748
+ # Before setup there is nowhere to send them.
749
+ telemetry.emit_event(LogRecord(attributes={**event, "a": "1"}))
750
+ setup()
751
+ telemetry.emit_event(LogRecord(attributes={**event, "a": "2"}))
752
+ [record] = cloud.flush_logs()
753
+
754
+ assert record.log_record.attributes["a"] == "2"
755
+ assert record.log_record.attributes["gcp.log_name"] == log_name
756
+
757
+
758
+ def test_log_records_still_print_to_stderr(setup, monkeypatch, capsys):
759
+ """Python prints to stderr only while the root logger has no handler."""
760
+ monkeypatch.setattr(logging.getLogger(), "handlers", [])
761
+ setup()
762
+ logging.getLogger("app.test").warning("Tool call denied.")
763
+ assert "Tool call denied." in capsys.readouterr().err
764
+
765
+
766
+ def test_uvicorn_server_logs_reach_cloud_logging(setup, cloud, monkeypatch):
767
+ # As uvicorn configures its loggers before it imports the app.
768
+ monkeypatch.setattr(logging.getLogger("uvicorn"), "propagate", False)
769
+ setup()
770
+ logging.getLogger("uvicorn.error").warning("Invalid HTTP request received.")
771
+ [record] = cloud.flush_logs()
772
+ assert record.log_record.severity_number == SeverityNumber.WARN
773
+ assert record.log_record.body == "Invalid HTTP request received."
774
+
775
+
776
+ def _messages() -> list:
777
+ """A turn with two model calls; the second delegates to a subagent (Task),
778
+ which makes two of its own."""
779
+
780
+ def message(message_id, *content, parent=None):
781
+ return AssistantMessage(
782
+ content=list(content),
783
+ model="claude-haiku-4-5",
784
+ message_id=message_id,
785
+ parent_tool_use_id=parent,
786
+ )
787
+
788
+ def stream(kind):
789
+ return StreamEvent(uuid="u", session_id="s", event={"type": kind})
790
+
791
+ return [
792
+ stream("message_start"),
793
+ message("m1", ToolUseBlock(id="t1", name="get_weather", input={})),
794
+ message("m1", TextBlock(text="Checking.")), # the same model call
795
+ stream("message_stop"),
796
+ stream("message_start"),
797
+ message("m2", ToolUseBlock(id="t2", name="Task", input={})),
798
+ stream("message_stop"),
799
+ message("m3", ToolUseBlock(id="t3", name="Bash", input={}), parent="t2"),
800
+ message("m4", TextBlock(text="Done."), parent="t2"),
801
+ ]
802
+
803
+
804
+ def _count_calls(messages: list) -> None:
805
+ """Record a turn's call counts, as stream_turn does."""
806
+ parser = TurnParser(config.agent_name())
807
+ calls = CallCounts(parser.agent_name)
808
+ for message in messages:
809
+ for event in parser.feed(message):
810
+ calls.handle(event)
811
+ for event in parser.finish():
812
+ calls.handle(event)
813
+
814
+
815
+ def test_a_turn_records_adk_metrics(setup, cloud, monkeypatch):
816
+ monkeypatch.setattr(settings, "AGENT_NAME", "weather_agent")
817
+ _, provider = setup()
818
+ tracer = OITracer(provider.get_tracer(__name__), config=traces._trace_config())
819
+ with tracer.start_as_current_span(
820
+ "turn", openinference_span_kind=OpenInferenceSpanKindValues.AGENT
821
+ ):
822
+ tracer.start_span(
823
+ "get_weather",
824
+ openinference_span_kind=OpenInferenceSpanKindValues.TOOL,
825
+ attributes=get_tool_attributes(name="get_weather", parameters={}),
826
+ ).end()
827
+ _count_calls(_messages())
828
+
829
+ exported = cloud.flush_metrics()
830
+ [(attributes, turn)] = exported.points("gen_ai.invoke_agent.duration")
831
+ assert attributes == {
832
+ "gen_ai.agent.name": "weather_agent",
833
+ "gen_ai.operation.name": "invoke_agent",
834
+ }
835
+ assert turn.count == 1
836
+ [(attributes, _)] = exported.points("gen_ai.execute_tool.duration")
837
+ assert attributes == {
838
+ "gen_ai.agent.name": "weather_agent",
839
+ "gen_ai.operation.name": "execute_tool",
840
+ "gen_ai.tool.name": "get_weather",
841
+ }
842
+ for name in ("inference_calls", "tool_calls"):
843
+ counts = {
844
+ attributes["gen_ai.agent.name"]: point.sum
845
+ for attributes, point in exported.points(f"gen_ai.invoke_agent.{name}")
846
+ }
847
+ # The Task call is the agent's; the subagent's calls are its own.
848
+ assert counts == {
849
+ "weather_agent": 2,
850
+ "subagent": 2 if name == "inference_calls" else 1,
851
+ }
852
+ endpoint = cloud.metric_exporter.call_args.kwargs["endpoint"]
853
+ assert endpoint == "https://telemetry.googleapis.com/v1/metrics"
854
+
855
+
856
+ def test_a_failed_turn_records_its_error_type(setup, cloud):
857
+ _, provider = setup()
858
+ tracer = OITracer(provider.get_tracer(__name__), config=traces._trace_config())
859
+ span = tracer.start_span(
860
+ "turn", openinference_span_kind=OpenInferenceSpanKindValues.AGENT
861
+ )
862
+ span.record_exception(_ModelUnavailableError("claude-haiku-4-5"))
863
+ span.set_status(trace.Status(trace.StatusCode.ERROR))
864
+ span.end()
865
+
866
+ [(attributes, _)] = cloud.flush_metrics().points("gen_ai.invoke_agent.duration")
867
+ # The class name, not the span's module-qualified one.
868
+ assert attributes["error.type"] == "_ModelUnavailableError"
869
+
870
+
871
+ class _ModelUnavailableError(Exception):
872
+ pass
873
+
874
+
875
+ def test_cli_model_calls_record_token_usage_once(setup, cloud, upstream):
876
+ setup()
877
+ fake = upstream(status=503)
878
+ endpoint = cli_relay.start_trace_forwarder(lambda: (requests.Session(), fake.url))
879
+ body = _cli_llm_span_export(input_tokens=100, output_tokens=7, cache_read_tokens=20)
880
+
881
+ # The CLI resends a batch the Telemetry API turned away for now.
882
+ assert _post(f"{endpoint}/v1/traces", body) == 503
883
+ fake.status = 200
884
+ assert _post(f"{endpoint}/v1/traces", body) == 200
885
+
886
+ points = cloud.flush_metrics().points("gen_ai.client.token.usage")
887
+ tokens = {attrs["gen_ai.token.type"]: (p.count, p.sum) for attrs, p in points}
888
+ assert tokens == {"input": (1, 120), "output": (1, 7)}
889
+ attributes, _ = points[0]
890
+ assert attributes["gen_ai.request.model"] == "claude-haiku-4-5"
891
+ assert attributes["gen_ai.operation.name"] == "generate_content"
892
+
893
+
894
+ def test_a_failing_token_metric_still_relays_the_response(
895
+ setup, cloud, upstream, monkeypatch, caplog
896
+ ):
897
+ setup()
898
+ monkeypatch.setattr(
899
+ metrics,
900
+ "_instruments",
901
+ dataclasses.replace(
902
+ metrics._instruments,
903
+ token_usage=MagicMock(record=MagicMock(side_effect=ValueError("bad"))),
904
+ ),
905
+ )
906
+ endpoint = cli_relay.start_trace_forwarder(
907
+ lambda: (requests.Session(), upstream().url)
908
+ )
909
+
910
+ assert _post(f"{endpoint}/v1/traces", _cli_llm_span_export(input_tokens=1)) == 200
911
+ assert "agent metrics" in caplog.text
912
+
913
+
914
+ def test_without_cloud_export_turns_record_no_metrics(setup, cloud, monkeypatch):
915
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY", "false")
916
+ setup()
917
+ _count_calls(_messages())
918
+ cloud.metric_exporter.assert_not_called()
919
+
920
+
921
+ def _app() -> FastAPI:
922
+ app = FastAPI()
923
+ app.add_middleware(telemetry.FlushTelemetryMiddleware)
924
+
925
+ # Agent turns arrive as POSTs.
926
+ @app.post("/turn")
927
+ def turn() -> dict[str, str]:
928
+ calls = CallCounts(TurnParser(config.agent_name()).agent_name)
929
+ calls.handle(TurnEnded(failed=False, error=None))
930
+ return {"status": "ok"}
931
+
932
+ @app.get("/health")
933
+ def health() -> dict[str, str]:
934
+ calls = CallCounts(TurnParser(config.agent_name()).agent_name)
935
+ calls.handle(TurnEnded(failed=False, error=None))
936
+ return {"status": "ok"}
937
+
938
+ return app
939
+
940
+
941
+ @pytest.mark.parametrize("on_agent_runtime", [True, False])
942
+ def test_agent_runtime_exports_metrics_before_each_response_ends(
943
+ setup, cloud, monkeypatch, on_agent_runtime
944
+ ):
945
+ """Agent Runtime throttles the CPU between requests; elsewhere a periodic
946
+ reader exports in the background."""
947
+ if on_agent_runtime:
948
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", "123")
949
+ setup()
950
+
951
+ client = TestClient(_app())
952
+ assert client.post("/turn").status_code == 200
953
+ assert bool(cloud.metrics.batches) == on_agent_runtime
954
+ if on_agent_runtime:
955
+ assert cloud.metrics.points("gen_ai.invoke_agent.inference_calls")
956
+ # Cloud Monitoring rejects points closer than 5s apart on one series: the
957
+ # next request's points wait for a later collect.
958
+ assert client.post("/turn").status_code == 200
959
+ assert len(cloud.metrics.batches) == int(on_agent_runtime)
960
+
961
+
962
+ def test_reads_like_health_checks_do_not_wait_for_a_flush(setup, cloud, monkeypatch):
963
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", "123")
964
+ setup()
965
+
966
+ assert TestClient(_app()).get("/health").status_code == 200
967
+
968
+ assert not cloud.metrics.batches
969
+
970
+
971
+ def test_a_failing_metrics_export_never_fails_a_request(
972
+ setup, cloud, monkeypatch, caplog
973
+ ):
974
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", "123")
975
+ setup()
976
+ client = TestClient(_app())
977
+
978
+ def turn(fail: str | None) -> None:
979
+ cloud.metrics.fail = fail
980
+ monkeypatch.setattr(request_flush, "_last_collect", float("-inf"))
981
+ assert client.post("/turn").status_code == 200
982
+
983
+ def warnings() -> int:
984
+ return sum("agent metrics" in r.getMessage() for r in caplog.records)
985
+
986
+ turn("raise")
987
+ turn("reject")
988
+ assert warnings() == 1 # once per run of failures
989
+ turn(None)
990
+ turn("reject")
991
+ assert warnings() == 2