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,266 @@
|
|
|
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 Claude Code CLI's spans: a local relay to Cloud Trace, and the CLI's env.
|
|
16
|
+
|
|
17
|
+
The relay also adds ADK's gen_ai.usage.* attributes to the CLI's model-call
|
|
18
|
+
spans, and records their token usage.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import gzip
|
|
24
|
+
import logging
|
|
25
|
+
import os
|
|
26
|
+
import queue
|
|
27
|
+
import threading
|
|
28
|
+
from collections.abc import Callable
|
|
29
|
+
from dataclasses import dataclass
|
|
30
|
+
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
|
31
|
+
from typing import Any
|
|
32
|
+
|
|
33
|
+
from app.app_utils.telemetry import config, metrics
|
|
34
|
+
|
|
35
|
+
# If you set any of these, the Claude Code CLI's telemetry is left to you.
|
|
36
|
+
_USER_CLI_TELEMETRY_VARS = (
|
|
37
|
+
"CLAUDE_CODE_ENABLE_TELEMETRY",
|
|
38
|
+
"OTEL_TRACES_EXPORTER",
|
|
39
|
+
"OTEL_EXPORTER_OTLP_ENDPOINT",
|
|
40
|
+
"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
# Statuses the CLI's OTLP exporter retries on.
|
|
44
|
+
_RETRIED_STATUSES = (429, 502, 503, 504)
|
|
45
|
+
|
|
46
|
+
# gen_ai.usage.input_tokens includes the cache tokens.
|
|
47
|
+
_CLI_LLM_SPAN = "claude_code.llm_request"
|
|
48
|
+
_CLI_CACHE_TOKENS = ("cache_read_tokens", "cache_creation_tokens")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
@dataclass(frozen=True)
|
|
52
|
+
class _CliExport:
|
|
53
|
+
endpoint: str
|
|
54
|
+
project_id: str
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
_cli_export: _CliExport | None = None
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def enable_cli_export(credentials: Any, project_id: str) -> None:
|
|
61
|
+
"""Relay the CLI's spans to Cloud Trace, unless you configured its telemetry."""
|
|
62
|
+
global _cli_export
|
|
63
|
+
if any(os.environ.get(v) for v in _USER_CLI_TELEMETRY_VARS):
|
|
64
|
+
return
|
|
65
|
+
endpoint = start_trace_forwarder(lambda: config.telemetry_session(credentials))
|
|
66
|
+
_cli_export = _CliExport(endpoint, project_id)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def cli_telemetry_env() -> dict[str, str]:
|
|
70
|
+
"""Environment that makes the Claude Code CLI export its spans, if enabled."""
|
|
71
|
+
if _cli_export is None:
|
|
72
|
+
return {}
|
|
73
|
+
runtime = config.agent_runtime_attributes(_cli_export.project_id)
|
|
74
|
+
engine_id = runtime.pop("service.name", None)
|
|
75
|
+
service_name = (
|
|
76
|
+
os.environ.get("OTEL_SERVICE_NAME") or engine_id or config.service_name()
|
|
77
|
+
)
|
|
78
|
+
env = {
|
|
79
|
+
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
|
|
80
|
+
"CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
|
|
81
|
+
"OTEL_TRACES_EXPORTER": "otlp",
|
|
82
|
+
# Never "console": the CLI's stdout carries the SDK's messages.
|
|
83
|
+
"OTEL_METRICS_EXPORTER": "none",
|
|
84
|
+
"OTEL_LOGS_EXPORTER": "none",
|
|
85
|
+
"OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
|
|
86
|
+
"OTEL_EXPORTER_OTLP_ENDPOINT": _cli_export.endpoint,
|
|
87
|
+
"OTEL_RESOURCE_ATTRIBUTES": _resource_attributes(
|
|
88
|
+
runtime, _cli_export.project_id
|
|
89
|
+
),
|
|
90
|
+
"OTEL_SERVICE_NAME": service_name,
|
|
91
|
+
}
|
|
92
|
+
if config.capture_content():
|
|
93
|
+
for var in (
|
|
94
|
+
"OTEL_LOG_USER_PROMPTS",
|
|
95
|
+
"OTEL_LOG_TOOL_DETAILS",
|
|
96
|
+
"OTEL_LOG_TOOL_CONTENT",
|
|
97
|
+
):
|
|
98
|
+
env[var] = os.environ.get(var, "1")
|
|
99
|
+
return env
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def start_trace_forwarder(new_session: Callable[[], tuple[Any, str]]) -> str:
|
|
103
|
+
"""Relay the CLI's OTLP trace exports from 127.0.0.1 to the Telemetry API.
|
|
104
|
+
|
|
105
|
+
The CLI can't mint Google credentials, so the sessions `new_session` makes
|
|
106
|
+
add them; it returns a session and the upstream it sends to. Returns the
|
|
107
|
+
endpoint for the CLI's OTEL_EXPORTER_OTLP_ENDPOINT.
|
|
108
|
+
"""
|
|
109
|
+
# Each request runs on its own thread and takes a session no other request
|
|
110
|
+
# holds: sessions aren't thread-safe. The first is made now, so a bad
|
|
111
|
+
# credential setup fails at startup.
|
|
112
|
+
idle: queue.SimpleQueue[tuple[Any, str]] = queue.SimpleQueue()
|
|
113
|
+
idle.put(new_session())
|
|
114
|
+
|
|
115
|
+
class Handler(BaseHTTPRequestHandler):
|
|
116
|
+
def do_POST(self) -> None:
|
|
117
|
+
if self.path != "/v1/traces":
|
|
118
|
+
self.send_error(404)
|
|
119
|
+
return
|
|
120
|
+
body = self.rfile.read(int(self.headers.get("Content-Length") or 0))
|
|
121
|
+
headers = {
|
|
122
|
+
k: self.headers[k]
|
|
123
|
+
for k in ("Content-Type", "Content-Encoding")
|
|
124
|
+
if self.headers.get(k)
|
|
125
|
+
}
|
|
126
|
+
body, calls = _with_genai_usage(body, headers)
|
|
127
|
+
try:
|
|
128
|
+
session, upstream = idle.get_nowait()
|
|
129
|
+
except queue.Empty:
|
|
130
|
+
session, upstream = new_session()
|
|
131
|
+
try:
|
|
132
|
+
response = session.post(
|
|
133
|
+
f"{upstream}/v1/traces", data=body, headers=headers, timeout=10
|
|
134
|
+
)
|
|
135
|
+
except Exception as e:
|
|
136
|
+
logging.warning("Forwarding Claude Code CLI spans failed: %s", e)
|
|
137
|
+
self.send_error(502)
|
|
138
|
+
return
|
|
139
|
+
finally:
|
|
140
|
+
idle.put((session, upstream))
|
|
141
|
+
# The CLI retries these, so count tokens only on the final attempt.
|
|
142
|
+
if response.status_code not in _RETRIED_STATUSES:
|
|
143
|
+
for model, usage in calls:
|
|
144
|
+
metrics.record_token_usage(model, usage)
|
|
145
|
+
if response.status_code >= 400:
|
|
146
|
+
logging.warning(
|
|
147
|
+
"Cloud Trace rejected Claude Code CLI spans (%s): %s",
|
|
148
|
+
response.status_code,
|
|
149
|
+
response.text[:500],
|
|
150
|
+
)
|
|
151
|
+
self.send_response(response.status_code)
|
|
152
|
+
self.send_header(
|
|
153
|
+
"Content-Type",
|
|
154
|
+
response.headers.get("Content-Type", "application/x-protobuf"),
|
|
155
|
+
)
|
|
156
|
+
self.send_header("Content-Length", str(len(response.content)))
|
|
157
|
+
self.end_headers()
|
|
158
|
+
self.wfile.write(response.content)
|
|
159
|
+
|
|
160
|
+
def log_message(self, format: str, *args: Any) -> None:
|
|
161
|
+
pass
|
|
162
|
+
|
|
163
|
+
server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
|
|
164
|
+
server.daemon_threads = True
|
|
165
|
+
threading.Thread(
|
|
166
|
+
target=server.serve_forever, name="otlp-forwarder", daemon=True
|
|
167
|
+
).start()
|
|
168
|
+
return f"http://127.0.0.1:{server.server_port}"
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _resource_attributes(runtime: dict[str, str], project_id: str) -> str:
|
|
172
|
+
"""OTEL_RESOURCE_ATTRIBUTES for the CLI: Agent Runtime's, then the user's."""
|
|
173
|
+
# The Telemetry API rejects spans whose resource lacks gcp.project_id.
|
|
174
|
+
user_attributes = os.environ.get("OTEL_RESOURCE_ATTRIBUTES", "")
|
|
175
|
+
if "gcp.project_id=" not in user_attributes:
|
|
176
|
+
user_attributes = ",".join(
|
|
177
|
+
filter(None, [user_attributes, f"gcp.project_id={project_id}"])
|
|
178
|
+
)
|
|
179
|
+
# User attributes come last so they override.
|
|
180
|
+
return ",".join(
|
|
181
|
+
[*(f"{key}={value}" for key, value in runtime.items()), user_attributes]
|
|
182
|
+
)
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def _with_genai_usage(
|
|
186
|
+
body: bytes, headers: dict[str, str]
|
|
187
|
+
) -> tuple[bytes, list[tuple[str, dict[str, Any]]]]:
|
|
188
|
+
"""The export with gen_ai.usage.* added, if it's protobuf; else unchanged.
|
|
189
|
+
|
|
190
|
+
Decompresses a gzipped body, and drops its Content-Encoding from `headers`.
|
|
191
|
+
"""
|
|
192
|
+
if headers.get("Content-Type") != "application/x-protobuf":
|
|
193
|
+
return body, []
|
|
194
|
+
try:
|
|
195
|
+
if headers.get("Content-Encoding") == "gzip":
|
|
196
|
+
body = gzip.decompress(body)
|
|
197
|
+
headers.pop("Content-Encoding")
|
|
198
|
+
return _add_genai_usage(body)
|
|
199
|
+
except Exception as e: # never lose spans over the extra attributes
|
|
200
|
+
logging.debug("Could not add GenAI usage to CLI spans: %s", e)
|
|
201
|
+
return body, []
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def _add_genai_usage(body: bytes) -> tuple[bytes, list[tuple[str, dict[str, Any]]]]:
|
|
205
|
+
"""Add gen_ai.usage.* to the CLI's model-call spans in an OTLP export.
|
|
206
|
+
|
|
207
|
+
Also returns each call's model and usage.
|
|
208
|
+
"""
|
|
209
|
+
if _CLI_LLM_SPAN.encode() not in body:
|
|
210
|
+
return body, []
|
|
211
|
+
from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
|
|
212
|
+
ExportTraceServiceRequest,
|
|
213
|
+
)
|
|
214
|
+
from opentelemetry.proto.common.v1.common_pb2 import AnyValue, KeyValue
|
|
215
|
+
|
|
216
|
+
request = ExportTraceServiceRequest.FromString(body)
|
|
217
|
+
calls = []
|
|
218
|
+
for resource_spans in request.resource_spans:
|
|
219
|
+
for scope_spans in resource_spans.scope_spans:
|
|
220
|
+
for span in scope_spans.spans:
|
|
221
|
+
if span.name != _CLI_LLM_SPAN:
|
|
222
|
+
continue
|
|
223
|
+
present = {kv.key: kv.value for kv in span.attributes}
|
|
224
|
+
usage = _genai_usage(_token_counts(present))
|
|
225
|
+
model = present.get("model")
|
|
226
|
+
calls.append((model.string_value if model else "", usage))
|
|
227
|
+
for key, value in usage.items():
|
|
228
|
+
if key in present:
|
|
229
|
+
continue
|
|
230
|
+
any_value = (
|
|
231
|
+
AnyValue(int_value=value)
|
|
232
|
+
if isinstance(value, int)
|
|
233
|
+
else AnyValue(string_value=value)
|
|
234
|
+
)
|
|
235
|
+
span.attributes.append(KeyValue(key=key, value=any_value))
|
|
236
|
+
return request.SerializeToString(), calls
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def _token_counts(attributes: dict[str, Any]) -> dict[str, int]:
|
|
240
|
+
"""The CLI's token counts among a span's attributes, sent as int or string."""
|
|
241
|
+
counts = {}
|
|
242
|
+
for key in ("input_tokens", "output_tokens", *_CLI_CACHE_TOKENS):
|
|
243
|
+
value = attributes.get(key)
|
|
244
|
+
if value is None:
|
|
245
|
+
continue
|
|
246
|
+
raw = value.int_value if value.HasField("int_value") else value.string_value
|
|
247
|
+
if str(raw).isdigit():
|
|
248
|
+
counts[key] = int(raw)
|
|
249
|
+
return counts
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def _genai_usage(counts: dict[str, int]) -> dict[str, Any]:
|
|
253
|
+
usage: dict[str, Any] = {"gen_ai.operation.name": "generate_content"}
|
|
254
|
+
if "input_tokens" in counts:
|
|
255
|
+
usage["gen_ai.usage.input_tokens"] = counts["input_tokens"] + sum(
|
|
256
|
+
counts.get(key, 0) for key in _CLI_CACHE_TOKENS
|
|
257
|
+
)
|
|
258
|
+
if "output_tokens" in counts:
|
|
259
|
+
usage["gen_ai.usage.output_tokens"] = counts["output_tokens"]
|
|
260
|
+
if "cache_read_tokens" in counts:
|
|
261
|
+
usage["gen_ai.usage.cache_read.input_tokens"] = counts["cache_read_tokens"]
|
|
262
|
+
if "cache_creation_tokens" in counts:
|
|
263
|
+
usage["gen_ai.usage.cache_creation.input_tokens"] = counts[
|
|
264
|
+
"cache_creation_tokens"
|
|
265
|
+
]
|
|
266
|
+
return usage
|
|
@@ -0,0 +1,133 @@
|
|
|
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
|
+
"""Settings every telemetry signal shares: names, resource, Telemetry API access."""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import logging
|
|
20
|
+
import os
|
|
21
|
+
import uuid
|
|
22
|
+
from typing import Any
|
|
23
|
+
|
|
24
|
+
from app.app_utils import settings
|
|
25
|
+
|
|
26
|
+
_TELEMETRY_ENDPOINT = "https://telemetry.googleapis.com"
|
|
27
|
+
_MTLS_TELEMETRY_ENDPOINT = "https://telemetry.mtls.googleapis.com"
|
|
28
|
+
|
|
29
|
+
FLUSH_TIMEOUT_MILLIS = 5_000
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def cloud_export_enabled() -> bool:
|
|
33
|
+
value = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY")
|
|
34
|
+
return value is None or value.lower() in ("true", "1")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def capture_content() -> bool:
|
|
38
|
+
"""Whether prompts, replies and tool arguments and results go into spans."""
|
|
39
|
+
capture = os.environ.get("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "")
|
|
40
|
+
return capture.lower() not in ("", "false", "no_content")
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def on_agent_runtime() -> bool:
|
|
44
|
+
return bool(os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID"))
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def agent_runtime_location() -> str:
|
|
48
|
+
return os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION") or os.environ.get(
|
|
49
|
+
"GOOGLE_CLOUD_LOCATION", ""
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def service_name() -> str:
|
|
54
|
+
return os.environ.get("OTEL_SERVICE_NAME") or os.environ.get(
|
|
55
|
+
"K_SERVICE", "claude-agent"
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def agent_name() -> str:
|
|
60
|
+
name = settings.AGENT_NAME
|
|
61
|
+
return service_name() if not name or "{{" in name else name
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def build_resource(project_id: str) -> Any:
|
|
65
|
+
"""Build the Resource; OTEL_* env vars, then GCP detection, override defaults."""
|
|
66
|
+
from opentelemetry.sdk.resources import OTELResourceDetector, Resource
|
|
67
|
+
|
|
68
|
+
resource = Resource.create(
|
|
69
|
+
{
|
|
70
|
+
"service.name": service_name(),
|
|
71
|
+
"service.version": os.environ.get("COMMIT_SHA", "dev"),
|
|
72
|
+
"service.instance.id": f"{uuid.uuid4().hex}-{os.getpid()}",
|
|
73
|
+
# The Telemetry API rejects spans whose resource lacks gcp.project_id.
|
|
74
|
+
"gcp.project_id": project_id,
|
|
75
|
+
"cloud.account.id": project_id,
|
|
76
|
+
}
|
|
77
|
+
)
|
|
78
|
+
resource = resource.merge(OTELResourceDetector().detect())
|
|
79
|
+
try:
|
|
80
|
+
from opentelemetry.resourcedetector.gcp_resource_detector import (
|
|
81
|
+
GoogleCloudResourceDetector,
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
resource = resource.merge(
|
|
85
|
+
GoogleCloudResourceDetector(raise_on_error=False).detect()
|
|
86
|
+
)
|
|
87
|
+
except Exception as e: # best-effort; unavailable off-GCP
|
|
88
|
+
logging.debug("GCP resource detection skipped: %s", e)
|
|
89
|
+
return resource
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def agent_runtime_attributes(project_id: str) -> dict[str, str]:
|
|
93
|
+
"""Span resource attributes for this Agent Runtime engine; empty elsewhere.
|
|
94
|
+
|
|
95
|
+
The Agent Runtime console finds an engine's traces by cloud.resource_id.
|
|
96
|
+
"""
|
|
97
|
+
engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")
|
|
98
|
+
if not engine_id:
|
|
99
|
+
return {}
|
|
100
|
+
location = agent_runtime_location()
|
|
101
|
+
attributes = {
|
|
102
|
+
"cloud.provider": "gcp",
|
|
103
|
+
"cloud.platform": "gcp.agent_engine",
|
|
104
|
+
"service.name": engine_id,
|
|
105
|
+
"service.version": os.environ.get(
|
|
106
|
+
"GOOGLE_CLOUD_AGENT_ENGINE_RUNTIME_REVISION_ID", ""
|
|
107
|
+
),
|
|
108
|
+
"cloud.region": location,
|
|
109
|
+
}
|
|
110
|
+
if location:
|
|
111
|
+
attributes["cloud.resource_id"] = (
|
|
112
|
+
f"//aiplatform.googleapis.com/projects/{project_id}"
|
|
113
|
+
f"/locations/{location}/reasoningEngines/{engine_id}"
|
|
114
|
+
)
|
|
115
|
+
return {key: value for key, value in attributes.items() if value}
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def telemetry_session(credentials: Any) -> tuple[Any, str]:
|
|
119
|
+
"""An authorized session for the Telemetry API, and the endpoint to use.
|
|
120
|
+
|
|
121
|
+
With a client certificate (Agent Identity on Agent Runtime), tokens are
|
|
122
|
+
bound to it and only accepted over mTLS. Make one session per exporter:
|
|
123
|
+
requests sessions aren't thread-safe.
|
|
124
|
+
"""
|
|
125
|
+
from google.auth.transport import mtls
|
|
126
|
+
from google.auth.transport.requests import AuthorizedSession
|
|
127
|
+
|
|
128
|
+
session = AuthorizedSession(credentials)
|
|
129
|
+
if mtls.should_use_client_cert():
|
|
130
|
+
session.configure_mtls_channel()
|
|
131
|
+
if session.is_mtls:
|
|
132
|
+
return session, _MTLS_TELEMETRY_ENDPOINT
|
|
133
|
+
return session, _TELEMETRY_ENDPOINT
|
|
@@ -0,0 +1,175 @@
|
|
|
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
|
+
"""Python log records and GenAI events, exported to Cloud Logging.
|
|
16
|
+
|
|
17
|
+
Nothing is sent until setup_cloud_logging() runs.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
import logging
|
|
23
|
+
import os
|
|
24
|
+
from collections.abc import Mapping
|
|
25
|
+
from typing import Any
|
|
26
|
+
|
|
27
|
+
from opentelemetry import context as otel_context
|
|
28
|
+
from opentelemetry._logs import LogRecord, SeverityNumber
|
|
29
|
+
|
|
30
|
+
from app.app_utils.telemetry import config
|
|
31
|
+
|
|
32
|
+
# Cloud Logging log names; GCP_DEFAULT_LOG_NAME overrides both.
|
|
33
|
+
_AGENT_RUNTIME_LOG_NAME = "aiplatform.googleapis.com/reasoning_engine_stdout"
|
|
34
|
+
_LOG_NAME = "adk-otel"
|
|
35
|
+
|
|
36
|
+
# GenAI events are emitted under the telemetry package's name.
|
|
37
|
+
_EVENT_LOGGER_NAME = __name__.rpartition(".")[0]
|
|
38
|
+
|
|
39
|
+
_logger_provider: Any = None
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def setup_cloud_logging(credentials: Any, resource: Any, project_id: str) -> Any:
|
|
43
|
+
"""Send Python log records to Cloud Logging too; return the LoggerProvider."""
|
|
44
|
+
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
|
|
45
|
+
from opentelemetry.sdk._logs import LoggerProvider
|
|
46
|
+
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
|
|
47
|
+
|
|
48
|
+
global _logger_provider
|
|
49
|
+
resource = _log_resource(resource, project_id)
|
|
50
|
+
session, upstream = config.telemetry_session(credentials)
|
|
51
|
+
logger_provider = LoggerProvider(resource=resource)
|
|
52
|
+
logger_provider.add_log_record_processor(
|
|
53
|
+
BatchLogRecordProcessor(
|
|
54
|
+
OTLPLogExporter(session=session, endpoint=f"{upstream}/v1/logs")
|
|
55
|
+
)
|
|
56
|
+
)
|
|
57
|
+
_install_handler(
|
|
58
|
+
_CloudLoggingHandler(
|
|
59
|
+
logger_provider,
|
|
60
|
+
{
|
|
61
|
+
"gcp.log_name": _log_name(),
|
|
62
|
+
# Cloud Logging drops resource attributes, so send it as a label.
|
|
63
|
+
"service.version": str(resource.attributes.get("service.version", "")),
|
|
64
|
+
},
|
|
65
|
+
)
|
|
66
|
+
)
|
|
67
|
+
_logger_provider = logger_provider
|
|
68
|
+
return logger_provider
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def emit_event(record: LogRecord) -> None:
|
|
72
|
+
"""Send a GenAI event to Cloud Logging, in a log named after `event.name`."""
|
|
73
|
+
if _logger_provider is None:
|
|
74
|
+
return
|
|
75
|
+
attributes = dict(record.attributes or {})
|
|
76
|
+
attributes["gcp.log_name"] = (
|
|
77
|
+
_AGENT_RUNTIME_LOG_NAME
|
|
78
|
+
if config.on_agent_runtime()
|
|
79
|
+
else attributes["event.name"]
|
|
80
|
+
)
|
|
81
|
+
record.attributes = attributes
|
|
82
|
+
_logger_provider.get_logger(_EVENT_LOGGER_NAME).emit(record)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _log_resource(resource: Any, project_id: str) -> Any:
|
|
86
|
+
"""On Agent Runtime, the resource that files logs under the engine."""
|
|
87
|
+
from opentelemetry.sdk.resources import Resource
|
|
88
|
+
|
|
89
|
+
engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")
|
|
90
|
+
if not engine_id:
|
|
91
|
+
return resource
|
|
92
|
+
# Logs only: on the metrics' resource, gcp.resource_type would move them
|
|
93
|
+
# off their monitored resource.
|
|
94
|
+
return resource.merge(
|
|
95
|
+
Resource(
|
|
96
|
+
{
|
|
97
|
+
"gcp.resource_type": "aiplatform.googleapis.com/ReasoningEngine",
|
|
98
|
+
"location": config.agent_runtime_location(),
|
|
99
|
+
"reasoning_engine_id": engine_id,
|
|
100
|
+
# Without "projects/" the Telemetry API rejects the records.
|
|
101
|
+
"resource_container": f"projects/{project_id}",
|
|
102
|
+
}
|
|
103
|
+
)
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _log_name() -> str:
|
|
108
|
+
return os.environ.get("GCP_DEFAULT_LOG_NAME") or (
|
|
109
|
+
_AGENT_RUNTIME_LOG_NAME if config.on_agent_runtime() else _LOG_NAME
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _install_handler(handler: logging.Handler) -> None:
|
|
114
|
+
root = logging.getLogger()
|
|
115
|
+
if not root.handlers:
|
|
116
|
+
# Keep stderr output, which Python drops once the root logger has a handler.
|
|
117
|
+
root.addHandler(logging.StreamHandler())
|
|
118
|
+
root.addHandler(handler)
|
|
119
|
+
# uvicorn's logger doesn't propagate; its access log is left out.
|
|
120
|
+
uvicorn = logging.getLogger("uvicorn")
|
|
121
|
+
if not uvicorn.propagate:
|
|
122
|
+
uvicorn.addHandler(handler)
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
_SEVERITIES = (
|
|
126
|
+
(logging.CRITICAL, SeverityNumber.FATAL, "FATAL"),
|
|
127
|
+
(logging.ERROR, SeverityNumber.ERROR, "ERROR"),
|
|
128
|
+
(logging.WARNING, SeverityNumber.WARN, "WARN"),
|
|
129
|
+
(logging.INFO, SeverityNumber.INFO, "INFO"),
|
|
130
|
+
(logging.NOTSET, SeverityNumber.DEBUG, "DEBUG"),
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
class _CloudLoggingHandler(logging.Handler):
|
|
135
|
+
"""Hands Python log records to `logger_provider`, under the active span.
|
|
136
|
+
|
|
137
|
+
`extra=` fields are not copied into attributes.
|
|
138
|
+
"""
|
|
139
|
+
|
|
140
|
+
def __init__(self, logger_provider: Any, attributes: Mapping[str, str]) -> None:
|
|
141
|
+
super().__init__()
|
|
142
|
+
self._logger_provider = logger_provider
|
|
143
|
+
self._attributes = dict(attributes)
|
|
144
|
+
|
|
145
|
+
def emit(self, record: logging.LogRecord) -> None:
|
|
146
|
+
# The OTel SDK's own records would feed back into the export.
|
|
147
|
+
if record.name.startswith("opentelemetry"):
|
|
148
|
+
return
|
|
149
|
+
try:
|
|
150
|
+
_, severity, severity_text = next(
|
|
151
|
+
s for s in _SEVERITIES if record.levelno >= s[0]
|
|
152
|
+
)
|
|
153
|
+
attributes: dict[str, Any] = {
|
|
154
|
+
**self._attributes,
|
|
155
|
+
"code.file.path": record.pathname,
|
|
156
|
+
"code.function.name": record.funcName,
|
|
157
|
+
"code.line.number": record.lineno,
|
|
158
|
+
}
|
|
159
|
+
if record.exc_info and record.exc_info[0]:
|
|
160
|
+
attributes["exception.type"] = record.exc_info[0].__name__
|
|
161
|
+
self._logger_provider.get_logger(record.name).emit(
|
|
162
|
+
LogRecord(
|
|
163
|
+
timestamp=int(record.created * 1e9),
|
|
164
|
+
context=otel_context.get_current(),
|
|
165
|
+
severity_number=severity,
|
|
166
|
+
severity_text=severity_text,
|
|
167
|
+
body=self.format(record),
|
|
168
|
+
attributes=attributes,
|
|
169
|
+
)
|
|
170
|
+
)
|
|
171
|
+
except Exception:
|
|
172
|
+
self.handleError(record)
|
|
173
|
+
|
|
174
|
+
def flush(self) -> None:
|
|
175
|
+
self._logger_provider.force_flush(config.FLUSH_TIMEOUT_MILLIS)
|