这是面向贡献者的契约,规定 Core 如何观测 Runtime 并保留其历史。路由和响应字段见 Runtime telemetry API。代码位于 services/core/internal/runtimeobs(解析、源、采样器和导出)、services/core/internal/runtimehistory(历史查询和 PostgreSQL 存储)以及 services/core/internal/runtimeobs/otlpexporter。
观测属于遥测数据。它们绝不会创建、续期、唤醒、恢复或停止计算,绝不会影响 Session 活动,也绝不会决定空闲时间、挂起、准入或执行结果。
身份与源选择
在读取提供商之前,Core 会先把每次观测归属到持久化的 Core 身份:
managed: tenant_id -> session_id -> environment_id -> runtime_allocation_id
self-hosted: tenant_id -> session_id -> environment_id -> device_id + connection_generation
none: tenant_id -> session_id (no Session-owned Runtime instance)解析器(services/core/internal/deployment/observation.go)从数据库中读取 Session、其 Environment、当前分配以及 Session 的实测使用量。Session、守护进程连接、进程、容器和原生 Harness Session 是不同身份,彼此绝不能替代。
托管 microsandbox、E2B 和 OpenSandbox 分配均会被观测。none 和 self_hosted Session 为 unsupported;Core 绝不会将共享主机统计信息归属于 environment:none Session。
每个托管分配都通过部署所选的沙箱提供商读取;该提供商在返回数值前会验证分配的 installation(provider_key)以及分配标签或等效所有权数据。在读取任何提供商之前,部分行的结果由分配状态决定:处于 creating 状态或尚无分配时得到 allocation_pending,处于 cleanup_pending 或 released 状态时得到 runtime_not_running。提供商读取超出截止时间时得到 sample_timeout,返回未运行结果时得到 runtime_not_running,返回不可用结果时得到 sample_unavailable。任何其他错误、所有权不匹配或无效采样都会使读取失败。
Observe 属于 沙箱提供商协议;services/core/internal/runtimeobs/source.go 负责观测类型以及提供商的 Source 视图。Core 每页只加载一次所选提供商及其注册 kind,并在该页的每次读取中使用同一不可变提供商,用 Observe 读取每个运行中的目标。没有选择时,加载返回类型化的 ErrUnavailable,从而生成不含提供商类型的 sample_unavailable。其他加载错误遵循上述提供商读取错误规则。
观测的提供商类型即该注册 kind:microsandbox 或 e2b。重新配置会影响后续页面,但无法更改正在处理页面所选定的提供商类型或提供商。Generation 路由器仍会通过每个分配记录的部署代次解析该分配。
采样语义
一个采样包含:
observed_at,即提供商的观测时间;以及started_at,即当前计算实例启动周期的开始时间;- 累计 CPU 秒数,以及以核心数计的已配置 CPU 容量;
- 提供商报告的 CPU 利用率比率,仅适用于不提供累计 CPU 时间的提供商(E2B、OpenSandbox);
- 当前内存使用量,以及以字节计的内存限制;
- 当前磁盘使用量和容量,以字节计,且仅在提供商报告这些值时提供(E2B)。
每项测量都是可选的。存在的零值表示观测到零;缺失值表示不可用,绝不会显示或聚合为零。Core 会拒绝以下采样:observed_at 晚于 Core 自身时钟,started_at 晚于 observed_at,或任一值为负数、非有限值、容量或限制值为零,或超出 JSON 安全整数范围。
提供商映射
microsandbox
处于挂起状态的分配为 runtime_not_running,且不会调用 helper。否则,Core 会针对分配中记录的确切计算实例向 helper 发送 metrics 请求。在分配锁保护下,helper 通过固定版本 SDK 检查 sandbox 身份,运行固定版本的 msb metrics <name> --format json CLI 读取,再次检查身份;sandbox 必须处于 running 或 draining 状态。microsandbox helper 负责此请求。
累计 vCPU 时间、来宾内存使用量和有效内存限制均来自该次 CLI 采样。CPU 容量为部署中配置的 CPU 数量。started_at 等于采样自身的时间戳减去其毫秒级运行时长,绝不能从较晚读取的时钟值中减去已取整的运行时长;因此,恢复后的 generation 会重置计算运行时长,而分配时长会继续累计。不使用瞬时 CPU 百分比、主机内存、磁盘和网络值,磁盘为 null。对于关闭了挂起功能但未记录计算实例身份的分配,结果为 sample_unavailable;其他任何未记录计算实例身份的分配都会使读取失败;绝不会改用确定性 sandbox 名称。
E2B
Core 用一次 helper observe 请求读取一个分配:读取私有回执中指定 sandbox 的 E2B 指标,并按该分配的标签列出运行中的 sandbox,以确认该 sandbox。E2B helper 负责此请求。它绝不会连接、续期或更改 sandbox,也不会写入任何回执。
| E2B 值 | 采样字段 |
|---|---|
cpuUsedPct / 100 | CPU 利用率比率 |
cpuCount | CPU 容量 |
memUsed、memTotal | 内存使用量和限制 |
diskUsed、diskTotal | 磁盘使用量和容量;仅当两者都存在且总量非零时保留 |
E2B 不报告累计 CPU 时间,因此 CPU 秒数保持为 null。observed_at 为 E2B 的时间点;比 Core 时钟最多领先 30 秒的时间点按 Core 时间记录,领先幅度更大时则为 sample_unavailable。未出现在运行列表中的 sandbox 为 runtime_not_running。时间点缺失或格式错误、列表存在歧义以及 E2B API 失败(包括 key 被拒绝)均为 sample_unavailable。
OpenSandbox
Core 按所有权元数据列出该分配的 sandbox,并通过 OpenSandbox 服务器的代理读取 execd 的 GET /metrics。它绝不会续期或更改 sandbox。OpenSandbox adapter 指南说明了该 adapter。
| execd 值 | 采样字段 |
|---|---|
cpu_used_pct / 100 | CPU 利用率比率 |
cpu_count | CPU 容量 |
mem_used_mib、mem_total_mib | 内存使用量和限制,以字节计 |
Sandbox createdAt | started_at |
execd 不报告累计 CPU 时间和磁盘,因此 CPU 秒数和磁盘保持为 null。observed_at 为 execd 的 timestamp,领先 Core 时钟的 30 秒规则与 E2B 相同。缺失或未运行的 sandbox 为 runtime_not_running。读取失败或格式错误为 sample_unavailable。
读取预算
当前列表读取处理一页最多 100 个 Session(默认 20 个),提供商读取并发数最多为 8。每次提供商读取的时限为 2 秒,整个列表请求为 10 秒;超过这些时限时,列表返回 503。单 Session 读取的时限为 2 秒。一次请求内不会重试任何提供商调用,Core 也不保留观测缓存。
时长
以下时长回答不同问题,彼此保持独立:
- 分配时长:
runtime_allocations.created_at到released_at,或到当前时间; - 计算运行时长:采样的
started_at到observed_at; - 忙碌 Turn 时长:
turns.started_at到completed_at,或到当前时间。
CPU 静默状态、心跳时龄和连接状态都不是空闲时间。
保留的历史记录与可选导出
周期采样
周期采集在执行工作器中运行,并受其数据库租约保护。
采样器在启动时扫描一次,此后每次扫描结束后再经过一个采样间隔再次扫描。一次扫描按 Session ID 顺序,对未删除、状态为 openai_hosted 且没有已释放分配的 Session 执行 keyset 扫描。它通过与当前读取相同的解析器和源,以 32 个 Session 为一页进行读取,并发数为 8,每个源时限为 2 秒。采样器在每页之前以及扫描期间每 100 ms 检查租约;失去所有权时取消进行中的读取;将每条记录交给导出之前再次检查租约。失败的行不会停止扫描;未完成的扫描会在下一个间隔重复。
每次观测,无论来自当前读取还是周期采集,都会标记采集源 on_read 或 periodic,并放入每个导出器的有界队列。队列已满时会丢弃记录;该记录将成为缺失采样,而绝不会成为零。PostgreSQL 历史存储和可选 OTLP 导出器使用彼此独立的队列,因此导出器故障不会延迟本地历史记录或执行。导出器每次开始失败时记录一条警告,只包含导出器和结果类别,不包含其错误文本。Runtime 历史文件 用于设置采样间隔、队列容量、超时和 OTLP 目标。
存储的历史记录
PostgreSQL 存储仅保留周期性的 openai_hosted 记录,因此 API 读取无法虚增覆盖率。每条记录都会写入一行 runtime_history_samples,以租户、Session、Environment 和解析时间为键,包括分配信息、提供商类型、状态、观测时间与启动时间、CPU 秒数、容量和利用率比率、内存使用量和限制,以及实测 token 计数器。磁盘数据不存储。缺少 started_at 的采样仍计入覆盖范围,但会丢弃资源值,因为这些值无法关联到某次计算实例启动周期。
历史服务在查询前解析项目、Session 和 Environment;查询始终携带该作用域和有界时间范围,但绝不携带提供商身份。存储保留 7 天。单次读取最多覆盖 24 小时,最多读取 20,000 条原始采样,并从范围起点之前两个采样间隔处开始读取,以查找 CPU 基线;每个数组最多返回 1,000 个桶,最多返回 64 个序列,总点数最多 10,000 个。结果超出请求的作用域、时间范围或限制时,读取失败。API 的 Series 部分说明了聚合方式。
runtimehistory.Capabilities 声明采样间隔、7 天保留期、最小桶宽度(30 秒或采样间隔,取较长者)、24 小时范围和点数限制;这些值无效时 Core 不会启动。
清理循环每分钟运行一次,即使没有活跃 Runtime 也会运行。每轮最多耗时 2 秒,按每表 256 行的批次删除过期 Runtime 行和节点主机行,每张表最多 16 批。读取绝不会返回超过保留期的行。
节点主机历史记录
每次扫描结束后,Core 会在 2 秒内且在检查租约后,将每个新鲜节点心跳复制到 node_host_history_samples,其中包含主机 CPU 利用率、已用内存和可用磁盘,并以节点和心跳自身时间为键,因此重复扫描不会增加数据。心跳新鲜的判定条件是:其节点未被移除、在当前所有者 epoch 下处于连接状态、在过去 45 秒内被观察到,并且所报告的主机时间位于过去 45 秒内且不在未来。同样适用 7 天清理期。节点主机历史属于遥测数据,绝不作为调度或容量的权威依据,读取也绝不会对其进行采样或回填。
token 使用量
每次观测都携带来自 MeasuredSessionUsage 的 Session 实测使用量,即所有已记录根 Turn 快照之和,其中包含活跃 Turn。这不是公开的 Session 使用量规则,并且 Core 绝不会从提供商计数器、上下文占用量或成本推导令牌数。
OTLP 导出
配置 OTLP 端点后,Core 会将每条记录,包括 on_read 和 periodic,都导出为 OTLP/HTTP 指标。资源具有 service.name=oac-core 和 service.namespace=oac。
| 指标 | 聚合方式 | 来源 |
|---|---|---|
agents.runtime.cpu.usage | 单调累积和,秒 | 累计 CPU 计数器 |
agents.runtime.cpu.capacity | Gauge,核心数 | 已配置的 CPU 容量 |
agents.runtime.cpu.utilization | Gauge,比率 | 提供商报告的 CPU 占比(E2B、OpenSandbox) |
agents.runtime.memory.usage | Gauge,字节 | 内存使用量 |
agents.runtime.memory.limit | Gauge,字节 | 内存限制 |
agents.session.tokens.input | Gauge,token | 实测 Session 输入 token |
agents.session.tokens.output | Gauge,token | 实测 Session 输出 token |
agents.runtime.sample | 单调差值和 | 每个经验证的结果一条,包括 unavailable 和 unsupported |
agents.runtime.sample.duration | Delta 直方图,秒 | 提供商读取时长 |
仅当采样包含 started_at 时才导出 CPU 和内存数据点;缺少测量值不会产生数据点。属性包括 agents.tenant.id、agents.session.id、agents.environment.id、agents.runtime.allocation.id、agents.runtime.mode、agents.runtime.provider.type、agents.runtime.status、agents.runtime.reason、agents.runtime.collection.source,以及以纳秒为单位的 agents.runtime.resolved_at_unix_nano、agents.runtime.observed_at_unix_nano 和 agents.runtime.compute.started_at_unix_nano。这些纳秒时间使记录在后端以较低精度存储事件时间时仍可关联。提供商 key、回执、原生标识符、原始错误、路径和凭据绝不会作为属性。
Web 仅通过 Core 读取历史记录;其图表不需要 Collector 或其他指标存储。