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. CLAUDE_CODE_DISABLE_FEATURE_FLAGS é relacionado mas diferente: definir CLAUDE_CODE_DISABLE_FEATURE_FLAGS=1 desabilita a busca de sinalizador de recurso, e a telemetria permanece ativada a menos que DISABLE_TELEMETRY também esteja definido. CLAUDE_CODE_DISABLE_FEATURE_FLAGS requer Claude Code v2.1.319 ou posterior.

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 assim que se registra e conclui suas verificações de inicialização. A partir daí, 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 endpoint 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 do Prometheus

Cada executor serve métricas do Prometheus em GET /metrics na mesma porta que /healthz. Principais séries:

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

Para autoscaling, escolha a série que corresponde ao seu estilo de escalonamento e aplique um filtro antes que ela alimente o escalonador:

• Escalonamento por profundidade da fila: alimente seu escalonador HPA ou KEDA com claude_code_self_hosted_orchestrator_pool_pending_sessions, não com queue_pending_sessions.
• Escalonamento por capacidade: escalone com base na razão entre active_sessions e capacity do executor.
• Filtre por connected: filtre a consulta com claude_code_self_hosted_orchestrator_connected == 1 por instância, para que o valor desatualizado de uma réplica desconectada não alimente o escalonador.

Durante uma interrupção total do polling, com todas as réplicas desconectadas, a consulta filtrada não retorna dados. O HPA mantém a contagem atual de réplicas quando uma métrica está ausente, mas o escalonador Prometheus do KEDA, com seu padrão ignoreNullValues: "true", lê o resultado vazio como zero e reduz a escala; defina ignoreNullValues: "false" no ScaledObject, opcionalmente com um piso de réplicas de fallback.

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

# Exemplo de PodMonitor do Prometheus Operator para o executor auto-hospedado
# + orquestrador do Claude Code. Ajuste o namespace e os seletores de rótulos para
# corresponder à sua implantação. Tanto o executor quanto o orquestrador servem /metrics
# em sua --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 do Kubernetes, além de
      # quaisquer Jobs de executor sob demanda e pods do orquestrador que você rotule
      # da mesma forma e aos quais atribua uma containerPort nomeada 'health'.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Exemplos de regras de alerta

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

# Exemplos de regras de alerta do Prometheus para o executor auto-hospedado
# + orquestrador do 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: "Runner {{ $labels.pod }} has not polled in >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Runners are running mixed versions"
      - 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: "Sessions are failing before init (checkout hook / git / token / pre-init crash)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: PollWork failing ({{ $value | humanize }}/s over 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: "SessionStart hooks are failing"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} cannot reach the Anthropic control plane"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} has not polled in >90s (poll loop waits on hook execution)"
      - 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: "Sessions blocked from spawning: {{ $value }}. Read each one's error in the Activity tab, fix the cause, then select 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: "Orchestrator {{ $labels.pod }}: PollSpawnHints failing ({{ $value | humanize }}/s over 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: "Orchestrator {{ $labels.pod }}: >3 spawn-runner hook failures in 5m"

Alertar sobre executores perdidos e sessões em espera

Para ser alertado quando executores forem perdidos, sessões estiverem aguardando ou o orquestrador estiver fora do ar, carregue estas regras de alerta do Prometheus junto com os exemplos de regras de alerta:

• 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 coletados 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 estivesse 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: "Runners registered and scraped: {{ $value }}, below the floor. Check the runner workloads first, then the scrape targets if all are running."

• Piso: defina o 2 em expr como cerca de metade da sua contagem de réplicas, arredondada 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 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 dos exemplos de regras de alerta, porque ClaudeRunnersBelowFloor ainda conta um executor que não consegue fazer polling

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: "Sessions waiting for a runner: {{ $value }}, above the threshold for 10 minutes. Check claude_code_self_hosted_orchestrator_spawn_hooks_total by result, then runner workloads that don't start."
      - 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: "Over 1% of queue waits in the last 10 minutes exceeded 160 seconds. Check whether ClaudeOrchestratorDisconnected is firing, then claude_code_self_hosted_orchestrator_spawn_hooks_total by result and 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ê costuma ver
• ClaudeOrchestratorDisconnected: mantenha-o carregado a partir dos exemplos de regras de alerta, porque ClaudeOrchestratorSessionsWaiting para de disparar cerca de 2 minutos depois que o último orquestrador no namespace se desconecta

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 coletado 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: "No orchestrator has been scraped for 5 minutes. If it's down, no on-demand runner starts, and sessions wait. Check the orchestrator workload first, then its scrape target if it's running."

• 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 rótulo namespace, remova o matcher, ou o alerta disparará após 5 minutos e permanecerá ativo.
• Servidores Prometheus que não coletam o orquestrador: deixe o alerta de fora dos arquivos de regras deles, porque em um servidor desse tipo 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 os exemplos de regras de alerta do orquestrador param de disparar em cerca de 10 minutos após o orquestrador ficar fora do ar.

Repassar métricas dos processos filhos de sessão

Cada sessão é executada em seu próprio processo filho com suas próprias métricas do OpenTelemetry; com --capacity acima de um, o executor reescreve a forma como essas métricas dos processos filhos 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 do seu script wrapper ou do próprio ambiente do executor, que as sessões herdam, reexpõe os instrumentos de counter e gauge de cada processo filho no próprio endpoint /metrics do executor, junto com as séries do executor. O executor reescreve o exportador do processo filho para enviar via OTLP a um receptor somente de loopback na porta de health, marca cada série com os rótulos session_id e client_platform e remove as séries de uma sessão quando essa sessão termina. Histogramas não são repassados, e uma métrica de processo filho cujo nome colidiria com o prefixo próprio do executor é descartada.

Com o padrão --capacity 1, a reescrita não se aplica: o processo filho da sessão vincula seu próprio endpoint do Prometheus na porta 9464, como de costume.

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

Para ver quanto as sessões ociosas custaram, una a claude_code_self_hosted_runner_session_idle_seconds do executor à métrica de custo do Claude Code em ccr_session_id. A métrica do executor não tem esse rótulo, então atribua um a ela 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 unir 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 união por ele não retorna nada, então una 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 dos contadores do 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 pela forma como ela terminou. Cada processo filho de sessão iniciado incrementa sessions_started_total no momento da inicialização, e exatamente um dos outros três é incrementado na saída, então sessions_started_total menos a soma dos outros três é igual ao número de processos filhos de sessão em execução no momento.

• completed: a sessão terminou de forma limpa. Isso abrange o processo filho saindo por conta própria com código 0, a sessão sendo arquivada ou excluída enquanto o processo filho ainda estava conectado, e o executor devolvendo o slot de forma limpa: liberando a sessão no timeout de ociosidade, no horário de aposentadoria ou no limite de --kill-session-after-min; um timeout de inicialização; ou uma desatribuição do lado do servidor que o loop de polling percebeu antes de o processo filho sair. Incrementa sessions_completed_total.
• failed: o processo filho saiu por conta própria com um código diferente de zero, seja uma falha ou uma falha de configuração após a inicialização. Incrementa sessions_failed_total.
• interrupted: o executor encerrou o processo filho por um motivo operacional que não é nem um sucesso da sessão nem uma falha do executor, como um drain, ou o encerramento de uma sessão que ainda estava no executor quando a janela de tolerância SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS após seu limite de --kill-session-after-min terminou. Um reinício gradual do Kubernetes enviando SIGTERM é um exemplo de drain. Incrementa sessions_interrupted_total.

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

O CLAUDE_RUNNER_EXIT_REASON do hook post-session classifica as devoluções limpas de forma diferente. O hook as relata como interrupted, porque o executor interrompeu o processo filho: uma liberação, um timeout de inicialização, uma desatribuição do servidor e um arquivamento ou exclusão que o polling percebeu primeiro. Esses contadores registram os mesmos eventos como completed, porque o slot foi devolvido de forma limpa.

Se você reconciliar os recebimentos do hook diretamente com sessions_completed_total, contará menos conclusões do que as reais. Use o hook para garantias por sessão e os contadores para taxas agregadas.

Em um ambiente de uso único, --capacity 1 com o padrão --drain-grace-sec 0, cada processo do executor sai momentos depois que sua única sessão termina. sessions_completed_total, sessions_failed_total e sessions_interrupted_total são incrementados apenas no fim da sessão, logo antes dessa saída, então uma coleta do Prometheus a cada 15 a 60 segundos raramente captura o incremento antes que as séries do executor desapareçam; esses três contadores de fim de sessão são os contadores terminais aos quais o restante desta seção se refere. sessions_started_total é incrementado na inicialização e permanece visível durante toda a vida da sessão, então aparece de forma confiável, mas em um ambiente de uso único ele se aproxima mais de "sessões em execução no momento" do que de uma contagem cumulativa.

Use as séries desta tabela para o objetivo correspondente em vez dos contadores terminais:

As linhas orchestrator_* existem apenas em ambientes que executam o orquestrador sob demanda. Em uma frota fixa cujos executores sobrevivem às 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 de uso único, essa série tem o mesmo problema de janela de coleta que os contadores terminais, então dependa da contagem de sessões enfileiradas. Verifique o backlog na guia 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órios de resultado por sessão, use o hook post-session: ele dispara em todo fim de sessão em que um processo filho foi iniciado, exceto em um encerramento abrupto do executor, como uma preempção de VM, conforme o 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