跳转到正文

ADR 0064: 指标与日志批次走数据通道上的遥测流,日志在 agent 侧有界缓冲

本文目录

日期:2026-11-13 · 状态:已接受(补充 ADR 0024)

背景

指标批次(metrics)和容器、节点、agent 的日志批次(logs)原来都是 ctrl 流上的 JSON 信封,与心跳、RPC 应答共用同一条 yamux 流和 agent 的写锁。ctrl 通道是固定 256 KiB 窗口的小窗口通道,于是 RPC 应答最多要排在一个窗口的日志之后。实测(40 ms RTT,节点的两条通道共享一条链路,TestNoisyNodeCtrlLatency):日志刷得多的节点,RPC 往返 p50 在 2 Mbps 下是 954 ms,同条件下安静节点是 58 ms;10 Mbps 下是 145 ms 对 45 ms。

agent 没有连接时直接丢掉要发的批次。实测(TestInstanceLogsWrittenWhileTheServerIsDownReachTheLogCenter)server 停 5 秒,实例在这段时间以及节点重新上线前写的约 120 行日志永久缺失,日志中心看不出这里有缺口(GWKS-258)。

proto 里还声明过一个 metrics 流类型,但从来没有代码打开它,已删除。

决策

  1. 遥测流。 新增流类型 telemetry,由 agent 在数据通道上主动打开,承载 metrics 与 logs 两种信封(JSON Lines,与 ctrl 上的格式相同)。每个数据通道上每种批次各一条,流头的 ref 写明是 metrics 还是 logs,首次使用时打开,数据通道换新时随之换新。分成两条是为了让 server 等待日志入库时(第 5 条)不拖住指标:指标还供监控页与网关的负载判断使用。server 只接受 agent 在数据通道上打开这一种流且 ref 必须是这两者之一,否则 reset;同一种批次的新流要等前一条流的行读完才开始读,保证按发送顺序入库;遥测流上的其他信封不处理,单行超过 128 MiB 时 reset 这条流。
  2. 能力位。 server 在自己的 hello 里宣告 telemetry.stream。agent 只在 server 宣告了这一能力时才使用遥测流;老 server 收到的批次仍然走 ctrl,行为与以前一致。
  3. 按连接选路,不回退 ctrl。 agent 在握手后就知道这条连接会不会有数据通道(server 下发了 session ID,且 agent 自己拨数据通道,或 server_dial 由 server 拨回)。不会有的(老 server、--data-lane=false),批次走 ctrl。会有的,等数据通道连上再走遥测流,期间发送返回 conn.ErrTelemetryUnavailable,不先挤上 ctrl——重连后要补发的积压正是这时最大。数据通道 30 秒内都没连上(例如网络只放行了 ctrl),这条连接的遥测先走 ctrl,等数据通道连上再切过去,只切这一次;切换的那一刻,ctrl 上最后几批与遥测流上头几批由 server 不同 goroutine 读取,同一毫秒的日志行可能前后颠倒(日志按时间戳排序,影响仅限于此)。回退到 ctrl 时 agent 记一条 warn 日志(data lane did not attach; telemetry uses ctrl until it does),可在日志中心按来源 agent 检索。选定数据通道后它再断开,同 ADR 0024,发送返回 conn.ErrTelemetryUnavailable,不改走 ctrl。
  4. 日志有界缓冲。 agent 把日志批次先放进内存中的先进先出缓冲(上限 16 MiB,按每行文本加固定开销估算),能发时按顺序发出;发不出(无连接、数据通道未连上或断开)时保留,重连(Bind,在后台进行,不耽误连接自己的心跳与读循环)时以及每 2 秒重试一次;每一轮只发它开始时已在队列里的批次,不替别的写入者没完没了地清空。缓冲满时丢最旧的批次,但不丢正在发送的那一批,也不因刚放进来的那一批本身而丢它(单批超过上限时,只要发出之前没有更新的批次进来,就照样整批发出;上限约束的是断线积压);被丢的行按实例和来源合并成一条 warn 级标记行(gpuworks: N log lines from <起> to <止> were dropped: …),排在幸存日志之前发出,日志中心能看到缺口。发送在链路上阻塞时,后来的日志写入者排队等待,压力照旧经由 docker logs -f 管道反压到容器,不额外丢行。
  5. server 端不再丢遥测流上的日志。 ctrl 上的日志在 server 入库队列满时整批丢弃并计数(不能让 ctrl 读循环等)。遥测流是这个 agent 独占的,server 在入库队列满时等待,等待经 yamux 流控传回 agent,日志留在 agent 的缓冲里,满了才按第 4 条丢弃并留下标记。server 只处理以换行结尾的完整行:agent 在一次写入报错(例如 server 等待超过 30 秒的写超时)后关闭(不是 reset)这条流,再在新流上重发该批;关闭让 server 仍能读完已收到的完整行,被截断的末行不算送达。会话结束时,已读出、正在等入库的批次还有 10 秒余量。
  6. 指标不缓冲。 指标仍是尽力而为,无连接、或数据通道未连上/断开时直接丢弃,不记警告:过期的采样对监控页没有用,而它们会和日志抢缓冲空间。

结果

同样的测量下,日志刷得多的节点 RPC p50 在 2 Mbps 下是 72 ms(安静节点 57 ms),10 Mbps 下 48 ms(45 ms)。server 停 5 秒期间实例写的日志在重连后全部补上,序号无缺口。

代价与不做的事

  • 缓冲在内存中:agent 进程重启会丢掉还没发出的日志。要做到持久与至少一次,需要落盘加 server 回执,那是另一份设计(HA 分支上有一套进行中的实现)。
  • 没有回执:一批日志写进流(进入 yamux 发送缓冲)后算已发出。紧接着数据通道断开、server 收到但还没入库时挂掉、或 server 等入库空间期间会话结束且 10 秒内仍没有空间,这批日志以及已进入 server 接收窗口、排在它后面的批次仍然会丢(最后一种只在 server 的丢弃计数里留下记录)。这三种情况都需要回执才能消除,这里不做。
  • 每条连接开始时,在数据通道连上之前(通常不到一秒)产生的指标会丢掉。
  • 与 benchPending(评测状态的少量待发列表)是两个缓冲:那个按条数,这个按字节并要记录丢弃,需求不同,未合并。
  • 不对实例日志额外限速:日志离开 ctrl 后,量大的节点不再拖慢自己的 RPC,限速的必要性随之消失(GWKS-259)。
  • 单通道节点(老 server、--data-lane=false)仍然在 ctrl 上发遥测,延迟特性不变;缓冲对它们同样生效。

这篇文档有帮助吗?