← 文章 / AI技术
signoz 10天前 · 2026-11-12 18:45:34 · 13 阅读

使用 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。

Copy
python3 -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。

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

请确认以下参数值:

不要依赖导出的环境变量

交互式的 agy 会话会继承启动它的 Shell 环境,因此 Hook 几乎无法读取你在终端中导出的 OTEL_EXPORTER_OTLP_* 变量。如果缺少此配置文件,SDK 会回退到 localhost:4318,导致所有 span 因连接被拒绝而丢弃,且 Agent 表现正常,表面上看不出任何异常。该文件保存的是

原始来源: signoz

评论 (0)