使用 OpenTelemetry 对 Google Antigravity CLI 进行监控
Antigravity CLI 是 Google 推出的终端编程智能体,也是 Gemini CLI 的继任者。它的智能体循环会规划和执行多步骤任务:读写和编辑文件、运行 shell 命令、调用 MCP 服务器,以及将任务委派给子智能体。但它没有任何机制来记录这些操作。Antigravity 没有内置 OpenTelemetry 导出器,相关功能请求仍在 antigravity-cli#366 中处于开放状态。
本指南利用 OpenTelemetry 来填补这一空白。Antigravity 自带一套钩子系统,会在工具调用完成、智能体循环每次迭代结束时以及对话轮次结束时触发事件。一段简短的钩子脚本即可将这些事件转换为 OTLP span,并对 Antigravity 用于计量使用的周配额进行采样。
通过在 SigNoz 中观测 Antigravity CLI,你可以查看智能体调用了哪些工具、每轮对话的智能体循环迭代次数、轮次结束的原因、实际处理请求的模型,以及周配额的消耗速度。
前置条件
- SigNoz 环境(二选一):
- 拥有活跃摄取密钥的 SigNoz Cloud 账户
- 自托管的 SigNoz 实例
- 在 macOS 或 Linux 上安装 Antigravity CLI(
agy) - Python 3.11 或更高版本
使用 OpenTelemetry 监控 Antigravity CLI
Antigravity 暴露了五种钩子事件。本方案注册其中三个被动事件(PostToolUse、PostInvocation 和 Stop),并将每个事件转换为 span。
步骤 1:将导出器安装在独立环境中,以避免影响系统 Python。
Copypython3 -m venv ~/.local/opt/agy-otel
~/.local/opt/agy-otel/bin/pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
步骤 2:将以下代码保存为 ~/.local/opt/agy-otel/hook.py。
#!/usr/bin/env python3
"""Antigravity CLI hook → OpenTelemetry span 导出器。
按事件注册在 ~/.gemini/config/hooks.json。事件名通过 argv[1] 传入,因为 Antigravity 的
hook 载荷里没有事件类型字段。
只支持被动事件:PostToolUse、PostInvocation 和 Stop。刻意排除了 PreToolUse,因为它的
`decision` 字段是必填的,而每个合法值都会改变权限行为,遥测 hook 无法以中立方式观察它。
"""
import json, os, sys, time, hashlib
PASSIVE_OUTPUT = {"PostToolUse": {}, "PostInvocation": {}, "Stop": {}}
CONFIG_PATH = os.path.expanduser("~/.config/agy-otel/env")
def load_config():
"""从配置文件读取 OTLP 设置。
交互式 `agy` 会话会继承启动它的 shell,所以 hook 不能依赖导出的环境变量。不这样做的话,
SDK 会静默回退到 localhost:4318,所有 span 都会因连接被拒而丢弃。真正的环境变量
仍然优先。
"""
try:
with open(CONFIG_PATH) as fh:
for line in fh:
line = line.strip()
if not line or line.startswith("#") or "=" not in line:
continue
key, val = line.split("=", 1)
os.environ.setdefault(key.strip(), val.strip())
except FileNotFoundError:
pass
QUOTA_STAMP = os.path.expanduser("~/.config/agy-otel/.quota-last")
QUOTA_MIN_INTERVAL = int(os.environ.get("AGY_OTEL_QUOTA_INTERVAL", "300"))
def _quota_due():
"""限制配额采样的频率:/usage 大约耗时 5 秒,而数值变化很慢。"""
try:
if time.time() - os.path.getmtime(QUOTA_STAMP) < QUOTA_MIN_INTERVAL:
return False
except OSError:
pass
try:
os.makedirs(os.path.dirname(QUOTA_STAMP), exist_ok=True)
open(QUOTA_STAMP, "w").close()
except OSError:
pass
return True
def emit_quota(meter):
"""执行 `agy -p /usage` 并记录每个 bucket 的剩余配额。
Antigravity 是固定费率订阅,不会向交互式会话暴露按 token 计费的成本,因此已消耗配额
是唯一可用的花费信号。该命令不会启动 agent 回合、不消耗配额、也不触发 hook,所以在
hook 内部调用是安全的。
"""
import json as _json
import subprocess
out = subprocess.run(["agy", "-p", "/usage", "--output-format", "json"],
capture_output=True, text=True, timeout=60).stdout
data = _json.loads(out, strict=False).get("command", {}).get("data", {})
remaining = meter.create_gauge(
"agy.quota.remaining_fraction", unit="1",
description="Antigravity 每周配额的剩余比例")
reset_in = meter.create_gauge(
"agy.quota.seconds_to_reset", unit="s",
description="Antigravity 配额窗口重置前的秒数")
now = time.time()
for group in data.get("groups", []):
for bucket in group.get("buckets", []):
attrs = {
"agy.quota.group": group.get("name", ""),
"agy.quota.bucket": bucket.get("id", ""),
"agy.quota.window": bucket.get("window", ""),
}
frac = bucket.get("remaining_fraction")
if frac is not None:
remaining.set(float(frac), attrs)
reset = bucket.get("reset_time")
if reset:
try:
from datetime import datetime, timezone
ts = datetime.fromisoformat(reset.replace("Z", "+00:00"))
reset_in.set(max(0.0, ts.timestamp() - now), attrs)
except Exception:
pass
def emit(event, payload):
# 在这里导入而不是在模块顶层:OpenTelemetry SDK 导入约需 200ms,且只有脱离的子进程
# 需要它,agent 循环因此不必等待。
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.trace import (SpanKind, SpanContext, TraceFlags,
NonRecordingSpan, set_span_in_context)
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
os.environ.setdefault("OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE", "delta")
conv = payload.get("conversationId") or "unknown"
resource = Resource.create({
"service.name": os.environ.get("OTEL_SERVICE_NAME", "antigravity-cli"),
})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
tracer = provider.get_tracer("antigravity-cli-hooks")
# hook 是独立进程,所以要从 conversationId 派生一个稳定的 trace id,把同一对话的
# span 归到一起。根 span 从不发送,因此 trace 会显示缺失根 span 的占位符,这是预期行为。
digest = hashlib.sha256(conv.encode()).hexdigest()
ctx = set_span_in_context(NonRecordingSpan(SpanContext(
trace_id=int(digest[:32], 16),
span_id=int(digest[32:48], 16),
is_remote=True,
trace_flags=TraceFlags(TraceFlags.SAMPLED),
)))
tool = payload.get("toolName") or (payload.get("toolCall") or {}).get("name")
if event == "PostToolUse":
name = f"execute_tool {tool or 'unknown'}"
op = "execute_tool"
elif event == "Stop":
name, op = "agy stop", "invoke_agent"
else:
name, op = "agy invocation", "invoke_agent"
now = time.time()
span = tracer.start_span(name, context=ctx, kind=SpanKind.INTERNAL,
start_time=int(now * 1e9))
span.set_attribute("gen_ai.operation.name", op)
span.set_attribute("gen_ai.provider.name", "gcp.gemini")
span.set_attribute("gen_ai.conversation.id", conv)
span.set_attribute("agy.hook.event", event)
if payload.get("modelName"):
span.set_attribute("gen_ai.request.model", payload["modelName"])
for key, attr in (("stepIdx", "agy.step.index"),
("invocationNum", "agy.invocation.num"),
("initialNumSteps", "agy.initial_num_steps"),
("executionNum", "agy.execution.num"),
("terminationReason", "agy.termination_reason"),
("fullyIdle", "agy.fully_idle")):
if payload.get(key) is not None:
span.set_attribute(attr, payload[key])
if tool:
span.set_attribute("gen_ai.tool.name", tool)
err = payload.get("error")
if err:
span.set_attribute("error.type", str(err)[:200])
span.set_status(trace.Status(trace.StatusCode.ERROR, str(err)[:200]))
span.end(end_time=int(now * 1e9))
provider.force_flush(2000)
provider.shutdown()
# 配额是交互式会话唯一可用的花费信号。
if event == "Stop" and _quota_due():
try:
mp = MeterProvider(resource=resource, metric_readers=[
PeriodicExportingMetricReader(OTLPMetricExporter(), 60000)])
emit_quota(mp.get_meter("antigravity-cli-quota"))
mp.force_flush(5000)
mp.shutdown()
except Exception:
pass
def main():
load_config()
event = sys.argv[1] if len(sys.argv) > 1 else "PostInvocation"
try:
raw = sys.stdin.read()
payload = json.loads(raw) if raw.strip() else {}
except Exception:
payload = {}
# Antigravity 同步运行 hook 并阻塞 agent 循环,而前台导出 OTLP 每次工具调用要花
# 0.5-1 秒。fork 出去,让父进程立即返回,子进程在后台发送 span。
try:
if os.fork() == 0:
os.setsid()
if os.fork() == 0:
try:
emit(event, payload)
finally:
os._exit(0)
os._exit(0)
else:
os.wait() # 回收短命的中间子进程
except Exception:
pass # 遥测失败绝不能打断 agent 循环
# 被动响应:必须是合法 JSON,且不能改变 agent 行为。
print(json.dumps(PASSIVE_OUTPUT.get(event, {})))
if __name__ == "__main__":
main()
展开 209 行
第 3 步: 将导出器配置写入 ~/.config/agy-otel/env 文件。
mkdir -p ~/.config/agy-otel
cat > ~/.config/agy-otel/env <<'EOF'
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.signoz.cloud:443
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<your-ingestion-key>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=antigravity-cli
EOF
chmod 600 ~/.config/agy-otel/env
请确认以下参数值:
<region>:你的 SigNoz Cloud 区域。<your-ingestion-key>:你的 SigNoz 数据接入密钥。
交互式的 agy 会话会继承启动它的 Shell 环境,因此 Hook 几乎无法读取你在终端中导出的 OTEL_EXPORTER_OTLP_* 变量。如果缺少此配置文件,SDK 会回退到 localhost:4318,导致所有 span 因连接被拒绝而丢弃,且 Agent 表现正常,表面上看不出任何异常。该文件保存的是
