/workspace 和 ~/.claude 假设。运行 claude self-hosted-runner --help 以获取已安装版本上的权威列表。
指标系列和一些 API 字段仍然使用 pool 来表示这些页面所称的环境;两个术语都指同一事物。环境 ID 是 pool_id 字段,形式为 ccpool_...:无论这些页面在哪里显示 pool 标识符,它都命名环境。CLI 标志和环境变量将其拼写为 environment,例如 --environment-secret-file;已弃用的 pool 拼写仍然有效,如--environment-secret-file 行所述。
Runner CLI 标志
大多数标志都有对应的环境变量。两者同时设置时,标志优先。时长类标志在 CLI 中以分钟或秒为单位,但对应的环境变量始终以毫秒为单位(由_MS 后缀表示),而“默认值”列显示的是标志的单位:--exit-if-unused-min 10 等同于 SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000,而像 SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" 这样的 Helm 值表示 15 毫秒,而不是默认的 15 分钟。
大多数时长类标志都有上限,其选择是为了使每个超时都保持在运行时约 24.85 天的 32 位计时器上限之内。
--*-min 标志的上限为 10080 分钟,即 7 天;--drain-grace-sec 为 604800 秒,同样是 7 天;--drain-wait-sec 为 86400 秒,即 24 小时。--session-stop-grace-sec 和 --post-session-hook-timeout-sec 没有上限。超出上限时,不同使用方式的行为有所不同:
- 标志:启动失败并报错。
- 环境变量:runner 将该值截断为计时器上限,而不是拒绝它。
会话启动超时
如果会话在/code-review 等轮次中丢失了槽位,请将 runner 和子进程二进制文件更新到 v2.1.309 或更高版本。在 v2.1.299 至 v2.1.308 中,一旦启动超时已过且没有 user 或 assistant 消息,runner 就会释放会话,即使该会话正处于轮次中。
使用 --startup-timeout-min <n> 时,如果会话的子进程在克隆后 <n> 分钟内未完成初始化,runner 会释放该会话的槽位。在子进程初始化之前开始的轮次中,会话会保留其槽位,直到子进程的活动通道上连续 <n> 分钟没有任何输出行为止。子进程初始化后,runner 会清除该计时,改由 --release-idle-session-min 控制释放。要限制子进程仍存活但已卡住的会话,请设置 --kill-session-after-min。
自动模式规则列表
--server-auto-mode-lists 让您决定来自 runner 外部的哪些自动模式分类器规则可以作用于您的 runner 上的会话。Anthropic 的控制平面可以随会话发送规则列表,并请求 runner 应用它们。其中一些条目可能是您组织的管理员编写的规则。这些列表是 environment、soft_deny 和 allow:
environment:其中的条目既可以让分类器允许更多操作,也可以让其允许更少操作。soft_deny:其中的条目会阻止某项操作,除非用户明确要求执行该操作,或适用某个allow例外。allow:soft_deny条目的例外。
no-allow:默认值。应用environment和soft_deny,不应用allow。environment条目仍可能让分类器允许更多操作,因此默认值并不能排除所有放宽。all:应用全部三个列表。none:一个都不应用。若要排除来自这些列表的所有放宽,请选择none。这也会去掉soft_deny的限制。
--log-level debug 启动 runner。随后,runner 会为每个会话记录一行日志,其中包含 the server asked this runner to apply,或包含 the server did not ask this runner to apply the auto mode lists it sends。
Orchestrator CLI 标志
self-hosted-runner orchestrator 子命令(生成按需运行器)接受 --api-url、--environment-secret-file、--hooks-dir、--health-port 和 --log-level,与运行器具有相同的默认值,以及运行器的标志具有的相同环境变量(除了 --hooks-dir 是必需的,必须包含 spawn-runner 钩子)。它还采用自己的标志:
SCM 连接器标志
SCM 连接器不可用,因此请将本部分中的标志保持未设置。如果您设置--scm-connector-host,连接不会打开,编排器会继续重试。运行器仍然作为会话队列启动。
连接器是从编排器到 Anthropic 控制平面的常设 WebSocket 连接。它的设计目的是让托管的预会话流(例如存储库选择器和分支或 ref 解析器)能够到达仅从您的网络内部可路由的 GitHub Enterprise Server 主机。请参阅 GitHub Enterprise Server 页面上的网络要求,了解这些流需要什么。
在每次连接尝试时,编排器发送其现有的环境密钥,并使用指数退避自动重试,上限为 30 秒加抖动。
仅环境变量设置
这些运行器设置仅从环境读取,涵盖大多数部署保留在默认值的行为:遥测
会话子进程向 Anthropic 发送操作遥测,除非您关闭它。不发送代码或存储库内容。在运行器进程上设置遥测变量;运行器在应用服务器提供的环境变量后重新声明它们,因此操作员的设置始终优先。 一个控制特定于自托管环境:CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 选择加入 Datadog 操作指标,这在自托管环境中默认关闭。一般 Claude Code 遥测控制 DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_ERROR_REPORTING 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 适用于会话子进程,如环境变量参考中所述。CLAUDE_CODE_DISABLE_FEATURE_FLAGS 相关但不同:设置 CLAUDE_CODE_DISABLE_FEATURE_FLAGS=1 禁用功能标志获取,遥测保持开启,除非也设置了 DISABLE_TELEMETRY。CLAUDE_CODE_DISABLE_FEATURE_FLAGS 需要 Claude Code v2.1.319 或更高版本。
CLAUDE_CODE_ENABLE_TELEMETRY 无关:它启用 OpenTelemetry 导出到您自己的收集器,如监控中所述,不控制 Anthropic 的分析。
健康端点
运行器在完成注册并结束启动检查后,会在配置的健康端口上提供GET /healthz。从那时起,只要进程活跃,响应就是 200 OK,无论轮询循环处于什么状态,因此此端点上的 HTTP 探针仅检测死进程。JSON 正文描述当前状态:
last_poll_age_ms 设置警报,但不要在存活探针中使用它;存活探针应继续依据 HTTP 状态代码。该值是自上次成功轮询以来经过的时间,因此当运行器无法连接到 Anthropic 时它也会上升。在第一次轮询成功之前,last_poll_at 和 last_poll_age_ms 都是 null。要捕获从一开始就失败的轮询,还应针对 claude_code_self_hosted_runner_poll_errors_total 设置警报,该指标列在 Prometheus 指标下。
编排器自己的 /healthz(位于其健康端口上)始终返回 200。正文携带报告最近一次轮询是否成功的 connected 字段,加上 queue_counts 中的每个状态生成队列计数。要了解 connected 为何是 false,请读取顶层 last_error 字段,每次成功轮询都会将其重置为 null。使用 connected 而不是状态代码来控制就绪和警报。
当SCM 连接器被配置时,编排器的 /healthz 正文也携带 scm_connector_connected 和一个 scm_connector 对象,包含 connected、last_connected_at、last_error、reconnects 和 requests_forwarded。当未设置 --scm-connector-host 时,两个字段都是 null。
Prometheus 指标
每个运行器都在与/healthz 相同的端口上通过 GET /metrics 提供 Prometheus 指标。主要序列:
编排器在与其
/healthz 相同的端口上通过 GET /metrics 提供自己的序列:
对于自动扩缩,请选择与您的扩缩方式相匹配的序列,并在其输入扩缩器之前对其进行门控:
- 基于队列深度扩缩:将
claude_code_self_hosted_orchestrator_pool_pending_sessions输入您的 HPA 或 KEDA 扩缩器,而不是queue_pending_sessions。 - 基于容量扩缩:根据运行器的
active_sessions与capacity之比进行扩缩。 - 按
connected门控:按实例使用claude_code_self_hosted_orchestrator_connected == 1过滤查询,这样已断开连接的副本的陈旧值就不会输入扩缩器。
ignoreNullValues: "true" 下会将空结果读取为零并缩容;请在 ScaledObject 上设置 ignoreNullValues: "false",并可选择设置 fallback 副本下限。
以下 Prometheus Operator PodMonitor 涵盖这两个进程。它通过 app.kubernetes.io/part-of: claude-code-self-hosted-runner 标签以及 Kubernetes 方案所设置的命名 health 端口来选择 Pod;请调整命名空间以匹配您的部署:
示例告警规则
这些示例告警规则只是一个起点;请根据您的机群规模调整阈值:针对运行器丢失和会话等待进行告警
若要在运行器丢失、会话等待或编排器停机时收到告警,请在示例告警规则之外加载以下 Prometheus 告警规则:- 固定机群:
ClaudeRunnersBelowFloor - 按需运行器:
ClaudeOrchestratorSessionsWaiting、ClaudeOrchestratorQueueWaitHigh和ClaudeOrchestratorAbsent
固定机群丢失运行器时告警
当已注册且被抓取的运行器数量低于下限并持续 10 分钟时,ClaudeRunnersBelowFloor 会触发:
- 下限:将
expr中的2设置为副本数的一半左右,向上取整。如果有三个副本,则保留2,当只剩一个运行器或没有运行器时告警会触发。 - 命名空间:替换匹配器和
labels中的claude-runners,并为每个其他命名空间复制该告警。如果您的目标没有namespace标签,请删除该匹配器和该标签,否则告警会读取到 0 并触发。 ClaudeRunnerPollStale和ClaudeRunnerPollErrors:请保持从示例告警规则中加载它们,因为ClaudeRunnersBelowFloor仍会将无法轮询的运行器计入在内
会话等待按需运行器时告警
当等待运行器的会话数保持在 0 以上并持续 10 分钟时,ClaudeOrchestratorSessionsWaiting 会触发。当过去 10 分钟内超过 1% 的队列等待超过 160 秒,并且该情况持续 5 分钟时,ClaudeOrchestratorQueueWaitHigh 会触发:
- 阈值:如果始终有某个会话在等待,请将
ClaudeOrchestratorSessionsWaiting中的> 0提高到您通常看到的数量以上 ClaudeOrchestratorDisconnected:请保持从示例告警规则中加载它,因为在命名空间中最后一个编排器断开连接约 2 分钟后,ClaudeOrchestratorSessionsWaiting就会停止触发
编排器停机时告警
若要得知编排器本身已停机,请加载ClaudeOrchestratorAbsent。当命名空间中没有任何编排器被抓取并持续 5 分钟时,它会触发:
- 命名空间:将
claude-runners替换为编排器的命名空间,并为每个运行编排器的其他命名空间复制该告警。如果您的目标没有namespace标签,请删除该匹配器,否则告警会在 5 分钟后触发并一直保持。 - 不抓取编排器的 Prometheus 服务器:请不要将该告警放入它们的规则文件中,因为在这类服务器上它会在 5 分钟后触发并一直保持
- 不要依赖编排器的其他告警:它们读取的是编排器自身提供的指标。在编排器停机后约 10 分钟内,
ClaudeOrchestratorSessionsWaiting、ClaudeOrchestratorQueueWaitHigh以及编排器的示例告警规则都会停止触发。
透传会话子进程指标
每个会话都在其自己的子进程中运行,并拥有自己的 OpenTelemetry 指标;当--capacity 大于 1 时,运行器会改写这些子进程指标的暴露方式。在运行器主机上设置 OTEL_METRICS_EXPORTER=prometheus,并在会话的环境中设置 CLAUDE_CODE_ENABLE_TELEMETRY=1(例如通过您的包装脚本或运行器自身的环境,会话会继承该环境),即可在运行器自身的 /metrics 端点上与运行器的序列一起重新暴露每个子进程的计数器和仪表类指标。运行器会改写子进程的导出器,使其通过 OTLP 推送到健康端口上仅限环回的接收器,为每个序列添加 session_id 和 client_platform 标签,并在会话结束时清除该会话的序列。直方图不会透传,名称会与运行器自身前缀冲突的子进程指标将被丢弃。
在默认的 --capacity 1 下,不会进行这种改写:会话的子进程照常在端口 9464 上绑定自己的 Prometheus 端点。
将会话指标与运行器指标关联
若要查看空闲会话产生的成本,请在ccr_session_id 上将运行器的 claude_code_self_hosted_runner_session_idle_seconds 与 Claude Code 的成本指标关联。运行器的指标不带该标签,因此请使用 label_replace 为其添加一个,如以下查询所示:
claude_code_cost_usage_total。该查询适用于任何 --capacity。
session_id:在端口 9464 上,Claude Code 指标中的该标签保存的是 Claude Code 自己的session.id,它不与任何运行器序列匹配。基于它进行关联不会返回任何结果,因此请基于ccr_session_id进行关联。- Claude Code 指标没有
ccr_session_id:请检查OTEL_METRICS_INCLUDE_SESSION_ID是否未设置为false
会话生命周期计数器语义
sessions_started_total、sessions_completed_total、sessions_failed_total 和 sessions_interrupted_total 计数器根据每个会话的结束方式对其进行分类。每个生成的会话子进程都会在生成时递增 sessions_started_total,并在退出时恰好递增其他三个计数器中的一个,因此 sessions_started_total 减去其他三个计数器之和即等于当前正在运行的会话子进程数。
completed:会话正常结束。这包括子进程以代码0自行退出、会话在子进程仍处于连接状态时被归档或删除,以及运行器正常交还槽位:在空闲超时、退役时间或--kill-session-after-min限制时释放会话;启动超时;或轮询循环在子进程退出前注意到服务器端取消分配。递增sessions_completed_total。failed:子进程以非零代码自行退出,可能是崩溃,也可能是生成后的设置失败。递增sessions_failed_total。interrupted:运行器出于既非会话成功也非运行器故障的运维原因终止了子进程,例如排空,或者在会话的--kill-session-after-min限制之后的SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS宽限期结束时,终止仍在运行器上的会话。Kubernetes 滚动重启发送SIGTERM就是排空的一个例子。递增sessions_interrupted_total。
--kill-session-after-min 限制的会话,并将其计入 sessions_interrupted_total。
post-session hook 的 CLAUDE_RUNNER_EXIT_REASON 对正常交接的分类方式不同。该 hook 将以下情况报告为 interrupted,因为是运行器停止了子进程:释放、启动超时、服务器取消分配,以及轮询先注意到的归档或删除。这些计数器则将相同的事件记录为 completed,因为槽位已被正常交还。
如果您直接将 hook 回执与 sessions_completed_total 进行核对,会少计完成数。请使用 hook 获取针对每个会话的保证,使用计数器获取聚合速率。
在一次性环境中,即 --capacity 1 并使用默认的 --drain-grace-sec 0,每个运行器进程会在其唯一的会话结束后片刻退出。sessions_completed_total、sessions_failed_total 和 sessions_interrupted_total 仅在会话结束时(即该退出之前)递增,因此每 15 到 60 秒一次的 Prometheus 抓取很少能在运行器的序列消失之前捕获到该递增;这三个会话结束计数器就是本节其余部分所说的终结计数器。sessions_started_total 在生成时递增,并在会话的整个生命周期内保持可见,因此能可靠地出现,但在一次性环境中,它的含义更接近”当前正在运行的会话”,而不是累计计数。
请针对相应的目标使用此表中的序列,而不是终结计数器:
orchestrator_* 行仅存在于运行按需编排器的环境中。在运行器比其会话存活更久的固定机群上(--drain-grace-sec 大于 0),请使用 sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) 衡量吞吐量;在一次性机群上,该序列存在与终结计数器相同的抓取窗口问题,因此请改为依赖排队会话计数。请在 Cloud environments 管理页面上该环境的 Activity 选项卡中检查积压情况:运行器不导出队列深度序列。
如需按会话报告结果,请改用 post-session hook:根据 hook 自身的约定,除了运行器被突然终止(例如 VM 抢占)之外,它会在每个生成了子进程的会话结束时触发。