Referensi lingkungan yang di-host sendiri

Referensi lengkap untuk runner dan orchestrator yang di-host sendiri: flag CLI, variabel lingkungan, dan metrik Prometheus.

[!NOTE]

Lingkungan yang di-host sendiri berada dalam beta publik pada paket Team dan Enterprise; seorang Owner mengaktifkannya dengan mengaktifkan Allow self-hosted environments di halaman admin Cloud environments. Halaman ini adalah referensi flag dan metrik; lihat quickstart untuk setup dan Deploy to production untuk resep fleet.

Halaman ini adalah referensi untuk dua proses yang Anda jalankan dalam lingkungan yang di-host sendiri: runner, yang mengeksekusi Claude Code cloud sessions di host Anda, dan orchestrator autoscaling opsional, yang memulai runner saat session antri. Masing-masing memiliki tabel flag-nya sendiri. Keduanya berjalan di host Linux atau macOS, yang default seperti /workspace dan ~/.claude asumsikan. Jalankan claude self-hosted-runner --help untuk daftar otoritatif pada versi terinstal Anda.

Seri metrik dan beberapa field API masih menggunakan pool untuk apa yang halaman ini sebut lingkungan; kedua istilah menamakan hal yang sama. ID lingkungan adalah field pool_id, dengan bentuk ccpool_...: di mana pun halaman ini menunjukkan identifier pool, itu menamakan lingkungan. Flag CLI dan variabel lingkungan mengejanya environment, seperti --environment-secret-file; ejaan pool yang sudah usang masih berfungsi, seperti yang dijelaskan baris --environment-secret-file.

Flag CLI Runner

Sebagian besar flag memiliki variabel lingkungan yang sesuai. Ketika keduanya diatur, flag mengambil prioritas. Flag durasi mengambil menit atau detik di CLI, tetapi variabel lingkungan yang dipasangkan selalu dalam milidetik, ditunjukkan oleh suffix _MS, dan kolom Default menunjukkan unit flag: --exit-if-unused-min 10 setara dengan SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, dan nilai Helm seperti SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" berarti 15 milidetik, bukan default 15 menit.

Sebagian besar flag durasi memiliki maksimum, dipilih untuk menjaga setiap timeout di dalam ceiling timer 32-bit runtime sekitar 24,85 hari. Flag --*-min cap pada 10080 menit, 7 hari; --drain-grace-sec pada 604800 detik, juga 7 hari; dan --drain-wait-sec pada 86400 detik, 24 jam. --session-stop-grace-sec dan --post-session-hook-timeout-sec tidak terbatas. Melampaui cap berperilaku berbeda per surface:

• Flag: startup gagal dengan error.
• Variabel lingkungan: runner menjepit nilai ke ceiling timer daripada menolaknya.

Timeout startup sesi

Jika sebuah sesi kehilangan slotnya selama giliran seperti /code-review, perbarui runner dan binary child ke v2.1.309 atau lebih baru. Dari v2.1.299 hingga v2.1.308, runner melepaskan sesi, bahkan di tengah giliran, begitu timeout startup terlewati tanpa pesan user atau assistant.

Dengan --startup-timeout-min <n>, runner melepaskan slot sesi ketika child-nya belum diinisialisasi dalam <n> menit setelah cloning. Selama giliran yang dimulai sebelum child diinisialisasi, sesi mempertahankan slotnya hingga <n> menit berlalu tanpa satu baris pun di activity channel milik child. Setelah child diinisialisasi, runner mengosongkan hitungan tersebut dan --release-idle-session-min mengatur pelepasan. Untuk membatasi sesi yang child-nya hidup tetapi macet, atur --kill-session-after-min.

Daftar aturan auto mode

--server-auto-mode-lists memungkinkan Anda memutuskan aturan pengklasifikasi auto mode mana dari luar runner yang mencapai sesi di runner Anda. Control plane Anthropic dapat mengirim daftar aturan bersama sebuah sesi dan meminta runner untuk menerapkannya. Beberapa entri mungkin merupakan aturan yang ditulis oleh admin organisasi Anda. Daftarnya adalah environment, soft_deny, dan allow:

• environment: sebuah entri dapat membuat pengklasifikasi mengizinkan lebih banyak maupun lebih sedikit.
• soft_deny: sebuah entri memblokir tindakan kecuali pengguna secara eksplisit memintanya atau pengecualian allow berlaku.
• allow: pengecualian terhadap entri soft_deny.

Nilai flag menentukan daftar mana yang diterapkan runner:

• no-allow: default. Menerapkan environment dan soft_deny serta menahan allow. Entri environment tetap dapat membuat pengklasifikasi mengizinkan lebih banyak, sehingga default tidak mencegah setiap pelonggaran.
• all: menerapkan ketiga daftar.
• none: tidak menerapkan satu pun. Pilih none untuk mencegah setiap pelonggaran dari daftar-daftar ini. Ini juga menghilangkan pembatasan soft_deny.

Tidak ada pengaturan runner yang membuat control plane meminta runner menerapkan daftar tersebut. Ketika control plane tidak meminta, sesi tidak menerima daftar apa pun, apa pun yang Anda atur. Untuk melihat mana yang terjadi, mulai runner dengan --log-level debug. Untuk setiap sesi, runner kemudian mencatat ke log baris yang berisi the server asked this runner to apply, atau baris yang berisi the server did not ask this runner to apply the auto mode lists it sends.

Flag CLI orchestrator

Subperintah self-hosted-runner orchestrator, yang menjalankan runner on-demand, menerima --api-url, --environment-secret-file, --hooks-dir, --health-port, dan --log-level dengan default yang sama seperti runner dan, jika flag runner memilikinya, environment variable yang sama, kecuali bahwa --hooks-dir wajib diisi dan harus berisi hook spawn-runner. Subperintah ini juga menerima flag-nya sendiri:

Flag konektor SCM

Konektor SCM tidak tersedia, jadi biarkan flag di bagian ini tidak diatur. Jika Anda mengatur --scm-connector-host, koneksi tidak terbuka, dan orchestrator terus mencoba ulang. Runner tetap dimulai saat sesi masuk antrean.

Konektor ini adalah koneksi WebSocket tetap dari orchestrator ke control plane Anthropic. Konektor ini dirancang agar alur pra-sesi yang di-host, seperti pemilih repositori dan penentu branch atau ref, dapat menjangkau host GitHub Enterprise Server yang hanya dapat dirutekan dari dalam jaringan Anda. Lihat Persyaratan jaringan di halaman GitHub Enterprise Server untuk mengetahui apa yang dibutuhkan alur tersebut.

Pada setiap upaya koneksi, orchestrator mengirimkan environment secret yang sudah ada, dan otomatis mencoba ulang dengan exponential backoff, dibatasi hingga 30 detik ditambah jitter.

Pengaturan variabel-lingkungan-saja

Pengaturan runner ini dibaca dari lingkungan saja dan mencakup perilaku yang sebagian besar deployment tinggalkan di default:

Telemetry

Child session mengirim telemetry operasional ke Anthropic kecuali Anda mematikannya. Tidak ada kode atau konten repositori yang dikirim. Atur variabel telemetry pada proses runner; runner re-assert mereka setelah menerapkan variabel lingkungan yang disediakan server, jadi pengaturan operator selalu mengambil prioritas.

Satu kontrol spesifik untuk lingkungan yang di-host sendiri: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 opt in ke metrik operasional Datadog, yang off secara default dalam lingkungan yang di-host sendiri. Kontrol telemetry Claude Code umum, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING, dan CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, berlaku untuk child session seperti yang didokumentasikan dalam referensi variabel lingkungan. DISABLE_GROWTHBOOK terkait tetapi berbeda: mengatur DISABLE_GROWTHBOOK=1 menonaktifkan pengambilan feature-flag, dan telemetry tetap on kecuali DISABLE_TELEMETRY juga diatur.

CLAUDE_CODE_ENABLE_TELEMETRY tidak terkait: itu mengaktifkan export OpenTelemetry ke collector Anda sendiri, seperti yang dijelaskan dalam Monitoring, dan tidak mengontrol analytics Anthropic.

Health endpoint

Runner melayani GET /healthz pada port health yang dikonfigurasi. Respons adalah 200 OK kapan pun proses hidup, apa pun state poll loop, jadi probe HTTP pada endpoint ini mendeteksi proses mati saja. Badan JSON menjelaskan state saat ini:

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

Buat peringatan berdasarkan last_poll_age_ms, tetapi jangan menggunakannya dalam probe liveness; pertahankan probe tersebut pada kode status HTTP. Nilai ini adalah waktu sejak poll terakhir yang berhasil, sehingga nilainya juga naik saat runner tidak dapat menjangkau Anthropic. Baik last_poll_at maupun last_poll_age_ms bernilai null sampai poll pertama berhasil. Untuk menangkap poll yang gagal sejak awal, buat juga peringatan berdasarkan claude_code_self_hosted_runner_poll_errors_total, yang tercantum di bawah metrik Prometheus.

/healthz milik orchestrator sendiri, pada port health-nya, selalu mengembalikan 200. Badan membawa field connected yang melaporkan apakah poll terbaru berhasil, plus spawn-queue count per-state dalam queue_counts. Untuk melihat mengapa connected bernilai false, baca field last_error tingkat atas, yang diatur ulang menjadi null oleh setiap poll yang berhasil. Gate readiness dan alerting pada connected daripada status code.

Ketika SCM connector dikonfigurasi, badan /healthz orchestrator juga membawa scm_connector_connected dan objek scm_connector dengan connected, last_connected_at, last_error, reconnects, dan requests_forwarded. Kedua field adalah null ketika --scm-connector-host tidak diatur.

Metrik Prometheus

Setiap runner menyajikan metrik Prometheus di GET /metrics pada port yang sama dengan /healthz. Seri utama:

Orchestrator menyajikan serinya sendiri di GET /metrics pada port yang sama dengan /healthz miliknya:

Untuk autoscaling, pilih seri yang sesuai dengan gaya scaling Anda dan beri gerbang padanya sebelum diumpankan ke scaler:

• Scaling berdasarkan kedalaman antrean: umpankan claude_code_self_hosted_orchestrator_pool_pending_sessions ke scaler HPA atau KEDA Anda, bukan queue_pending_sessions.
• Scaling berdasarkan kapasitas: lakukan scaling berdasarkan rasio active_sessions runner terhadap capacity.
• Gerbang pada connected: filter kueri dengan claude_code_self_hosted_orchestrator_connected == 1 per instans, sehingga nilai usang dari replika yang terputus tidak diumpankan ke scaler.

Selama gangguan poll total, ketika setiap replika terputus, kueri yang diberi gerbang tidak mengembalikan data. HPA mempertahankan jumlah replika saat ini ketika metrik tidak ada, tetapi scaler Prometheus KEDA dengan default ignoreNullValues: "true" membaca hasil kosong sebagai nol dan melakukan scale in; atur ignoreNullValues: "false" pada ScaledObject, opsional dengan batas bawah replika fallback.

PodMonitor Prometheus Operator berikut mencakup kedua proses. Ini memilih pod berdasarkan label app.kubernetes.io/part-of: claude-code-self-hosted-runner dan port bernama health yang diatur oleh resep Kubernetes; sesuaikan namespace agar cocok dengan deployment Anda:

# Example Prometheus Operator PodMonitor for the Claude Code self-hosted
# runner + orchestrator. Adjust the namespace and label selectors to match
# your deployment. Both the runner and the orchestrator serve /metrics on
# their --health-port (default 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      # Matches the runner Deployment from the Kubernetes recipe, plus any
      # on-demand runner Jobs and orchestrator pods you label the same way
      # and give a named 'health' containerPort.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

Contoh aturan peringatan

Contoh aturan peringatan ini adalah titik awal; sesuaikan ambang batasnya untuk ukuran armada Anda:

# Example Prometheus alert rules for the Claude Code self-hosted runner
# + orchestrator. Tune thresholds for your fleet size and 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"

Peringatan untuk runner yang hilang dan sesi yang menunggu

Agar mendapat peringatan ketika runner hilang, sesi menunggu, atau orchestrator mati, muat aturan peringatan Prometheus berikut bersama contoh aturan peringatan:

• Armada tetap: ClaudeRunnersBelowFloor
• Runner on-demand: ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh, dan ClaudeOrchestratorAbsent

Peringatan ketika armada tetap kehilangan runner

ClaudeRunnersBelowFloor dipicu ketika jumlah runner yang terdaftar dan di-scrape yang tersisa lebih sedikit dari batas bawah selama 10 menit:

groups:
  # Fixed fleets only. With on-demand runners the count follows demand,
  # so ClaudeRunnersBelowFloor would fire whenever demand is low.
  - 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."

• Batas bawah: atur 2 dalam expr ke sekitar setengah jumlah replika Anda, dibulatkan ke atas. Dengan tiga replika, pertahankan 2, dan peringatan dipicu ketika tersisa satu runner atau tidak ada sama sekali.
• Namespace: ganti claude-runners di matcher dan di labels, lalu salin peringatan tersebut untuk setiap namespace tambahan. Jika target Anda tidak memiliki label namespace, hapus matcher dan label tersebut, jika tidak peringatan akan membaca 0 dan dipicu.
• ClaudeRunnerPollStale dan ClaudeRunnerPollErrors: tetap muat keduanya dari contoh aturan peringatan, karena ClaudeRunnersBelowFloor tetap menghitung runner yang tidak dapat melakukan poll

Peringatan ketika sesi menunggu runner on-demand

ClaudeOrchestratorSessionsWaiting dipicu ketika jumlah sesi yang menunggu runner tetap di atas 0 selama 10 menit. ClaudeOrchestratorQueueWaitHigh dipicu ketika lebih dari 1% waktu tunggu antrean dalam 10 menit terakhir melebihi 160 detik, dan kondisi itu bertahan selama 5 menit:

groups:
  # On-demand runners only. Needs no edit for the 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."

• Ambang batas: jika selalu ada sesi yang menunggu, naikkan > 0 dalam ClaudeOrchestratorSessionsWaiting di atas jumlah yang biasanya Anda lihat
• ClaudeOrchestratorDisconnected: tetap muat dari contoh aturan peringatan, karena ClaudeOrchestratorSessionsWaiting berhenti dipicu sekitar 2 menit setelah orchestrator terakhir di namespace tersebut terputus

Peringatan ketika orchestrator mati

Untuk mengetahui bahwa orchestrator itu sendiri mati, muat ClaudeOrchestratorAbsent. Peringatan ini dipicu ketika tidak ada orchestrator di namespace tersebut yang di-scrape selama 5 menit:

groups:
  # On-demand runners only. Replace claude-runners with the orchestrator's namespace.
  - 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: ganti claude-runners dengan namespace orchestrator, lalu salin peringatan tersebut untuk setiap namespace tambahan yang menjalankan orchestrator. Jika target Anda tidak memiliki label namespace, hapus matcher tersebut, jika tidak peringatan akan dipicu setelah 5 menit dan tetap aktif.
• Server Prometheus yang tidak melakukan scrape pada orchestrator: jangan sertakan peringatan ini dalam file aturan server tersebut, karena pada server seperti itu peringatan akan dipicu setelah 5 menit dan tetap aktif
• Jangan mengandalkan peringatan orchestrator lainnya: peringatan tersebut membaca metrik yang disajikan oleh orchestrator itu sendiri. ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh, dan contoh aturan peringatan orchestrator semuanya berhenti dipicu dalam sekitar 10 menit setelah orchestrator mati.

Meneruskan metrik proses anak sesi

Setiap sesi berjalan dalam proses anaknya sendiri dengan metrik OpenTelemetry-nya sendiri; pada --capacity di atas satu, runner menulis ulang cara metrik proses anak tersebut diekspos. Mengatur OTEL_METRICS_EXPORTER=prometheus pada host runner dan CLAUDE_CODE_ENABLE_TELEMETRY=1 di environment sesi, misalnya dari skrip wrapper Anda atau environment runner itu sendiri, yang diwarisi oleh sesi, akan mengekspos ulang instrumen counter dan gauge setiap proses anak pada endpoint /metrics milik runner sendiri, bersama seri runner. Runner menulis ulang exporter proses anak agar mengirim melalui OTLP ke receiver khusus loopback pada port health, menandai setiap seri dengan label session_id dan client_platform, dan menghapus seri sebuah sesi ketika sesi tersebut berakhir. Histogram tidak diteruskan, dan metrik proses anak yang namanya akan bertabrakan dengan prefiks milik runner sendiri akan dibuang.

Pada --capacity 1 default, penulisan ulang ini tidak berlaku: proses anak sesi mengikat endpoint Prometheus-nya sendiri pada port 9464 seperti biasa.

Menggabungkan metrik sesi dengan metrik runner

Untuk melihat biaya yang telah dihabiskan sesi yang idle, lakukan join claude_code_self_hosted_runner_session_idle_seconds milik runner dengan metrik biaya Claude Code pada ccr_session_id. Metrik runner tidak membawa label tersebut, jadi berikan label itu dengan label_replace, seperti dalam kueri ini:

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

Kueri ini mengembalikan satu hasil per sesi yang idle lebih dari sepuluh menit: biaya dalam dolar AS yang telah dihitung oleh proses Claude Code sesi tersebut sejauh ini. Untuk melakukan join dengan metrik Claude Code lainnya, ganti claude_code_cost_usage_total dalam kueri. Kueri ini berfungsi pada --capacity berapa pun.

• session_id: pada port 9464, label tersebut pada metrik Claude Code berisi session.id milik Claude Code sendiri, yang tidak cocok dengan seri runner mana pun. Join pada label itu tidak mengembalikan apa pun, jadi lakukan join pada ccr_session_id.
• Metrik Claude Code tidak memiliki ccr_session_id: periksa bahwa OTEL_METRICS_INCLUDE_SESSION_ID tidak diatur ke false

Semantik penghitung siklus hidup sesi

Penghitung sessions_started_total, sessions_completed_total, sessions_failed_total, dan sessions_interrupted_total mengklasifikasikan setiap sesi berdasarkan cara sesi tersebut berakhir. Setiap proses anak sesi yang di-spawn menambah sessions_started_total pada saat spawn, dan tepat satu dari tiga lainnya bertambah saat keluar, sehingga sessions_started_total dikurangi jumlah tiga lainnya sama dengan jumlah proses anak sesi yang sedang berjalan.

• completed: sesi berakhir dengan bersih. Ini mencakup proses anak yang keluar dengan sendirinya dengan kode 0, sesi yang diarsipkan atau dihapus saat proses anak masih terhubung, dan runner yang menyerahkan kembali slot dengan bersih: melepaskan sesi pada idle timeout, waktu pensiun, atau batas --kill-session-after-min; timeout startup; atau deassign dari sisi server yang diketahui loop poll sebelum proses anak keluar. Menambah sessions_completed_total.
• failed: proses anak keluar dengan sendirinya dengan kode bukan nol, baik karena crash maupun kegagalan setup setelah spawn. Menambah sessions_failed_total.
• interrupted: runner menghentikan proses anak karena alasan operasional yang bukan keberhasilan sesi maupun kesalahan runner, seperti drain, atau menghentikan sesi yang masih berada di runner ketika jendela tenggang SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS setelah batas --kill-session-after-min-nya berakhir. Rolling restart Kubernetes yang mengirim SIGTERM adalah salah satu contoh drain. Menambah sessions_interrupted_total.

Sebelum v2.1.260, runner menghentikan setiap sesi yang mencapai batas --kill-session-after-min-nya dan menghitungnya dalam sessions_interrupted_total.

CLAUDE_RUNNER_EXIT_REASON milik hook post-session mengklasifikasikan penyerahan bersih secara berbeda. Hook melaporkannya sebagai interrupted, karena runner menghentikan proses anak: pelepasan, timeout startup, deassign server, serta pengarsipan atau penghapusan yang diketahui poll terlebih dahulu. Penghitung ini mencatat peristiwa yang sama sebagai completed, karena slot diserahkan kembali dengan bersih.

Jika Anda merekonsiliasi tanda terima hook langsung terhadap sessions_completed_total, Anda akan menghitung penyelesaian lebih sedikit dari yang sebenarnya. Gunakan hook untuk jaminan per sesi dan penghitung untuk laju agregat.

Pada environment sekali pakai, yaitu --capacity 1 dengan --drain-grace-sec 0 default, setiap proses runner keluar sesaat setelah satu sesinya berakhir. sessions_completed_total, sessions_failed_total, dan sessions_interrupted_total hanya bertambah di akhir sesi, tepat sebelum keluar, sehingga scrape Prometheus setiap 15 hingga 60 detik jarang menangkap penambahan tersebut sebelum seri runner menghilang; ketiga penghitung akhir sesi ini adalah penghitung terminal yang dirujuk di sisa bagian ini. sessions_started_total bertambah saat spawn dan tetap terlihat selama masa hidup sesi, sehingga dapat diandalkan muncul, tetapi pada environment sekali pakai nilainya lebih mendekati "sesi yang sedang berjalan" daripada hitungan kumulatif.

Gunakan seri dalam tabel ini untuk tujuan yang sesuai alih-alih penghitung terminal:

Baris orchestrator_* hanya ada pada environment yang menjalankan orchestrator on-demand. Pada armada tetap yang runner-nya hidup lebih lama dari sesinya, dengan --drain-grace-sec di atas 0, gunakan sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) untuk throughput; pada armada sekali pakai, seri tersebut memiliki masalah jendela scrape yang sama dengan penghitung terminal, jadi andalkan hitungan sesi yang diantrekan sebagai gantinya. Periksa backlog di tab Activity environment, pada halaman admin Cloud environments: runner tidak mengekspor seri kedalaman antrean.

Untuk pelaporan hasil per sesi, gunakan hook post-session sebagai gantinya: hook ini dipicu di setiap akhir sesi ketika proses anak telah di-spawn, kecuali pada penghentian runner secara mendadak seperti preemption VM, sesuai kontrak hook itu sendiri.

Apa selanjutnya

• Self-hosted environments: lingkungan, runner, dan model session; quickstart dan Deploy to production memegang setup dan operasi
• Customize sessions: wrapper script, lifecycle hook, dan on-demand runner
• Verify session identity: session token, klaim-nya, dan cara memverifikasinya