Référence des environnements auto-hébergés

Référence complète pour le runner et l'orchestrateur auto-hébergés : drapeaux CLI, variables d'environnement et métriques Prometheus.

[!NOTE]

Les environnements auto-hébergés sont en bêta publique sur les plans Team et Enterprise ; un Propriétaire les active en activant Autoriser les environnements auto-hébergés sur la page d'administration Environnements cloud. Cette page est la référence des drapeaux et des métriques ; consultez le guide de démarrage rapide pour la configuration et Déployer en production pour les recettes de flotte.

Cette page est la référence pour les deux processus que vous exécutez dans un environnement auto-hébergé : le runner, qui exécute les sessions cloud Claude Code sur vos hôtes, et l'orchestrateur d'autoscaling optionnel, qui démarre les runners à mesure que les sessions s'accumulent. Chacun a sa propre table de drapeaux. Les deux s'exécutent sur des hôtes Linux ou macOS, pour lesquels les valeurs par défaut telles que /workspace et ~/.claude s'appliquent. Exécutez claude self-hosted-runner --help pour la liste faisant autorité sur votre version installée.

Les séries de métriques et quelques champs API utilisent toujours pool pour ce que ces pages appellent un environnement ; les deux termes désignent la même chose. L'ID d'environnement est le champ pool_id, avec la forme ccpool_... : partout où ces pages affichent un identifiant pool, il désigne l'environnement. Les drapeaux CLI et les variables d'environnement l'écrivent environment, comme --environment-secret-file ; les orthographes pool dépréciées fonctionnent toujours, comme la ligne --environment-secret-file le décrit.

Drapeaux CLI du runner

La plupart des drapeaux ont une variable d'environnement correspondante. Quand les deux sont définis, le drapeau a la priorité. Les drapeaux de durée prennent des minutes ou des secondes sur la CLI, mais la variable d'environnement appariée est toujours en millisecondes, indiquée par le suffixe _MS, et la colonne Par défaut affiche l'unité du drapeau : --exit-if-unused-min 10 équivaut à SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, et une valeur Helm comme SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" signifie 15 millisecondes, pas la valeur par défaut de 15 minutes.

La plupart des drapeaux de durée ont un maximum, choisi pour garder chaque délai d'attente en dessous du plafond de minuteur 32 bits du runtime d'environ 24,85 jours. Les drapeaux --*-min sont plafonnés à 10080 minutes, 7 jours ; --drain-grace-sec à 604800 secondes, également 7 jours ; et --drain-wait-sec à 86400 secondes, 24 heures. --session-stop-grace-sec et --post-session-hook-timeout-sec ne sont pas plafonnés. Dépasser un plafond se comporte différemment par surface :

• Drapeau : le démarrage échoue avec une erreur.
• Variable d'environnement : le runner serre la valeur au plafond de minuteur plutôt que de la rejeter.

Délai d'expiration du démarrage de session

Si une session a perdu son créneau pendant un tour tel que /code-review, mettez à jour le runner et le binaire enfant vers v2.1.309 ou ultérieur. De v2.1.299 à v2.1.308, le runner libérait une session, même en plein tour, dès que le délai d'expiration du démarrage s'écoulait sans message user ou assistant.

Avec --startup-timeout-min <n>, le runner libère le créneau d'une session quand son enfant ne s'est pas initialisé dans les <n> minutes qui suivent le clonage. Pendant un tour qui commence avant l'initialisation de l'enfant, la session conserve son créneau jusqu'à ce que <n> minutes s'écoulent sans aucune ligne sur le canal d'activité de l'enfant. Une fois l'enfant initialisé, le runner remet ce décompte à zéro et --release-idle-session-min régit la libération. Pour limiter une session dont l'enfant est actif mais bloqué, définissez --kill-session-after-min.

Listes de règles du mode auto

--server-auto-mode-lists vous permet de décider quelles règles du classifieur du mode auto provenant de l'extérieur du runner atteignent les sessions sur vos runners. Le plan de contrôle d'Anthropic peut envoyer des listes de règles avec une session et demander au runner de les appliquer. Certaines entrées peuvent être des règles rédigées par un administrateur de votre organisation. Les listes sont environment, soft_deny et allow :

• environment : une entrée peut amener le classifieur à autoriser davantage comme à autoriser moins.
• soft_deny : une entrée bloque une action sauf si l'utilisateur l'a explicitement demandée ou si une exception allow s'applique.
• allow : les exceptions aux entrées soft_deny.

La valeur du flag détermine quelles listes le runner applique :

• no-allow : la valeur par défaut. Applique environment et soft_deny et retient allow. Une entrée environment peut toujours amener le classifieur à autoriser davantage, donc la valeur par défaut n'exclut pas tout assouplissement.
• all : applique les trois listes.
• none : n'en applique aucune. Choisissez none pour exclure tout assouplissement provenant de ces listes. Cela supprime également les restrictions soft_deny.

Aucun paramètre du runner ne fait en sorte que le plan de contrôle demande au runner d'appliquer les listes. Quand il ne le demande pas, les sessions ne reçoivent aucune liste, quelle que soit la valeur que vous définissez. Pour voir ce qui s'est passé, démarrez le runner avec --log-level debug. Pour chaque session, le runner journalise alors une ligne contenant the server asked this runner to apply, ou une ligne contenant the server did not ask this runner to apply the auto mode lists it sends.

Drapeaux CLI de l'orchestrateur

La sous-commande self-hosted-runner orchestrator, qui génère les runners à la demande, accepte --api-url, --environment-secret-file, --hooks-dir, --health-port et --log-level avec les mêmes valeurs par défaut que le runner et, où le drapeau du runner en a une, la même variable d'environnement, sauf que --hooks-dir est requis et doit contenir un hook spawn-runner. Il prend également ses propres drapeaux :

Drapeaux du connecteur SCM

Le connecteur SCM n'est pas disponible, donc laissez les drapeaux de cette section non définis. Si vous définissez --scm-connector-host, la connexion ne s'ouvre pas, et l'orchestrateur continue à la réessayer. Les runners commencent toujours en tant que sessions en file d'attente.

Le connecteur est une connexion WebSocket permanente de l'orchestrateur au plan de contrôle d'Anthropic. Il est conçu pour permettre aux flux pré-session hébergés, tels que le sélecteur de dépôt et le résolveur de branche ou de ref, d'atteindre un hôte GitHub Enterprise Server qui n'est routable que de l'intérieur de votre réseau. Consultez Exigences réseau sur la page GitHub Enterprise Server pour voir ce dont ces flux ont besoin.

À chaque tentative de connexion, l'orchestrateur envoie son secret d'environnement existant, et il réessaye automatiquement avec un backoff exponentiel, plafonné à 30 secondes plus une gigue.

Paramètres réservés aux variables d'environnement

Ces paramètres du runner sont lus uniquement à partir de l'environnement et couvrent le comportement que la plupart des déploiements laissent à la valeur par défaut :

Télémétrie

Les enfants de session envoient la télémétrie opérationnelle à Anthropic sauf si vous la désactivez. Aucun code ou contenu de dépôt n'est envoyé. Définir les variables de télémétrie sur le processus du runner ; le runner les réaffirme après l'application des variables d'environnement fournies par le serveur, donc le paramètre de l'opérateur a toujours la priorité.

Un contrôle est spécifique aux environnements auto-hébergés : CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 opte pour les métriques opérationnelles Datadog, qui sont désactivées par défaut dans les environnements auto-hébergés. Les contrôles de télémétrie Claude Code généraux, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING et CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, s'appliquent aux enfants de session comme documenté dans la référence des variables d'environnement. CLAUDE_CODE_DISABLE_FEATURE_FLAGS est connexe mais différent : définir CLAUDE_CODE_DISABLE_FEATURE_FLAGS=1 désactive la récupération des drapeaux de fonctionnalité, et la télémétrie reste activée sauf si DISABLE_TELEMETRY est également défini. CLAUDE_CODE_DISABLE_FEATURE_FLAGS nécessite Claude Code v2.1.319 ou une version ultérieure.

CLAUDE_CODE_ENABLE_TELEMETRY n'est pas connexe : il active l'export OpenTelemetry vers votre propre collecteur, comme décrit dans Surveillance, et ne contrôle pas l'analytique d'Anthropic.

Point de terminaison de santé

Le runner sert GET /healthz sur le port de santé configuré une fois qu'il s'est enregistré et a terminé ses vérifications de démarrage. À partir de ce moment, la réponse est 200 OK chaque fois que le processus est actif, quel que soit l'état de la boucle d'interrogation, donc une sonde HTTP sur cet endpoint détecte uniquement un processus mort. Le corps JSON décrit l'état actuel :

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

Configurez des alertes sur last_poll_age_ms, mais ne l'utilisez pas dans une sonde de vivacité ; conservez cette sonde sur le code de statut HTTP. La valeur correspond au temps écoulé depuis la dernière interrogation réussie, elle augmente donc aussi lorsque le runner ne peut pas joindre Anthropic. last_poll_at et last_poll_age_ms valent tous deux null jusqu'à ce que la première interrogation réussisse. Pour détecter les interrogations qui échouent dès le départ, configurez également des alertes sur claude_code_self_hosted_runner_poll_errors_total, répertorié sous Métriques Prometheus.

Le /healthz propre à l'orchestrateur, sur son port de santé, retourne toujours 200. Le corps porte un champ connected signalant si l'interrogation la plus récente a réussi, plus les comptes de file d'attente de génération par état dans queue_counts. Pour savoir pourquoi connected vaut false, lisez le champ de premier niveau last_error, que chaque interrogation réussie réinitialise à null. Gater la disponibilité et les alertes sur connected plutôt que sur le code de statut.

Quand le connecteur SCM est configuré, le corps /healthz de l'orchestrateur porte également scm_connector_connected et un objet scm_connector avec connected, last_connected_at, last_error, reconnects et requests_forwarded. Les deux champs sont null quand --scm-connector-host n'est pas défini.

Métriques Prometheus

Chaque runner expose des métriques Prometheus sur GET /metrics, sur le même port que /healthz. Principales séries :

L'orchestrateur expose ses propres séries sur GET /metrics, sur le même port que son /healthz :

Pour l'autoscaling, choisissez la série qui correspond à votre stratégie de mise à l'échelle et filtrez-la avant qu'elle n'alimente le scaler :

• Mise à l'échelle selon la profondeur de file : alimentez votre scaler HPA ou KEDA avec claude_code_self_hosted_orchestrator_pool_pending_sessions, et non queue_pending_sessions.
• Mise à l'échelle selon la capacité : basez la mise à l'échelle sur le rapport entre active_sessions et capacity du runner.
• Filtrer sur connected : filtrez la requête avec claude_code_self_hosted_orchestrator_connected == 1 par instance, afin que la valeur obsolète d'un réplica déconnecté n'alimente pas le scaler.

Pendant une panne complète du poll, où tous les réplicas sont déconnectés, la requête filtrée ne renvoie aucune donnée. HPA conserve le nombre de réplicas actuel en cas de métrique manquante, mais le scaler Prometheus de KEDA, avec sa valeur par défaut ignoreNullValues: "true", interprète le résultat vide comme zéro et réduit le nombre de réplicas ; définissez ignoreNullValues: "false" sur le ScaledObject, éventuellement avec un plancher de réplicas fallback.

Le PodMonitor Prometheus Operator suivant couvre les deux processus. Il sélectionne les pods selon le label app.kubernetes.io/part-of: claude-code-self-hosted-runner et le port nommé health que définit la recette Kubernetes ; adaptez les namespaces à votre déploiement :

# Exemple de PodMonitor Prometheus Operator pour le runner auto-hébergé
# Claude Code + l'orchestrateur. Adaptez le namespace et les sélecteurs de labels
# à votre déploiement. Le runner et l'orchestrateur exposent tous deux /metrics sur
# leur --health-port (8080 par défaut).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Correspond au Deployment du runner de la recette Kubernetes, ainsi qu'aux
      # Jobs de runners à la demande et aux pods d'orchestrateur que vous étiquetez
      # de la même manière et auxquels vous attribuez un containerPort nommé 'health'.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Exemples de règles d'alerte

Ces exemples de règles d'alerte constituent un point de départ ; ajustez les seuils en fonction de la taille de votre flotte :

# Exemples de règles d'alerte Prometheus pour le runner auto-hébergé Claude Code
# + l'orchestrateur. Ajustez les seuils selon la taille de votre flotte et vos SLO.
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"

Alerter en cas de perte de runners et de sessions en attente

Pour être alerté lorsque des runners sont perdus, que des sessions attendent ou que l'orchestrateur est arrêté, chargez ces règles d'alerte Prometheus en complément des exemples de règles d'alerte :

• Flotte fixe : ClaudeRunnersBelowFloor
• Runners à la demande : ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh et ClaudeOrchestratorAbsent

Alerter lorsqu'une flotte fixe perd des runners

ClaudeRunnersBelowFloor se déclenche lorsque le nombre de runners enregistrés et scrapés restants est inférieur au plancher pendant 10 minutes :

groups:
  # Flottes fixes uniquement. Avec des runners à la demande, le nombre suit la demande,
  # donc ClaudeRunnersBelowFloor se déclencherait dès que la demande est faible.
  - 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."

• Plancher : définissez le 2 dans expr à environ la moitié de votre nombre de réplicas, arrondi à l'entier supérieur. Avec trois réplicas, conservez 2 : l'alerte se déclenche lorsqu'il reste un seul runner ou aucun.
• Namespace : remplacez claude-runners dans le matcher et dans labels, et dupliquez l'alerte pour chaque namespace supplémentaire. Si vos cibles n'ont pas de label namespace, supprimez le matcher et le label, sinon l'alerte lit 0 et se déclenche.
• ClaudeRunnerPollStale et ClaudeRunnerPollErrors : gardez-les chargées depuis les exemples de règles d'alerte, car ClaudeRunnersBelowFloor compte toujours un runner qui ne parvient pas à effectuer de poll

Alerter lorsque des sessions attendent des runners à la demande

ClaudeOrchestratorSessionsWaiting se déclenche lorsque le nombre de sessions en attente d'un runner reste supérieur à 0 pendant 10 minutes. ClaudeOrchestratorQueueWaitHigh se déclenche lorsque plus de 1 % des attentes en file au cours des 10 dernières minutes ont dépassé 160 secondes, et que cette situation dure 5 minutes :

groups:
  # Runners à la demande uniquement. Aucune modification nécessaire pour le 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."

• Seuil : si une session est toujours en attente, augmentez le > 0 de ClaudeOrchestratorSessionsWaiting au-dessus du nombre que vous observez habituellement
• ClaudeOrchestratorDisconnected : gardez-la chargée depuis les exemples de règles d'alerte, car ClaudeOrchestratorSessionsWaiting cesse de se déclencher environ 2 minutes après la déconnexion du dernier orchestrateur du namespace

Alerter lorsque l'orchestrateur est arrêté

Pour savoir si l'orchestrateur lui-même est arrêté, chargez ClaudeOrchestratorAbsent. Elle se déclenche lorsqu'aucun orchestrateur du namespace n'a été scrapé depuis 5 minutes :

groups:
  # Runners à la demande uniquement. Remplacez claude-runners par le namespace de l'orchestrateur.
  - 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 : remplacez claude-runners par le namespace de l'orchestrateur, et dupliquez l'alerte pour chaque namespace supplémentaire qui exécute un orchestrateur. Si vos cibles n'ont pas de label namespace, supprimez le matcher, sinon l'alerte se déclenche au bout de 5 minutes et reste active.
• Serveurs Prometheus qui ne scrapent pas l'orchestrateur : n'incluez pas l'alerte dans leurs fichiers de règles, car sur un tel serveur elle se déclenche au bout de 5 minutes et reste active
• Ne vous fiez pas aux autres alertes de l'orchestrateur : elles lisent des métriques que l'orchestrateur expose lui-même. ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh et les exemples de règles d'alerte de l'orchestrateur cessent tous de se déclencher dans les 10 minutes environ suivant l'arrêt de l'orchestrateur.

Relayer les métriques des enfants de session

Chaque session s'exécute dans son propre processus enfant avec ses propres métriques OpenTelemetry ; avec une --capacity supérieure à un, le runner réécrit la manière dont ces métriques enfants sont exposées. Définir OTEL_METRICS_EXPORTER=prometheus sur l'hôte du runner et CLAUDE_CODE_ENABLE_TELEMETRY=1 dans l'environnement de la session, par exemple depuis votre script wrapper ou l'environnement du runner lui-même, dont les sessions héritent, réexpose les instruments de type compteur et jauge de chaque enfant sur l'endpoint /metrics du runner, à côté des séries du runner. Le runner réécrit l'exportateur de l'enfant pour qu'il envoie via OTLP vers un récepteur en loopback uniquement sur le port de santé, ajoute à chaque série les labels session_id et client_platform, et supprime les séries d'une session lorsque celle-ci se termine. Les histogrammes ne sont pas relayés, et une métrique enfant dont le nom entrerait en conflit avec le préfixe propre du runner est ignorée.

Avec la valeur par défaut --capacity 1, la réécriture ne s'applique pas : l'enfant de la session lie son propre endpoint Prometheus sur le port 9464, comme d'habitude.

Joindre les métriques d'une session à celles du runner

Pour connaître le coût des sessions inactives, joignez la métrique claude_code_self_hosted_runner_session_idle_seconds du runner à la métrique de coût de Claude Code sur ccr_session_id. La métrique du runner ne porte pas ce label ; attribuez-le-lui avec label_replace, comme dans cette requête :

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_(.*)"
)

La requête renvoie un résultat par session inactive depuis plus de dix minutes : le coût en dollars américains que son processus Claude Code a comptabilisé jusqu'à présent. Pour joindre une autre métrique Claude Code, remplacez claude_code_cost_usage_total dans la requête. La requête fonctionne quelle que soit la --capacity.

• session_id : sur le port 9464, ce label sur les métriques Claude Code contient le session.id propre à Claude Code, qui ne correspond à aucune série du runner. Une jointure sur ce label ne renvoie rien ; effectuez donc la jointure sur ccr_session_id.
• Les métriques Claude Code n'ont pas de ccr_session_id : vérifiez que OTEL_METRICS_INCLUDE_SESSION_ID n'est pas défini sur false

Sémantique des compteurs du cycle de vie des sessions

Les compteurs sessions_started_total, sessions_completed_total, sessions_failed_total et sessions_interrupted_total classent chaque session selon la manière dont elle s'est terminée. Chaque enfant de session lancé incrémente sessions_started_total au moment du lancement, et exactement un des trois autres compteurs est incrémenté à la sortie ; ainsi, sessions_started_total moins la somme des trois autres est égal au nombre d'enfants de session en cours d'exécution.

• completed : la session s'est terminée proprement. Cela couvre l'enfant qui se termine de lui-même avec le code 0, la session archivée ou supprimée alors que l'enfant était encore connecté, et le runner qui restitue proprement le slot : libération de la session à l'expiration du délai d'inactivité, à l'heure de retrait ou à la limite --kill-session-after-min ; un délai d'expiration au démarrage ; ou une désattribution côté serveur détectée par la boucle de poll avant la sortie de l'enfant. Incrémente sessions_completed_total.
• failed : l'enfant s'est terminé de lui-même avec un code non nul, soit à la suite d'un plantage, soit d'un échec de configuration après le lancement. Incrémente sessions_failed_total.
• interrupted : le runner a arrêté l'enfant pour une raison opérationnelle qui n'est ni un succès de la session ni une défaillance du runner, comme un drain, ou l'arrêt d'une session encore présente sur le runner à la fin de la fenêtre de grâce SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS qui suit sa limite --kill-session-after-min. Un redémarrage progressif Kubernetes envoyant SIGTERM est un exemple de drain. Incrémente sessions_interrupted_total.

Avant la v2.1.260, le runner arrêtait chaque session atteignant sa limite --kill-session-after-min et la comptabilisait dans sessions_interrupted_total.

La variable CLAUDE_RUNNER_EXIT_REASON du hook post-session classe différemment les restitutions propres. Le hook les signale comme interrupted, car c'est le runner qui a arrêté l'enfant : une libération, un délai d'expiration au démarrage, une désattribution par le serveur, et une archive ou une suppression détectée en premier par le poll. Ces compteurs enregistrent les mêmes événements comme completed, car le slot a été restitué proprement.

Si vous rapprochez directement les accusés de réception du hook de sessions_completed_total, vous sous-estimez le nombre de sessions terminées. Utilisez le hook pour les garanties par session et les compteurs pour les taux agrégés.

Sur un environnement à usage unique, avec --capacity 1 et la valeur par défaut --drain-grace-sec 0, chaque processus runner se termine quelques instants après la fin de son unique session. sessions_completed_total, sessions_failed_total et sessions_interrupted_total ne sont incrémentés qu'à la fin de la session, juste avant cette sortie ; un scrape Prometheus toutes les 15 à 60 secondes capte donc rarement l'incrément avant la disparition des séries du runner. Ces trois compteurs de fin de session sont les compteurs terminaux auxquels fait référence le reste de cette section. sessions_started_total est incrémenté au lancement et reste visible pendant toute la durée de la session ; il apparaît donc de manière fiable, mais sur un environnement à usage unique, il s'interprète davantage comme « sessions en cours d'exécution » que comme un compteur cumulatif.

Utilisez les séries de ce tableau pour l'objectif correspondant plutôt que les compteurs terminaux :

Les lignes orchestrator_* n'existent que sur les environnements exécutant l'orchestrateur à la demande. Sur une flotte fixe dont les runners survivent à leurs sessions, avec --drain-grace-sec supérieur à 0, utilisez sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) pour le débit ; sur une flotte à usage unique, cette série présente le même problème de fenêtre de scrape que les compteurs terminaux ; fiez-vous donc plutôt au nombre de sessions en file d'attente. Vérifiez l'arriéré dans l'onglet Activity de l'environnement, sur la page d'administration Cloud environments : les runners n'exportent pas de série de profondeur de file.

Pour un suivi des résultats par session, utilisez plutôt le hook post-session : il se déclenche à chaque fin de session pour laquelle un processus enfant a été lancé, sauf en cas d'arrêt brutal du runner, comme une préemption de VM, conformément au contrat propre au hook.

Étapes suivantes

• Environnements auto-hébergés : le modèle d'environnement, de runner et de session ; le guide de démarrage rapide et Déployer en production contiennent la configuration et les opérations
• Personnaliser les sessions : scripts wrapper, hooks de cycle de vie et runners à la demande
• Vérifier l'identité de la session : le token de session, ses revendications et comment le vérifier