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.
- core/claude/README.md +35 -0
- core/claude/template/.agents/skills/agents-cli-claude/SKILL.md +106 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/claude.md +386 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/migrate-claude-agent.md +318 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/migrate-from-aws.md +132 -0
- core/claude/template/.dockerignore +28 -0
- core/claude/template/.env +18 -0
- core/claude/template/.env.example +17 -0
- core/claude/template/.template/templateconfig.yaml +31 -0
- core/claude/template/AGENTS.md +33 -0
- core/claude/template/Dockerfile +55 -0
- core/claude/template/agent_config/README.md +9 -0
- core/claude/template/agents-cli-extension.yaml +49 -0
- core/claude/template/app/__init__.py +15 -0
- core/claude/template/app/agent.py +49 -0
- core/claude/template/app/app_utils/a2a.py +245 -0
- core/claude/template/app/app_utils/bq_analytics/__init__.py +124 -0
- core/claude/template/app/app_utils/bq_analytics/recorder.py +593 -0
- core/claude/template/app/app_utils/bq_analytics/redaction.py +209 -0
- core/claude/template/app/app_utils/bq_analytics/schema.py +394 -0
- core/claude/template/app/app_utils/bq_analytics/tables.py +104 -0
- core/claude/template/app/app_utils/bq_analytics/uploader.py +188 -0
- core/claude/template/app/app_utils/claude.py +297 -0
- core/claude/template/app/app_utils/completions.py +225 -0
- core/claude/template/app/app_utils/conversation.py +29 -0
- core/claude/template/app/app_utils/memory_bank.py +308 -0
- core/claude/template/app/app_utils/project_settings.py +91 -0
- core/claude/template/app/app_utils/reasoning_engine.py +237 -0
- core/claude/template/app/app_utils/remote_agents.py +349 -0
- core/claude/template/app/app_utils/remote_auth.py +159 -0
- core/claude/template/app/app_utils/replies.py +143 -0
- core/claude/template/app/app_utils/session_store.py +174 -0
- core/claude/template/app/app_utils/settings.py +24 -0
- core/claude/template/app/app_utils/telemetry/__init__.py +114 -0
- core/claude/template/app/app_utils/telemetry/call_counts.py +44 -0
- core/claude/template/app/app_utils/telemetry/cli_relay.py +266 -0
- core/claude/template/app/app_utils/telemetry/config.py +133 -0
- core/claude/template/app/app_utils/telemetry/logs.py +175 -0
- core/claude/template/app/app_utils/telemetry/metrics.py +270 -0
- core/claude/template/app/app_utils/telemetry/request_flush.py +104 -0
- core/claude/template/app/app_utils/telemetry/subagent_spans.py +80 -0
- core/claude/template/app/app_utils/telemetry/traces.py +166 -0
- core/claude/template/app/app_utils/turn_events.py +463 -0
- core/claude/template/app/app_utils/turn_options.py +219 -0
- core/claude/template/app/app_utils/workspaces.py +65 -0
- core/claude/template/app/fast_api_app.py +71 -0
- core/claude/template/app/feature_tools.py +27 -0
- core/claude/template/pyproject.toml +100 -0
- core/claude/template/scripts/eval_generate.py +340 -0
- core/claude/template/scripts/publish.py +66 -0
- core/claude/template/scripts/run.py +85 -0
- core/claude/template/scripts/unsupported.py +48 -0
- core/claude/template/tests/eval/datasets/basic-dataset.json +31 -0
- core/claude/template/tests/eval/eval_config.yaml +17 -0
- core/claude/template/tests/eval/response_quality.py +60 -0
- core/claude/template/tests/integration/test_server_e2e.py +168 -0
- core/claude/template/tests/load_test/.results/.placeholder +0 -0
- core/claude/template/tests/load_test/README.md +24 -0
- core/claude/template/tests/load_test/load_test.py +118 -0
- core/claude/template/tests/unit/conftest.py +63 -0
- core/claude/template/tests/unit/helpers.py +32 -0
- core/claude/template/tests/unit/test_a2a.py +432 -0
- core/claude/template/tests/unit/test_bq_analytics.py +928 -0
- core/claude/template/tests/unit/test_bq_redaction.py +89 -0
- core/claude/template/tests/unit/test_claude.py +825 -0
- core/claude/template/tests/unit/test_completions.py +369 -0
- core/claude/template/tests/unit/test_fast_api_app.py +59 -0
- core/claude/template/tests/unit/test_feature_tools.py +55 -0
- core/claude/template/tests/unit/test_memory_bank.py +625 -0
- core/claude/template/tests/unit/test_reasoning_engine.py +295 -0
- core/claude/template/tests/unit/test_remote_agents.py +517 -0
- core/claude/template/tests/unit/test_telemetry.py +991 -0
- core/claude/template/tests/unit/test_turn_events.py +309 -0
- core/claude/template/tests/unit/test_turn_options.py +394 -0
- core/claude/template/uv.lock +3029 -0
- core/langchain/README.md +54 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/SKILL.md +84 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/references/langchain.md +120 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/references/samples.md +42 -0
- core/langchain/template/.template/templateconfig.yaml +32 -0
- core/langchain/template/AGENTS.md +35 -0
- core/langchain/template/agents-cli-extension.yaml +54 -0
- core/langchain/template/app/__init__.py +19 -0
- core/langchain/template/app/agent.py +61 -0
- core/langchain/template/app/app_utils/a2a.py +176 -0
- core/langchain/template/app/app_utils/content.py +37 -0
- core/langchain/template/app/app_utils/telemetry.py +154 -0
- core/langchain/template/app/fast_api_app.py +68 -0
- core/langchain/template/langgraph.json +7 -0
- core/langchain/template/pyproject.toml +102 -0
- core/langchain/template/scripts/_content.py +40 -0
- core/langchain/template/scripts/eval_generate.py +202 -0
- core/langchain/template/scripts/publish.py +59 -0
- core/langchain/template/scripts/run.py +59 -0
- core/langchain/template/scripts/unsupported.py +48 -0
- core/langchain/template/tests/eval/datasets/basic-dataset.json +16 -0
- core/langchain/template/tests/eval/eval_config.yaml +32 -0
- core/langchain/template/tests/eval/response_quality.py +60 -0
- core/langchain/template/tests/integration/test_server_e2e.py +173 -0
- core/langchain/template/tests/load_test/.results/.placeholder +0 -0
- core/langchain/template/tests/load_test/README.md +20 -0
- core/langchain/template/tests/load_test/load_test.py +82 -0
- core/langchain/template/uv.lock +3820 -0
- google_agents_cli_extensions-1.14.2.dist-info/METADATA +133 -0
- google_agents_cli_extensions-1.14.2.dist-info/RECORD +107 -0
- google_agents_cli_extensions-1.14.2.dist-info/WHEEL +4 -0
- google_agents_cli_extensions-1.14.2.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,270 @@
|
|
|
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
|
+
"""ADK's gen_ai.* metrics, exported to Cloud Monitoring.
|
|
16
|
+
|
|
17
|
+
Nothing is recorded until setup_cloud_metrics() runs.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
import logging
|
|
23
|
+
from collections.abc import Iterable, Mapping
|
|
24
|
+
from dataclasses import dataclass
|
|
25
|
+
from typing import Any
|
|
26
|
+
|
|
27
|
+
from openinference.semconv.trace import SpanAttributes
|
|
28
|
+
from opentelemetry.metrics import Histogram, MeterProvider
|
|
29
|
+
from opentelemetry.sdk.metrics.export import (
|
|
30
|
+
MetricExporter,
|
|
31
|
+
MetricExportResult,
|
|
32
|
+
MetricReader,
|
|
33
|
+
)
|
|
34
|
+
from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
|
|
35
|
+
from opentelemetry.trace import StatusCode
|
|
36
|
+
|
|
37
|
+
from app.app_utils.telemetry import config
|
|
38
|
+
|
|
39
|
+
_instruments: _Instruments | None = None
|
|
40
|
+
_metrics_failing = False
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def setup_cloud_metrics(credentials: Any, resource: Any) -> MetricReader | None:
|
|
44
|
+
"""Export the gen_ai.* metrics to Cloud Monitoring.
|
|
45
|
+
|
|
46
|
+
Agent Runtime throttles the CPU between requests, so there metrics are
|
|
47
|
+
collected per request and the reader is returned; elsewhere None.
|
|
48
|
+
"""
|
|
49
|
+
from opentelemetry import metrics as otel_metrics
|
|
50
|
+
from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
|
|
51
|
+
OTLPMetricExporter,
|
|
52
|
+
)
|
|
53
|
+
from opentelemetry.sdk.metrics import MeterProvider as SdkMeterProvider
|
|
54
|
+
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
|
|
55
|
+
|
|
56
|
+
global _instruments
|
|
57
|
+
session, upstream = config.telemetry_session(credentials)
|
|
58
|
+
exporter = _LoggingMetricExporter(
|
|
59
|
+
OTLPMetricExporter(session=session, endpoint=f"{upstream}/v1/metrics")
|
|
60
|
+
)
|
|
61
|
+
on_agent_runtime = config.on_agent_runtime()
|
|
62
|
+
reader = (
|
|
63
|
+
_RequestDrivenReader(exporter)
|
|
64
|
+
if on_agent_runtime
|
|
65
|
+
else PeriodicExportingMetricReader(exporter)
|
|
66
|
+
)
|
|
67
|
+
meter_provider = SdkMeterProvider(metric_readers=[reader], resource=resource)
|
|
68
|
+
otel_metrics.set_meter_provider(meter_provider)
|
|
69
|
+
_instruments = _create_instruments(meter_provider)
|
|
70
|
+
return reader if on_agent_runtime else None
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class MetricsProcessor(SpanProcessor):
|
|
74
|
+
"""Records agent and tool call durations from their spans."""
|
|
75
|
+
|
|
76
|
+
def on_end(self, span: ReadableSpan) -> None:
|
|
77
|
+
instruments = _instruments
|
|
78
|
+
attributes = span.attributes or {}
|
|
79
|
+
kind = attributes.get(SpanAttributes.OPENINFERENCE_SPAN_KIND)
|
|
80
|
+
if instruments is None or kind not in ("AGENT", "TOOL"):
|
|
81
|
+
return
|
|
82
|
+
try:
|
|
83
|
+
point: dict[str, Any] = {
|
|
84
|
+
"gen_ai.agent.name": attributes.get("gen_ai.agent.name")
|
|
85
|
+
or attributes.get(SpanAttributes.AGENT_NAME)
|
|
86
|
+
or config.agent_name(),
|
|
87
|
+
}
|
|
88
|
+
if span.status.status_code == StatusCode.ERROR:
|
|
89
|
+
point["error.type"] = _error_type(span)
|
|
90
|
+
seconds = ((span.end_time or 0) - (span.start_time or 0)) / 1e9
|
|
91
|
+
if kind == "AGENT":
|
|
92
|
+
point["gen_ai.operation.name"] = "invoke_agent"
|
|
93
|
+
instruments.agent_duration.record(seconds, point)
|
|
94
|
+
else:
|
|
95
|
+
point["gen_ai.operation.name"] = "execute_tool"
|
|
96
|
+
point["gen_ai.tool.name"] = str(
|
|
97
|
+
attributes.get("gen_ai.tool.name")
|
|
98
|
+
or attributes.get(SpanAttributes.TOOL_NAME, "")
|
|
99
|
+
)
|
|
100
|
+
instruments.tool_duration.record(seconds, point)
|
|
101
|
+
except Exception as e: # metrics must never fail a turn
|
|
102
|
+
_warn_metrics_failure(e)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def record_call_counts(counts: Iterable[tuple[str, int, int]]) -> None:
|
|
106
|
+
"""Record gen_ai.invoke_agent.inference_calls and .tool_calls.
|
|
107
|
+
|
|
108
|
+
`counts` holds (agent name, inference calls, tool calls) per agent of a turn.
|
|
109
|
+
"""
|
|
110
|
+
instruments = _instruments
|
|
111
|
+
if instruments is None:
|
|
112
|
+
return
|
|
113
|
+
try:
|
|
114
|
+
for agent, inference_calls, tool_calls in counts:
|
|
115
|
+
point = {"gen_ai.agent.name": agent}
|
|
116
|
+
instruments.inference_calls.record(inference_calls, point)
|
|
117
|
+
instruments.tool_calls.record(tool_calls, point)
|
|
118
|
+
except Exception as e: # metrics must never fail a turn
|
|
119
|
+
_warn_metrics_failure(e)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def record_token_usage(model: str, usage: Mapping[str, Any]) -> None:
|
|
123
|
+
"""Record gen_ai.client.token.usage for one CLI model call.
|
|
124
|
+
|
|
125
|
+
Subagent calls count toward the main agent: the CLI's spans don't name them.
|
|
126
|
+
"""
|
|
127
|
+
instruments = _instruments
|
|
128
|
+
if instruments is None:
|
|
129
|
+
return
|
|
130
|
+
try:
|
|
131
|
+
point = {
|
|
132
|
+
"gen_ai.operation.name": "generate_content",
|
|
133
|
+
"gen_ai.agent.name": config.agent_name(),
|
|
134
|
+
}
|
|
135
|
+
if model:
|
|
136
|
+
point["gen_ai.request.model"] = model
|
|
137
|
+
for token_type, key in (
|
|
138
|
+
("input", "gen_ai.usage.input_tokens"),
|
|
139
|
+
("output", "gen_ai.usage.output_tokens"),
|
|
140
|
+
):
|
|
141
|
+
if usage.get(key):
|
|
142
|
+
instruments.token_usage.record(
|
|
143
|
+
usage[key], {**point, "gen_ai.token.type": token_type}
|
|
144
|
+
)
|
|
145
|
+
except Exception as e: # metrics must never drop the relay's response
|
|
146
|
+
_warn_metrics_failure(e)
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
class _LoggingMetricExporter(MetricExporter):
|
|
150
|
+
"""Wraps an exporter: a failed export is logged once, and never raises."""
|
|
151
|
+
|
|
152
|
+
def __init__(self, exporter: MetricExporter) -> None:
|
|
153
|
+
# The OTLP exporter resolves these from OTEL_EXPORTER_OTLP_METRICS_*,
|
|
154
|
+
# and only exposes the result here.
|
|
155
|
+
super().__init__(
|
|
156
|
+
preferred_temporality=exporter._preferred_temporality,
|
|
157
|
+
preferred_aggregation=exporter._preferred_aggregation,
|
|
158
|
+
)
|
|
159
|
+
self._exporter = exporter
|
|
160
|
+
|
|
161
|
+
def export(
|
|
162
|
+
self, metrics_data: Any, timeout_millis: float = 10_000, **kwargs: Any
|
|
163
|
+
) -> MetricExportResult:
|
|
164
|
+
global _metrics_failing
|
|
165
|
+
try:
|
|
166
|
+
result = self._exporter.export(metrics_data, timeout_millis=timeout_millis)
|
|
167
|
+
except Exception as e:
|
|
168
|
+
_warn_metrics_failure(e)
|
|
169
|
+
return MetricExportResult.FAILURE
|
|
170
|
+
if result == MetricExportResult.SUCCESS:
|
|
171
|
+
_metrics_failing = False
|
|
172
|
+
else:
|
|
173
|
+
_warn_metrics_failure("the Telemetry API rejected the export")
|
|
174
|
+
return result
|
|
175
|
+
|
|
176
|
+
def force_flush(self, timeout_millis: float = 10_000) -> bool:
|
|
177
|
+
return self._exporter.force_flush(timeout_millis)
|
|
178
|
+
|
|
179
|
+
def shutdown(self, timeout_millis: float = 30_000, **kwargs: Any) -> None:
|
|
180
|
+
self._exporter.shutdown(timeout_millis=timeout_millis)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
class _RequestDrivenReader(MetricReader):
|
|
184
|
+
"""Collects only when collect() is called: see request_flush.py."""
|
|
185
|
+
|
|
186
|
+
def __init__(self, exporter: MetricExporter) -> None:
|
|
187
|
+
super().__init__(
|
|
188
|
+
preferred_temporality=exporter._preferred_temporality,
|
|
189
|
+
preferred_aggregation=exporter._preferred_aggregation,
|
|
190
|
+
)
|
|
191
|
+
self._exporter = exporter
|
|
192
|
+
|
|
193
|
+
def _receive_metrics(
|
|
194
|
+
self, metrics_data: Any, timeout_millis: float = 10_000, **kwargs: Any
|
|
195
|
+
) -> None:
|
|
196
|
+
self._exporter.export(metrics_data, timeout_millis=timeout_millis)
|
|
197
|
+
|
|
198
|
+
def shutdown(self, timeout_millis: float = 30_000, **kwargs: Any) -> None:
|
|
199
|
+
self.collect(timeout_millis=timeout_millis)
|
|
200
|
+
self._exporter.shutdown(timeout_millis=timeout_millis)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
@dataclass(frozen=True)
|
|
204
|
+
class _Instruments:
|
|
205
|
+
agent_duration: Histogram
|
|
206
|
+
tool_duration: Histogram
|
|
207
|
+
inference_calls: Histogram
|
|
208
|
+
tool_calls: Histogram
|
|
209
|
+
token_usage: Histogram
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
_CALL_COUNT_BUCKETS = [0, 1, 2, 3, 4, 5, 6, 8, 12, 16, 24, 32, 64, 128, 256, 512]
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def _create_instruments(meter_provider: MeterProvider) -> _Instruments:
|
|
216
|
+
# Same meter name as ADK, so existing dashboards pick these up.
|
|
217
|
+
meter = meter_provider.get_meter("gcp.vertex.agent")
|
|
218
|
+
return _Instruments(
|
|
219
|
+
agent_duration=meter.create_histogram(
|
|
220
|
+
"gen_ai.invoke_agent.duration",
|
|
221
|
+
unit="s",
|
|
222
|
+
description="Duration of agent invocations.",
|
|
223
|
+
explicit_bucket_boundaries_advisory=[0.1 * 2**i for i in range(13)],
|
|
224
|
+
),
|
|
225
|
+
tool_duration=meter.create_histogram(
|
|
226
|
+
"gen_ai.execute_tool.duration",
|
|
227
|
+
unit="s",
|
|
228
|
+
description="Duration of tool executions.",
|
|
229
|
+
explicit_bucket_boundaries_advisory=[0.01 * 2**i for i in range(14)],
|
|
230
|
+
),
|
|
231
|
+
inference_calls=meter.create_histogram(
|
|
232
|
+
"gen_ai.invoke_agent.inference_calls",
|
|
233
|
+
unit="1",
|
|
234
|
+
description="Number of inference (model) calls per agent invocation.",
|
|
235
|
+
explicit_bucket_boundaries_advisory=_CALL_COUNT_BUCKETS,
|
|
236
|
+
),
|
|
237
|
+
tool_calls=meter.create_histogram(
|
|
238
|
+
"gen_ai.invoke_agent.tool_calls",
|
|
239
|
+
unit="1",
|
|
240
|
+
description="Number of tool calls per agent invocation.",
|
|
241
|
+
explicit_bucket_boundaries_advisory=_CALL_COUNT_BUCKETS,
|
|
242
|
+
),
|
|
243
|
+
token_usage=meter.create_histogram(
|
|
244
|
+
"gen_ai.client.token.usage",
|
|
245
|
+
unit="{token}",
|
|
246
|
+
description="Number of input and output tokens used.",
|
|
247
|
+
explicit_bucket_boundaries_advisory=[4**i for i in range(14)],
|
|
248
|
+
),
|
|
249
|
+
)
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def _error_type(span: ReadableSpan) -> str:
|
|
253
|
+
"""The recorded exception's unqualified class name, else _OTHER."""
|
|
254
|
+
for event in span.events:
|
|
255
|
+
if event.name == "exception" and event.attributes:
|
|
256
|
+
name = str(event.attributes.get("exception.type", "_OTHER"))
|
|
257
|
+
return name.rsplit(".", 1)[-1]
|
|
258
|
+
return "_OTHER"
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def _warn_metrics_failure(error: object) -> None:
|
|
262
|
+
global _metrics_failing
|
|
263
|
+
if not _metrics_failing:
|
|
264
|
+
logging.warning(
|
|
265
|
+
"Exporting agent metrics to Cloud Monitoring failed: %s. The next "
|
|
266
|
+
"export sends the totals again; the service account needs "
|
|
267
|
+
"roles/monitoring.metricWriter.",
|
|
268
|
+
error,
|
|
269
|
+
)
|
|
270
|
+
_metrics_failing = True
|
|
@@ -0,0 +1,104 @@
|
|
|
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
|
+
"""On Agent Runtime, export each request's telemetry before its response ends.
|
|
16
|
+
|
|
17
|
+
Agent Runtime throttles the CPU once a response ends, starving background
|
|
18
|
+
exports.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import logging
|
|
24
|
+
import threading
|
|
25
|
+
import time
|
|
26
|
+
from collections.abc import Callable
|
|
27
|
+
from dataclasses import dataclass
|
|
28
|
+
from typing import Any
|
|
29
|
+
|
|
30
|
+
import anyio
|
|
31
|
+
from opentelemetry.sdk.metrics.export import MetricReader
|
|
32
|
+
|
|
33
|
+
from app.app_utils.telemetry.config import FLUSH_TIMEOUT_MILLIS
|
|
34
|
+
|
|
35
|
+
# Cloud Monitoring rejects points on one time series written closer than this.
|
|
36
|
+
_MIN_COLLECT_SECONDS = 5.0
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
@dataclass(frozen=True)
|
|
40
|
+
class _RequestFlush:
|
|
41
|
+
tracer_provider: Any
|
|
42
|
+
logger_provider: Any
|
|
43
|
+
reader: MetricReader
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
_request_flush: _RequestFlush | None = None
|
|
47
|
+
_collect_lock = threading.Lock()
|
|
48
|
+
_last_collect = float("-inf")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def enable_request_flush(
|
|
52
|
+
tracer_provider: Any, logger_provider: Any, reader: MetricReader
|
|
53
|
+
) -> None:
|
|
54
|
+
"""Make FlushTelemetryMiddleware flush these before each response ends."""
|
|
55
|
+
global _request_flush
|
|
56
|
+
_request_flush = _RequestFlush(tracer_provider, logger_provider, reader)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class FlushTelemetryMiddleware:
|
|
60
|
+
"""Exports each POST request's telemetry before its last body chunk.
|
|
61
|
+
|
|
62
|
+
No-op until enable_request_flush() runs, which only happens on Agent Runtime.
|
|
63
|
+
Agent turns arrive as POSTs; health checks and agent card reads don't wait.
|
|
64
|
+
"""
|
|
65
|
+
|
|
66
|
+
def __init__(self, app: Callable[..., Any]) -> None:
|
|
67
|
+
self.app = app
|
|
68
|
+
|
|
69
|
+
async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
|
|
70
|
+
flush = _request_flush
|
|
71
|
+
if flush is None or scope["type"] != "http" or scope.get("method") != "POST":
|
|
72
|
+
await self.app(scope, receive, send)
|
|
73
|
+
return
|
|
74
|
+
|
|
75
|
+
async def send_after_flush(message: Any) -> None:
|
|
76
|
+
if message["type"] == "http.response.body" and not message.get("more_body"):
|
|
77
|
+
await anyio.to_thread.run_sync(_flush_request_telemetry, flush)
|
|
78
|
+
await send(message)
|
|
79
|
+
|
|
80
|
+
await self.app(scope, receive, send_after_flush)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _flush_request_telemetry(flush: _RequestFlush) -> None:
|
|
84
|
+
"""Export the request's spans, log records and, if due, metrics."""
|
|
85
|
+
try:
|
|
86
|
+
flush.tracer_provider.force_flush(FLUSH_TIMEOUT_MILLIS)
|
|
87
|
+
flush.logger_provider.force_flush(FLUSH_TIMEOUT_MILLIS)
|
|
88
|
+
_collect_metrics_if_due(flush.reader)
|
|
89
|
+
except Exception as e: # never fail the request it rides on
|
|
90
|
+
logging.warning("Exporting the request's telemetry failed: %s", e)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _collect_metrics_if_due(reader: MetricReader) -> None:
|
|
94
|
+
global _last_collect
|
|
95
|
+
# While another request collects, skip rather than wait: this request's
|
|
96
|
+
# points go out with the next collect, as they do within the 5 s window.
|
|
97
|
+
if not _collect_lock.acquire(blocking=False):
|
|
98
|
+
return
|
|
99
|
+
try:
|
|
100
|
+
if time.monotonic() - _last_collect >= _MIN_COLLECT_SECONDS:
|
|
101
|
+
_last_collect = time.monotonic()
|
|
102
|
+
reader.collect(timeout_millis=FLUSH_TIMEOUT_MILLIS)
|
|
103
|
+
finally:
|
|
104
|
+
_collect_lock.release()
|
|
@@ -0,0 +1,80 @@
|
|
|
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
|
+
|
|
16
|
+
"""Names one turn's subagent spans, which OpenInference leaves unnamed."""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from collections.abc import Callable
|
|
21
|
+
from contextvars import ContextVar
|
|
22
|
+
from typing import Any
|
|
23
|
+
|
|
24
|
+
from openinference.semconv.trace import SpanAttributes
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class SubagentSpans:
|
|
28
|
+
"""Names one turn's subagent spans, and finds the span of each subagent.
|
|
29
|
+
|
|
30
|
+
OpenInference doesn't say which Agent call a subagent span is for, so the
|
|
31
|
+
first message with a new parent_tool_use_id claims the newest unclaimed span.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
def __init__(self, agent_name: Callable[[str | None], str]) -> None:
|
|
35
|
+
self._agent_name = agent_name
|
|
36
|
+
self._turn_started = False
|
|
37
|
+
self._unclaimed: dict[int, tuple[Any, list[Any]]] = {}
|
|
38
|
+
self._subagent_spans: dict[str, Any] = {}
|
|
39
|
+
self._span_agents: dict[int, str] = {}
|
|
40
|
+
|
|
41
|
+
def observe(self, message: Any) -> None:
|
|
42
|
+
"""Claim a span for the subagent that sent `message`, if it has none yet."""
|
|
43
|
+
parent = getattr(message, "parent_tool_use_id", None)
|
|
44
|
+
if parent and parent not in self._subagent_spans and self._unclaimed:
|
|
45
|
+
self._claim(parent, *self._unclaimed.popitem()[1])
|
|
46
|
+
|
|
47
|
+
def subagent_span(self, parent_tool_use_id: str) -> Any:
|
|
48
|
+
"""The span of the subagent whose messages have this parent, if any."""
|
|
49
|
+
return self._subagent_spans.get(parent_tool_use_id)
|
|
50
|
+
|
|
51
|
+
def span_started(self, span: Any) -> str | None:
|
|
52
|
+
"""The name for one of the turn's OpenInference spans, if not the agent's."""
|
|
53
|
+
attributes = span.attributes or {}
|
|
54
|
+
if attributes.get(SpanAttributes.OPENINFERENCE_SPAN_KIND) == "AGENT":
|
|
55
|
+
# The first is the turn's own span; later ones are subagents'.
|
|
56
|
+
if self._turn_started:
|
|
57
|
+
self._unclaimed[span.get_span_context().span_id] = (span, [])
|
|
58
|
+
self._turn_started = True
|
|
59
|
+
return None
|
|
60
|
+
parent = span.parent.span_id if span.parent else None
|
|
61
|
+
if parent in self._unclaimed:
|
|
62
|
+
self._unclaimed[parent][1].append(span)
|
|
63
|
+
return self._span_agents.get(parent)
|
|
64
|
+
|
|
65
|
+
def _claim(self, parent_tool_use_id: str, span: Any, children: list[Any]) -> None:
|
|
66
|
+
name = self._agent_name(parent_tool_use_id)
|
|
67
|
+
span.update_name(f"ClaudeAgentSDK.{name}")
|
|
68
|
+
span.set_attributes(
|
|
69
|
+
{SpanAttributes.AGENT_NAME: name, "gen_ai.agent.name": name}
|
|
70
|
+
)
|
|
71
|
+
for child in children:
|
|
72
|
+
child.set_attribute("gen_ai.agent.name", name)
|
|
73
|
+
self._subagent_spans[parent_tool_use_id] = span
|
|
74
|
+
self._span_agents[span.get_span_context().span_id] = name
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
# The running turn's subagent spans, for naming spans as they start.
|
|
78
|
+
current_subagent_spans: ContextVar[SubagentSpans | None] = ContextVar(
|
|
79
|
+
"current_subagent_spans", default=None
|
|
80
|
+
)
|
|
@@ -0,0 +1,166 @@
|
|
|
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
|
+
"""The server's spans: OpenInference instrumentation, and export to Cloud Trace."""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import logging
|
|
20
|
+
import os
|
|
21
|
+
from typing import Any
|
|
22
|
+
|
|
23
|
+
from openinference.instrumentation import REDACTED_VALUE, TraceConfig
|
|
24
|
+
from openinference.semconv.trace import SpanAttributes
|
|
25
|
+
from opentelemetry.sdk.trace import SpanProcessor, TracerProvider
|
|
26
|
+
from opentelemetry.sdk.trace.sampling import Decision, Sampler, SamplingResult
|
|
27
|
+
from opentelemetry.trace import NoOpTracer
|
|
28
|
+
from opentelemetry.util.genai.types import TextPart
|
|
29
|
+
from opentelemetry.util.genai.utils import gen_ai_json_dumps
|
|
30
|
+
|
|
31
|
+
from app.app_utils.telemetry import config
|
|
32
|
+
from app.app_utils.telemetry.subagent_spans import current_subagent_spans
|
|
33
|
+
from app.app_utils.turn_events import system_prompt_text
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def install_instrumentation() -> None:
|
|
37
|
+
try:
|
|
38
|
+
from openinference.instrumentation.claude_agent_sdk import (
|
|
39
|
+
ClaudeAgentSDKInstrumentor,
|
|
40
|
+
)
|
|
41
|
+
|
|
42
|
+
ClaudeAgentSDKInstrumentor().instrument(config=_trace_config())
|
|
43
|
+
except Exception as e: # pragma: no cover - optional dependency
|
|
44
|
+
logging.warning("Claude Agent SDK instrumentation unavailable: %s", e)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def setup_cloud_tracing(
|
|
48
|
+
credentials: Any, resource: Any, project_id: str
|
|
49
|
+
) -> TracerProvider:
|
|
50
|
+
"""A tracer provider that names the agent's spans and exports them to Cloud Trace."""
|
|
51
|
+
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
|
|
52
|
+
OTLPSpanExporter,
|
|
53
|
+
)
|
|
54
|
+
from opentelemetry.sdk.resources import OTELResourceDetector, Resource
|
|
55
|
+
from opentelemetry.sdk.trace.export import BatchSpanProcessor
|
|
56
|
+
from opentelemetry.sdk.trace.sampling import ALWAYS_ON
|
|
57
|
+
|
|
58
|
+
# Cloud Run and Agent Runtime front ends usually mark traceparent not
|
|
59
|
+
# sampled, so a parent-based sampler would drop every span.
|
|
60
|
+
sampler = None if os.environ.get("OTEL_TRACES_SAMPLER") else ALWAYS_ON
|
|
61
|
+
# Spans only: logs and metrics need the detected resource to map to their
|
|
62
|
+
# Cloud Logging and Cloud Monitoring resources.
|
|
63
|
+
span_resource = resource.merge(
|
|
64
|
+
Resource(config.agent_runtime_attributes(project_id))
|
|
65
|
+
).merge(OTELResourceDetector().detect())
|
|
66
|
+
tracer_provider = _TracerProvider(resource=span_resource, sampler=sampler)
|
|
67
|
+
tracer_provider.add_span_processor(AgentNameProcessor(config.agent_name()))
|
|
68
|
+
session, upstream = config.telemetry_session(credentials)
|
|
69
|
+
tracer_provider.add_span_processor(
|
|
70
|
+
BatchSpanProcessor(
|
|
71
|
+
OTLPSpanExporter(session=session, endpoint=f"{upstream}/v1/traces")
|
|
72
|
+
)
|
|
73
|
+
)
|
|
74
|
+
return tracer_provider
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class AgentNameProcessor(SpanProcessor):
|
|
78
|
+
"""Adds gen_ai.agent.name to the agent's and its tools' spans."""
|
|
79
|
+
|
|
80
|
+
def __init__(self, agent_name: str) -> None:
|
|
81
|
+
self._agent_name = agent_name
|
|
82
|
+
|
|
83
|
+
def on_start(self, span: Any, parent_context: Any = None) -> None:
|
|
84
|
+
attributes = span.attributes or {}
|
|
85
|
+
if SpanAttributes.OPENINFERENCE_SPAN_KIND not in attributes:
|
|
86
|
+
return
|
|
87
|
+
subagent_spans = current_subagent_spans.get()
|
|
88
|
+
name = subagent_spans.span_started(span) if subagent_spans is not None else None
|
|
89
|
+
if name is not None:
|
|
90
|
+
span.set_attribute("gen_ai.agent.name", name)
|
|
91
|
+
elif SpanAttributes.AGENT_NAME not in attributes:
|
|
92
|
+
span.set_attribute("gen_ai.agent.name", self._agent_name)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
# NOTE: The OpenTelemetry GenAI conventions are adding memory operations (a
|
|
96
|
+
# search_memory span with gen_ai.memory.records). Once a released version defines
|
|
97
|
+
# them, record recalled memories that way.
|
|
98
|
+
def system_prompt_attributes(system_prompt: Any) -> dict[str, str]:
|
|
99
|
+
"""The turn span's record of the system prompt the model got, as ADK's.
|
|
100
|
+
|
|
101
|
+
Empty unless content capture is on: the prompt can hold the user's memories.
|
|
102
|
+
"""
|
|
103
|
+
text = system_prompt_text(system_prompt)
|
|
104
|
+
if not text or not config.capture_content():
|
|
105
|
+
return {}
|
|
106
|
+
return {"gen_ai.system_instructions": gen_ai_json_dumps([TextPart(content=text)])}
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _trace_config() -> TraceConfig:
|
|
110
|
+
os.environ.setdefault("OPENINFERENCE_ENABLE_GENAI_SEMCONV", "true")
|
|
111
|
+
if not config.capture_content():
|
|
112
|
+
os.environ.setdefault("OPENINFERENCE_HIDE_INPUTS", "true")
|
|
113
|
+
os.environ.setdefault("OPENINFERENCE_HIDE_OUTPUTS", "true")
|
|
114
|
+
return _TraceConfig()
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
class _TraceConfig(TraceConfig):
|
|
118
|
+
"""Also hides tool.parameters when inputs are hidden; OpenInference doesn't."""
|
|
119
|
+
|
|
120
|
+
def mask(self, key, value, *, externalize: bool = True):
|
|
121
|
+
if self.hide_inputs and key == SpanAttributes.TOOL_PARAMETERS:
|
|
122
|
+
return REDACTED_VALUE
|
|
123
|
+
return super().mask(key, value, externalize=externalize)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
# MCP spans duplicate OpenInference's tool spans; BigQuery spans come from
|
|
127
|
+
# BigQuery Agent Analytics' own writes.
|
|
128
|
+
_UNRECORDED_SCOPES = ("mcp-python-sdk", "google.cloud.bigquery")
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class _TracerProvider(TracerProvider):
|
|
132
|
+
"""Gives _UNRECORDED_SCOPES no-op tracers, and records unsampled spans.
|
|
133
|
+
|
|
134
|
+
No-op tracers rather than export filtering, so child spans keep a parent
|
|
135
|
+
that exists.
|
|
136
|
+
"""
|
|
137
|
+
|
|
138
|
+
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
|
139
|
+
super().__init__(*args, **kwargs)
|
|
140
|
+
self.sampler = _RecordUnsampled(self.sampler)
|
|
141
|
+
|
|
142
|
+
def get_tracer(self, instrumenting_module_name: str, *args: Any, **kwargs: Any):
|
|
143
|
+
if instrumenting_module_name.startswith(_UNRECORDED_SCOPES):
|
|
144
|
+
return NoOpTracer()
|
|
145
|
+
return super().get_tracer(instrumenting_module_name, *args, **kwargs)
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
class _RecordUnsampled(Sampler):
|
|
149
|
+
"""Records dropped spans without sampling them.
|
|
150
|
+
|
|
151
|
+
OpenInference fails a turn whose span isn't recording.
|
|
152
|
+
"""
|
|
153
|
+
|
|
154
|
+
def __init__(self, sampler: Sampler) -> None:
|
|
155
|
+
self._sampler = sampler
|
|
156
|
+
|
|
157
|
+
def should_sample(self, *args: Any, **kwargs: Any) -> SamplingResult:
|
|
158
|
+
result = self._sampler.should_sample(*args, **kwargs)
|
|
159
|
+
if result.decision is not Decision.DROP:
|
|
160
|
+
return result
|
|
161
|
+
return SamplingResult(
|
|
162
|
+
Decision.RECORD_ONLY, result.attributes, result.trace_state
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
def get_description(self) -> str:
|
|
166
|
+
return self._sampler.get_description()
|