Referência de ambientes auto-hospedados

Referência completa para o executor e orquestrador auto-hospedados: sinalizadores CLI, variáveis de ambiente e métricas Prometheus.

[!NOTE]

Ambientes auto-hospedados estão em beta pública em planos Team e Enterprise; um Proprietário os habilita ativando Permitir ambientes auto-hospedados na página de administração Ambientes na nuvem. Esta página é a referência de sinalizadores e métricas; consulte o guia de início rápido para configuração e Implantar em produção para as receitas de frota.

Esta página é a referência para os dois processos que você executa em um ambiente auto-hospedado: o executor, que executa sessões na nuvem do Claude Code em seus hosts, e o orquestrador de dimensionamento automático opcional, que inicia executores conforme as sessões são enfileiradas. Cada um tem sua própria tabela de sinalizadores. Ambos são executados em hosts Linux ou macOS, que os padrões como /workspace e ~/.claude assumem. Execute claude self-hosted-runner --help para a lista autoritativa em sua versão instalada.

Séries de métricas e alguns campos de API ainda usam pool para o que estas páginas chamam de ambiente; ambos os termos nomeiam a mesma coisa. O ID do ambiente é o campo pool_id, com a forma ccpool_...: onde quer que estas páginas mostrem um identificador pool, ele nomeia o ambiente. Sinalizadores CLI e variáveis de ambiente o escrevem como environment, como --environment-secret-file; as grafias pool descontinuadas ainda funcionam, como a linha --environment-secret-file descreve.

Sinalizadores CLI do executor

A maioria dos sinalizadores tem uma variável de ambiente correspondente. Quando ambos estão definidos, o sinalizador tem precedência. Sinalizadores de duração usam minutos ou segundos na CLI, mas a variável de ambiente emparelhada está sempre em milissegundos, indicada pelo sufixo _MS, e a coluna Padrão mostra a unidade do sinalizador: --exit-if-unused-min 10 é equivalente a SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, e um valor Helm como SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" significa 15 milissegundos, não o padrão de 15 minutos.

A maioria dos sinalizadores de duração tem um máximo, escolhido para manter cada tempo limite dentro do teto do temporizador de 32 bits do tempo de execução de aproximadamente 24,85 dias. Os sinalizadores --*-min limitam a 10080 minutos, 7 dias; --drain-grace-sec a 604800 segundos, também 7 dias; e --drain-wait-sec a 86400 segundos, 24 horas. --session-stop-grace-sec e --post-session-hook-timeout-sec não têm limite. Exceder um limite se comporta diferentemente por superfície:

• Sinalizador: a inicialização falha com um erro.
• Variável de ambiente: o executor fixa o valor ao teto do temporizador em vez de rejeitá-lo.

Timeout de inicialização da sessão

Se uma sessão perdeu seu slot durante um turno como /code-review, atualize o executor e o binário filho para a v2.1.309 ou posterior. Da v2.1.299 até a v2.1.308, o executor liberava uma sessão, mesmo no meio de um turno, assim que o timeout de inicialização passava sem uma mensagem user ou assistant.

Com --startup-timeout-min <n>, o executor libera o slot de uma sessão quando seu filho não inicializou dentro de <n> minutos após a clonagem. Durante um turno que começa antes de o filho inicializar, a sessão mantém seu slot até que <n> minutos se passem sem nenhuma linha no canal de atividade do filho. Assim que o filho inicializa, o executor zera essa contagem e --release-idle-session-min governa a liberação. Para limitar uma sessão cujo filho está vivo, mas travado, defina --kill-session-after-min.

Listas de regras do modo auto

--server-auto-mode-lists permite que você decida quais regras do classificador do modo auto vindas de fora do executor chegam às sessões nos seus executores. O plano de controle da Anthropic pode enviar listas de regras com uma sessão e pedir ao executor que as aplique. Algumas entradas podem ser regras que um administrador da sua organização escreveu. As listas são environment, soft_deny e allow:

• environment: uma entrada pode fazer o classificador permitir mais, assim como menos.
• soft_deny: uma entrada bloqueia uma ação, a menos que o usuário a tenha solicitado explicitamente ou uma exceção allow se aplique.
• allow: as exceções às entradas soft_deny.

O valor da flag escolhe quais listas o executor aplica:

• no-allow: o padrão. Aplica environment e soft_deny e retém allow. Uma entrada environment ainda pode fazer o classificador permitir mais, então o padrão não descarta todo afrouxamento.
• all: aplica as três listas.
• none: não aplica nenhuma delas. Escolha none para descartar todo afrouxamento vindo dessas listas. Isso também remove as restrições de soft_deny.

Nenhuma configuração do executor faz o plano de controle pedir ao executor que aplique as listas. Quando ele não pede, as sessões não recebem nenhuma lista, seja qual for o valor que você definir. Para ver o que aconteceu, inicie o executor com --log-level debug. Para cada sessão, o executor então registra em log uma linha contendo the server asked this runner to apply, ou uma contendo the server did not ask this runner to apply the auto mode lists it sends.

Sinalizadores CLI do orquestrador

O subcomando self-hosted-runner orchestrator, que gera executores sob demanda, aceita --api-url, --environment-secret-file, --hooks-dir, --health-port e --log-level com os mesmos padrões que o executor e, onde o sinalizador do executor tem um, a mesma variável de ambiente, exceto que --hooks-dir é obrigatório e deve conter um hook spawn-runner. Também usa seus próprios sinalizadores:

Sinalizadores do conector SCM

O conector SCM não está disponível, portanto deixe os sinalizadores nesta seção não definidos. Se você definir --scm-connector-host, a conexão não abre e o orquestrador continua tentando novamente. Os executores ainda iniciam conforme a fila de sessões.

O conector é uma conexão WebSocket permanente do orquestrador para o plano de controle da Anthropic. Ele foi projetado para permitir que fluxos pré-sessão hospedados, como o seletor de repositório e o resolvedor de branch ou ref, alcancem um host GitHub Enterprise Server que é apenas roteável de dentro de sua rede. Consulte Requisitos de rede na página GitHub Enterprise Server para saber o que esses fluxos precisam.

Em cada tentativa de conexão, o orquestrador envia seu segredo de ambiente existente e tenta novamente automaticamente com backoff exponencial, limitado a 30 segundos mais jitter.

Configurações somente por variável de ambiente

Estas configurações do runner são lidas apenas do ambiente e abrangem comportamentos que a maioria das implantações mantém no padrão:

Telemetria

Filhos de sessão enviam telemetria operacional para Anthropic a menos que você a desative. Nenhum código ou conteúdo de repositório é enviado. Defina variáveis de telemetria no processo do executor; o executor as re-afirma após aplicar variáveis de ambiente fornecidas pelo servidor, então a configuração do operador sempre tem precedência.

Um controle é específico para ambientes auto-hospedados: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 opta por métricas operacionais Datadog, que estão desligadas por padrão em ambientes auto-hospedados. Os controles gerais de telemetria Claude Code, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING e CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, se aplicam a filhos de sessão conforme documentado na referência de variável de ambiente. DISABLE_GROWTHBOOK é relacionado mas diferente: definir DISABLE_GROWTHBOOK=1 desabilita a busca de sinalizador de recurso, e a telemetria permanece ativada a menos que DISABLE_TELEMETRY também esteja definido.

CLAUDE_CODE_ENABLE_TELEMETRY não está relacionado: habilita a exportação OpenTelemetry para seu próprio coletor, conforme descrito em Monitoring, e não controla a análise da Anthropic.

Ponto de extremidade de saúde

O executor serve GET /healthz na porta de saúde configurada. A resposta é 200 OK sempre que o processo está vivo, seja qual for o estado do loop de pesquisa, então uma sonda HTTP neste ponto de extremidade detecta apenas um processo morto. O corpo JSON descreve o estado atual:

{
  "status": "ok",
  "runner_id": "ccrunner_...",
  "active_sessions": 2,
  "last_poll_at": "2026-03-31T18:04:11.220Z",
  "last_poll_age_ms": 842
}

Configure alertas com base em last_poll_age_ms, mas não o use em uma sonda de vivacidade; mantenha essa sonda no código de status HTTP. O valor é o tempo desde a última pesquisa bem-sucedida, portanto ele também aumenta enquanto o executor não consegue alcançar a Anthropic. Tanto last_poll_at quanto last_poll_age_ms são null até a primeira pesquisa ser bem-sucedida. Para detectar pesquisas que falham desde o início, configure também alertas em claude_code_self_hosted_runner_poll_errors_total, listada em métricas do Prometheus.

O próprio /healthz do orquestrador, em sua porta de saúde, sempre retorna 200. O corpo carrega um campo connected relatando se a pesquisa mais recente foi bem-sucedida, mais contagens de fila de geração por estado em queue_counts. Para ver por que connected é false, leia o campo de nível superior last_error, que cada pesquisa bem-sucedida redefine para null. Controle prontidão e alertas em connected em vez do código de status.

Quando o conector SCM está configurado, o corpo /healthz do orquestrador também carrega scm_connector_connected e um objeto scm_connector com connected, last_connected_at, last_error, reconnects e requests_forwarded. Ambos os campos são null quando --scm-connector-host não está definido.

Métricas Prometheus

Cada executor serve métricas Prometheus em GET /metrics na mesma porta que /healthz. Séries principais:

O orquestrador serve suas próprias séries em GET /metrics na mesma porta que seu /healthz:

Para dimensionamento automático, escolha a série que corresponde ao seu estilo de dimensionamento e controle-a antes de alimentar o escalador:

• Dimensionamento de profundidade de fila: alimente claude_code_self_hosted_orchestrator_pool_pending_sessions em seu escalador HPA ou KEDA, não queue_pending_sessions.
• Dimensionamento de capacidade: dimensione na proporção de active_sessions do executor para capacity.
• Controle em connected: filtre a consulta com claude_code_self_hosted_orchestrator_connected == 1 por instância, para que o valor obsoleto de uma réplica desconectada não alimente o escalador.

Durante uma interrupção completa de pesquisa, cada réplica desconectada, a consulta controlada não retorna dados. HPA mantém a contagem de réplica atual em uma métrica ausente, mas o escalador Prometheus do KEDA em seu padrão ignoreNullValues: "true" lê o resultado vazio como zero e reduz; defina ignoreNullValues: "false" no ScaledObject, opcionalmente com um piso de réplica fallback.

O seguinte PodMonitor do Prometheus Operator cobre ambos os processos. Ele seleciona pods pelo rótulo app.kubernetes.io/part-of: claude-code-self-hosted-runner e a porta nomeada health que a receita Kubernetes define; ajuste os namespaces para corresponder à sua implantação:

# Exemplo de PodMonitor do Prometheus Operator para o executor +
# orquestrador auto-hospedado Claude Code. Ajuste o namespace e os seletores
# de rótulo para corresponder à sua implantação. Tanto o executor quanto o
# orquestrador servem /metrics em seu --health-port (padrão 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Corresponde ao Deployment do executor da receita Kubernetes, mais
      # qualquer Job de executor sob demanda e pods do orquestrador que você
      # rotula da mesma forma e dá uma containerPort 'health' nomeada.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Regras de alerta de exemplo

Essas regras de alerta de exemplo são um ponto de partida; ajuste os limites para o tamanho da sua frota:

# Exemplo de regras de alerta Prometheus para o executor + orquestrador
# auto-hospedado Claude Code. Ajuste os limites para o tamanho da sua frota
# e SLOs.
groups:
  - name: claude-code-self-hosted-runner
    rules:
      - alert: ClaudeRunnerPollStale
        expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Executor {{ $labels.pod }} não pesquisou em >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Executores estão executando versões mistas"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_init_errors_total[10m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Sessões estão falhando antes da inicialização (hook de checkout / git / token / falha pré-inicialização)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Executor {{ $labels.pod }}: PollWork falhando ({{ $value | humanize }}/s em 5m)"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Hooks SessionStart estão falhando"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orquestrador {{ $labels.pod }} não consegue alcançar o plano de controle Anthropic"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orquestrador {{ $labels.pod }} não pesquisou em >90s (loop de pesquisa aguarda execução de hook)"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: max by (namespace) (claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions and on (instance) max_over_time(claude_code_self_hosted_orchestrator_connected[2m]) == 1) > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "Sessões impedidas de serem geradas: {{ $value }}. Leia o erro de cada uma na aba Activity, corrija a causa e então selecione Retry"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orquestrador {{ $labels.pod }}: PollSpawnHints falhando ({{ $value | humanize }}/s em 5m)"
      - alert: ClaudeOrchestratorSpawnHookFailing
        expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Orquestrador {{ $labels.pod }}: >3 falhas de hook spawn-runner em 5m"

Alertar sobre executores perdidos e sessões em espera

Para ser alertado quando executores forem perdidos, sessões aguardarem ou o orquestrador estiver fora do ar, carregue estas regras de alerta do Prometheus ao lado das regras de alerta de exemplo:

• Frota fixa: ClaudeRunnersBelowFloor
• Executores sob demanda: ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh e ClaudeOrchestratorAbsent

Alertar quando uma frota fixa perde executores

ClaudeRunnersBelowFloor dispara quando restam menos executores registrados e raspados do que o piso por 10 minutos:

groups:
  # Apenas frotas fixas. Com executores sob demanda, a contagem acompanha a demanda,
  # então ClaudeRunnersBelowFloor dispararia sempre que a demanda fosse baixa.
  - name: claude-code-self-hosted-fixed-fleet-capacity
    rules:
      - alert: ClaudeRunnersBelowFloor
        expr: (count(claude_code_self_hosted_runner_info{namespace="claude-runners"}) or vector(0)) < 2
        for: 10m
        labels: {severity: critical, namespace: claude-runners}
        annotations:
          summary: "Executores registrados e raspados: {{ $value }}, abaixo do piso. Verifique primeiro as cargas de trabalho dos executores e, se todas estiverem em execução, os alvos de raspagem."

• Piso: defina o 2 em expr para cerca de metade da sua contagem de réplicas, arredondado para cima. Com três réplicas, mantenha 2, e o alerta dispara quando resta um executor ou nenhum.
• Namespace: substitua claude-runners no matcher e em labels, e copie o alerta para cada namespace adicional. Se seus alvos não tiverem o rótulo namespace, remova o matcher e o rótulo, ou o alerta lerá 0 e disparará.
• ClaudeRunnerPollStale e ClaudeRunnerPollErrors: mantenha-os carregados a partir das regras de alerta de exemplo, porque ClaudeRunnersBelowFloor ainda conta um executor que não consegue pesquisar

Alertar quando sessões aguardam executores sob demanda

ClaudeOrchestratorSessionsWaiting dispara quando o número de sessões aguardando um executor permanece acima de 0 por 10 minutos. ClaudeOrchestratorQueueWaitHigh dispara quando mais de 1% das esperas na fila nos últimos 10 minutos excederam 160 segundos, e isso se mantém por 5 minutos:

groups:
  # Apenas executores sob demanda. Não precisa de edição para o namespace.
  - name: claude-code-self-hosted-on-demand-capacity
    rules:
      - alert: ClaudeOrchestratorSessionsWaiting
        expr: |
          max by (namespace) (
            claude_code_self_hosted_orchestrator_pool_pending_sessions
            and on (instance)
            max_over_time(claude_code_self_hosted_orchestrator_connected[2m]) == 1
          ) > 0
        for: 10m
        labels: {severity: warning}
        annotations:
          summary: "Sessões aguardando um executor: {{ $value }}, acima do limite por 10 minutos. Verifique claude_code_self_hosted_orchestrator_spawn_hooks_total por resultado e, em seguida, as cargas de trabalho dos executores que não iniciam."
      - alert: ClaudeOrchestratorQueueWaitHigh
        expr: |
          histogram_quantile(0.99, sum by (namespace, le) (
            rate(claude_code_self_hosted_orchestrator_session_queue_wait_seconds_bucket[10m])
          )) > 160
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Mais de 1% das esperas na fila nos últimos 10 minutos excederam 160 segundos. Verifique se ClaudeOrchestratorDisconnected está disparando e, em seguida, claude_code_self_hosted_orchestrator_spawn_hooks_total por resultado e claude_code_self_hosted_orchestrator_spawn_hook_duration_seconds."

• Limite: se alguma sessão estiver sempre aguardando, aumente o > 0 em ClaudeOrchestratorSessionsWaiting para acima do número que você normalmente vê
• ClaudeOrchestratorDisconnected: mantenha-o carregado a partir das regras de alerta de exemplo, porque ClaudeOrchestratorSessionsWaiting para de disparar cerca de 2 minutos após o último orquestrador no namespace se desconectar

Alertar quando o orquestrador está fora do ar

Para saber quando o próprio orquestrador está fora do ar, carregue ClaudeOrchestratorAbsent. Ele dispara quando nenhum orquestrador no namespace foi raspado por 5 minutos:

groups:
  # Apenas executores sob demanda. Substitua claude-runners pelo namespace do orquestrador.
  - name: claude-code-self-hosted-on-demand-orchestrator
    rules:
      - alert: ClaudeOrchestratorAbsent
        expr: absent(claude_code_self_hosted_orchestrator_connected{namespace="claude-runners"})
        for: 5m
        labels: {severity: critical}
        annotations:
          summary: "Nenhum orquestrador foi raspado por 5 minutos. Se ele estiver fora do ar, nenhum executor sob demanda inicia e as sessões ficam aguardando. Verifique primeiro a carga de trabalho do orquestrador e, se ela estiver em execução, o alvo de raspagem dele."

• Namespace: substitua claude-runners pelo namespace do orquestrador, e copie o alerta para cada namespace adicional que executa um orquestrador. Se seus alvos não tiverem o rótulo namespace, remova o matcher, ou o alerta disparará após 5 minutos e permanecerá ativo.
• Servidores Prometheus que não raspam o orquestrador: deixe o alerta fora dos arquivos de regras deles, porque em um servidor assim ele dispara após 5 minutos e permanece ativo
• Não dependa dos outros alertas do orquestrador: eles leem métricas que o próprio orquestrador serve. ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh e as regras de alerta de exemplo do orquestrador param de disparar em cerca de 10 minutos depois que o orquestrador fica fora do ar.

Passar através de métricas de filho de sessão

Cada sessão é executada em seu próprio processo filho com suas próprias métricas OpenTelemetry; em --capacity acima de um, o executor reescreve como essas métricas de filho são expostas. Definir OTEL_METRICS_EXPORTER=prometheus no host do executor e CLAUDE_CODE_ENABLE_TELEMETRY=1 no ambiente da sessão, por exemplo a partir de seu script wrapper ou do próprio ambiente do executor, que as sessões herdam, re-expõe cada instrumento de contador e medidor do filho no ponto de extremidade /metrics do próprio executor, ao lado das séries do executor. O executor reescreve o exportador do filho para enviar por OTLP para um receptor somente de loopback na porta de saúde, marca cada série com rótulos session_id e client_platform, e remove as séries de uma sessão quando essa sessão termina. Histogramas não passam, e uma métrica de filho cujo nome colidiria com o prefixo do próprio executor é descartada.

No padrão --capacity 1, a reescrita não se aplica: o filho da sessão vincula seu próprio ponto de extremidade Prometheus na porta 9464 como usual.

Associar as métricas de uma sessão às do executor

Para ver quanto as sessões ociosas custaram, faça a junção de claude_code_self_hosted_runner_session_idle_seconds do executor com a métrica de custo do Claude Code por ccr_session_id. A métrica do executor não carrega esse rótulo, então atribua-o com label_replace, como nesta consulta:

sum by (ccr_session_id) (claude_code_cost_usage_total)
and on (ccr_session_id)
label_replace(
  claude_code_self_hosted_runner_session_idle_seconds > 600,
  "ccr_session_id", "cse_$1", "session_id", "session_(.*)"
)

A consulta retorna um resultado por sessão ociosa há mais de dez minutos: o custo em dólares americanos que seu processo do Claude Code contabilizou até agora. Para fazer a junção com outra métrica do Claude Code, substitua claude_code_cost_usage_total na consulta. A consulta funciona com qualquer --capacity.

• session_id: na porta 9464, esse rótulo nas métricas do Claude Code contém o próprio session.id do Claude Code, que não corresponde a nenhuma série do executor. Uma junção por ele não retorna nada, então faça a junção por ccr_session_id.
• As métricas do Claude Code não têm ccr_session_id: verifique se OTEL_METRICS_INCLUDE_SESSION_ID não está definido como false

Semântica do contador de ciclo de vida da sessão

Os contadores sessions_started_total, sessions_completed_total, sessions_failed_total e sessions_interrupted_total classificam cada sessão por como terminou. Cada filho de sessão gerado incrementa sessions_started_total no tempo de geração, e exatamente um dos outros três incrementa na saída, então sessions_started_total menos a soma dos outros três é igual ao número de filhos de sessão em execução no momento.

• completed: a sessão terminou limpo. Isso cobre o filho saindo por conta própria com código 0, a sessão sendo arquivada ou excluída enquanto o filho ainda estava conectado, e o executor devolvendo o slot de forma limpa: a liberação da sessão no tempo limite de ociosidade, no tempo de aposentadoria ou no limite --kill-session-after-min; um tempo limite de inicialização; ou uma desatribuição do lado do servidor que o loop de pesquisa notou antes do filho sair. Incrementa sessions_completed_total.
• failed: o filho saiu por conta própria com um código diferente de zero, seja um crash ou uma falha de configuração após geração. Incrementa sessions_failed_total.
• interrupted: o executor encerrou o filho por um motivo operacional que não é nem um sucesso de sessão nem uma falha do executor, como uma drenagem ou o encerramento de uma sessão que ainda estava no executor quando a janela de graça SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS após seu limite --kill-session-after-min terminou. Um reinício de rolagem Kubernetes enviando SIGTERM é um exemplo de uma drenagem. Incrementa sessions_interrupted_total.

Antes da v2.1.260, o executor encerrava cada sessão que atingia seu limite --kill-session-after-min e a contava em sessions_interrupted_total.

O CLAUDE_RUNNER_EXIT_REASON do hook post-session classifica entregas limpas de forma diferente. O hook relata estes como interrupted, porque o executor parou o filho: uma liberação, um tempo limite de inicialização, uma desatribuição do servidor e um arquivamento ou exclusão que a pesquisa notou primeiro. Esses contadores registram os mesmos eventos como completed, porque o slot foi devolvido limpo.

Se você reconciliar recebimentos de hook contra sessions_completed_total diretamente, você subestima as conclusões. Use o hook para garantias por sessão e os contadores para taxas agregadas.

Em um ambiente único, --capacity 1 com o padrão --drain-grace-sec 0, cada processo executor sai momentos após sua única sessão terminar. sessions_completed_total, sessions_failed_total e sessions_interrupted_total incrementam apenas no final da sessão, logo antes dessa saída, então uma raspagem Prometheus a cada 15 a 60 segundos raramente captura o incremento antes das séries do executor desaparecerem; esses três contadores de final de sessão são os contadores terminais que o resto desta seção se refere. sessions_started_total incrementa na geração e permanece visível pela vida da sessão, então aparece de forma confiável, mas em um ambiente único lê mais perto de "sessões em execução no momento" do que uma contagem cumulativa.

Use a série nesta tabela para o objetivo correspondente em vez dos contadores terminais:

As linhas orchestrator_* existem apenas em ambientes executando o orquestrador sob demanda. Em uma frota fixa cujos executores sobrevivem suas sessões, com --drain-grace-sec acima de 0, use sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) para throughput; em uma frota única essa série tem o mesmo problema de janela de raspagem que os contadores terminais, então confie na contagem de sessões enfileiradas em vez disso. Verifique backlog na aba Activity do ambiente, na página de administração Cloud environments: os executores não exportam uma série de profundidade de fila.

Para relatório de resultado por sessão, use o hook post-session em vez disso: ele dispara no final de cada sessão onde um processo filho foi gerado, exceto em caso de encerramento abrupto do executor, como uma preempção de VM, por contrato do próprio hook.

Próximos passos

• Self-hosted environments: o ambiente, executor e modelo de sessão; o guia de início rápido e Deploy to production contêm configuração e operações
• Customize sessions: scripts wrapper, hooks de ciclo de vida e executores sob demanda
• Verify session identity: o token de sessão, suas reivindicações e como verificá-lo