📘 תיעוד 143

הפניה לסביבות באירוח עצמי

הפניה מלאה ל-runner ול-orchestrator באירוח עצמי: דגלי CLI, משתני סביבה ומדדי Prometheus.

[!NOTE]

סביבות באירוח עצמי נמצאות בבטא ציבורית בתוכניות Team ו-Enterprise. Owner מפעיל אותן על ידי הפעלת Allow self-hosted environments בדף הניהול Cloud environments. הדף הזה הוא ההפניה לדגלים ולמדדים. ראו את ה-quickstart להתקנה ואת Deploy to production למתכוני הצי.

הדף הזה הוא ההפניה לשני התהליכים שאתם מריצים בסביבה באירוח עצמי: ה-runner, שמריץ cloud sessions של Claude Code על המארחים שלכם, וה-orchestrator האופציונלי ל-autoscaling, שמתחיל runners כש-sessions נכנסים לתור. לכל אחד טבלת דגלים משלו. שניהם רצים על מארחי Linux או macOS, שהברירות המחדל כמו /workspace ו-~/.claude מניחות. הריצו claude self-hosted-runner --help לרשימה הסמכותית בגרסה המותקנת אצלכם.

סדרות מדדים וכמה שדות API עדיין משתמשים ב-pool למה שהדפים האלה קוראים environment. שני המונחים מציינים את אותו הדבר. מזהה ה-environment הוא השדה pool_id, בצורה ccpool_...: בכל מקום שהדפים האלה מציגים מזהה pool, הוא מציין את ה-environment. דגלי CLI ומשתני סביבה כותבים אותו environment, למשל --environment-secret-file. איותי pool שיצאו משימוש עדיין עובדים, כפי שמתארת השורה של --environment-secret-file.

#דגלי CLI של ה-runner

לרוב הדגלים יש משתנה סביבה מתאים. כששניהם מוגדרים, הדגל גובר. דגלי משך מקבלים דקות או שניות ב-CLI, אבל משתנה הסביבה המזווג תמיד במילישניות, כפי שמציינת הסיומת _MS, ועמודת ברירת המחדל מציגה את יחידת הדגל: --exit-if-unused-min 10 שקול ל-SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, וערך Helm כמו SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" פירושו 15 מילישניות, ולא ברירת המחדל של 15 דקות.

לרוב דגלי המשך יש מקסימום, שנבחר כדי לשמור כל פסק זמן בתוך תקרת הטיימר של 32 סיביות של זמן הריצה, בערך 24.85 ימים. דגלי --*-min מוגבלים ל-10080 דקות, 7 ימים. --drain-grace-sec ל-604800 שניות, גם 7 ימים. ו---drain-wait-sec ל-86400 שניות, 24 שעות. --session-stop-grace-sec ו---post-session-hook-timeout-sec בלי תקרה. חריגה מתקרה מתנהגת אחרת לפי משטח:

• דגל: ההפעלה נכשלת עם שגיאה.
• משתנה סביבה: ה-runner מצמיד את הערך לתקרת הטיימר במקום לדחות אותו.

#פסק זמן להפעלת סשן

אם סשן איבד את המשבצת שלו במהלך תור כמו /code-review, עדכנו את ה-runner ואת הבינארי של הילד ל-v2.1.309 או לגרסה חדשה יותר. מ-v2.1.299 ועד v2.1.308, ה-runner שחרר סשן, גם באמצע תור, ברגע שפסק הזמן להפעלה חלף בלי הודעת user או assistant.

עם --startup-timeout-min <n>, ה-runner משחרר את המשבצת של סשן כשהילד שלו לא אותחל בתוך <n> דקות אחרי השכפול. במהלך תור שמתחיל לפני שהילד מאותחל, הסשן שומר את המשבצת שלו עד שחולפות <n> דקות בלי שורה בערוץ הפעילות של הילד. מרגע שהילד מאותחל, ה-runner מאפס את הספירה הזו ו---release-idle-session-min קובע את השחרור. כדי להגביל סשן שהילד שלו חי אבל תקוע, הגדירו --kill-session-after-min.

#רשימות כללים של מצב אוטומטי

--server-auto-mode-lists מאפשר לכם להחליט אילו כללי מסווג של מצב אוטומטי שמחוץ ל-runner מגיעים אל הסשנים על ה-runners שלכם. מישור הבקרה של Anthropic יכול לשלוח רשימות כללים עם סשן ולבקש מה-runner להחיל אותן. ייתכן שחלק מהרשומות הן כללים שמנהל בארגון שלכם כתב. הרשימות הן environment, soft_deny ו-allow:

• environment: רשומה יכולה לגרום למסווג להתיר יותר וגם פחות.
• soft_deny: רשומה חוסמת פעולה אלא אם המשתמש ביקש אותה במפורש או שחל חריג allow.
• allow: החריגים לרשומות soft_deny.

הערך של הדגל קובע אילו רשימות ה-runner מחיל:

• no-allow: ברירת המחדל. מחיל את environment ואת soft_deny ואינו מחיל את allow. רשומת environment עדיין יכולה לגרום למסווג להתיר יותר, ולכן ברירת המחדל אינה שוללת כל הקלה.
• all: מחיל את שלוש הרשימות.
• none: אינו מחיל אף אחת מהן. בחרו none כדי לשלול כל הקלה מהרשימות האלה. הבחירה הזו גם מסירה את המגבלות של soft_deny.

אין הגדרה של ה-runner שגורמת למישור הבקרה לבקש מה-runner להחיל את הרשימות. כשהוא אינו מבקש, הסשנים אינם מקבלים רשימה, בכל ערך שתגדירו. כדי לראות איזה משני המקרים קרה, הפעילו את ה-runner עם --log-level debug. עבור כל סשן ה-runner כותב אז שורה שמכילה the server asked this runner to apply, או שורה שמכילה the server did not ask this runner to apply the auto mode lists it sends.

#דגלי CLI של ה-orchestrator

פקודת המשנה self-hosted-runner orchestrator, שיוצרת runners לפי דרישה, מקבלת את --api-url, --environment-secret-file, --hooks-dir, --health-port ו---log-level עם אותן ברירות מחדל כמו ה-runner, ובמקום שלדגל של ה-runner יש משתנה סביבה, עם אותו משתנה סביבה, חוץ מכך ש---hooks-dir נדרש וחייב להכיל hook בשם spawn-runner. יש לה גם דגלים משלה:

#דגלי מחבר SCM

מחבר ה-SCM אינו זמין, לכן השאירו את הדגלים בסעיף זה לא מוגדרים. אם תגדירו --scm-connector-host, החיבור אינו נפתח, וה-orchestrator ממשיך לנסות אותו. runners עדיין מתחילים כשסשנים נכנסים לתור.

המחבר הוא חיבור WebSocket קבוע מה-orchestrator אל מישור הבקרה של Anthropic. הוא נועד לאפשר לזרימות מתארחות שלפני הסשן, כמו בוחר המאגר והפותר של ענף או ref, להגיע למארח GitHub Enterprise Server שאפשר לנתב אליו רק מתוך הרשת שלכם. ראו דרישות רשת בדף GitHub Enterprise Server לגבי מה שהזרימות האלה צריכות.

בכל ניסיון חיבור ה-orchestrator שולח את סוד הסביבה הקיים שלו, והוא מנסה שוב אוטומטית עם השהיה מעריכית, עם תקרה של 30 שניות בתוספת jitter.

#הגדרות דרך משתני סביבה בלבד

הגדרות runner אלה נקראות מהסביבה בלבד ומכסות התנהגות שרוב הפריסות משאירות בברירת המחדל:

#טלמטריה

ילדי הסשן שולחים טלמטריה תפעולית ל-Anthropic אלא אם תכבו אותה. לא נשלח קוד ולא נשלח תוכן של מאגר. הגדירו את משתני הטלמטריה על תהליך ה-runner. ה-runner מחיל אותם מחדש אחרי שהוא מחיל משתני סביבה שסיפק השרת, ולכן ההגדרה של המפעיל תמיד גוברת.

בקרה אחת ייחודית לסביבות באירוח עצמי: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 מפעיל הצטרפות למדדים תפעוליים של Datadog, שכבויים כברירת מחדל בסביבות באירוח עצמי. בקרי הטלמטריה הכלליים של Claude Code, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING ו-CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, חלים על ילדי הסשן כפי שמתועד בהפניה למשתני סביבה. DISABLE_GROWTHBOOK קשור אבל שונה: הגדרת DISABLE_GROWTHBOOK=1 משביתה שליפה של דגלי תכונות, והטלמטריה נשארת פעילה אלא אם מוגדר גם DISABLE_TELEMETRY.

CLAUDE_CODE_ENABLE_TELEMETRY אינו קשור: הוא מפעיל ייצוא OpenTelemetry אל האספן שלכם, כפי שמתואר בניטור, ואינו שולט באנליטיקה של Anthropic.

#נקודת קצה לתקינות

ה-runner מגיש GET /healthz בפורט התקינות שהוגדר. התגובה היא 200 OK בכל פעם שהתהליך חי, בכל מצב שבו נמצאת לולאת ה-poll, ולכן בדיקת HTTP על נקודת הקצה הזו מזהה רק תהליך מת. גוף ה-JSON מתאר את המצב הנוכחי:

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

התריעו על last_poll_age_ms, ואל תשתמשו בו בבדיקת חיות. השאירו את הבדיקה הזו על קוד המצב של HTTP. הערך הוא הזמן שעבר מאז ה-poll המוצלח האחרון, ולכן הוא עולה גם כשה-runner לא יכול להגיע אל Anthropic. גם last_poll_at וגם last_poll_age_ms הם null עד שה-poll הראשון מצליח. כדי לתפוס polls שנכשלים כבר מההתחלה, התריעו גם על claude_code_self_hosted_runner_poll_errors_total, שרשום תחת מדדי Prometheus.

נקודת /healthz של ה-orchestrator עצמו, על פורט התקינות שלו, תמיד מחזירה 200. הגוף כולל שדה connected שמדווח אם ה-poll האחרון הצליח, ובנוסף ספירות של תור spawn לפי מצב ב-queue_counts. כדי לראות למה connected הוא false, קראו את השדה last_error ברמה העליונה. כל poll מוצלח מאפס אותו ל-null. התנו מוכנות והתראות לפי connected ולא לפי קוד המצב.

כשמחבר SCM מוגדר, גוף /healthz של ה-orchestrator כולל גם את scm_connector_connected ואובייקט scm_connector עם connected, last_connected_at, last_error, reconnects ו-requests_forwarded. שני השדות הם null כש---scm-connector-host אינו מוגדר.

#מדדי Prometheus

כל runner מגיש מדדי Prometheus ב-GET /metrics על אותה יציאה כמו /healthz. סדרות מרכזיות:

ה-orchestrator מגיש סדרות משלו ב-GET /metrics על אותה יציאה כמו ה-/healthz שלו:

לצורך autoscaling, בחרו את הסדרה שתואמת את סגנון ה-scaling שלכם, וסננו אותה לפני שהיא מזינה את ה-scaler:

• scaling לפי עומק תור: הזינו את claude_code_self_hosted_orchestrator_pool_pending_sessions ל-scaler של HPA או של KEDA, ולא את queue_pending_sessions.
• scaling לפי קיבולת: בצעו scaling לפי היחס בין active_sessions של ה-runner לבין capacity.
• סינון לפי connected: סננו את השאילתה עם claude_code_self_hosted_orchestrator_connected == 1 לכל מופע, כדי שערך מיושן של replica מנותק לא יזין את ה-scaler.

בזמן השבתה מלאה של poll, כשכל replica מנותק, השאילתה המסוננת לא מחזירה נתונים. HPA שומר על מספר ה-replicas הנוכחי כשהמדד חסר, אבל ה-Prometheus scaler של KEDA, בברירת המחדל ignoreNullValues: "true", קורא את התוצאה הריקה כאפס ומבצע scale in. הגדירו ignoreNullValues: "false" ב-ScaledObject, ואפשר גם עם רצפת replicas ב-fallback.

ה-PodMonitor הבא של Prometheus Operator מכסה את שני התהליכים. הוא בוחר pods לפי התווית app.kubernetes.io/part-of: claude-code-self-hosted-runner ולפי היציאה בשם health שמתכון Kubernetes מגדיר. התאימו את ה-namespaces לפריסה שלכם:

# 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

#כללי התראה לדוגמה

כללי ההתראה לדוגמה האלה הם נקודת התחלה. כווננו את הספים לגודל הצי שלכם:

# 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"

#התראה על runners שאבדו ועל סשנים ממתינים

כדי לקבל התראה כש-runners אבדו, סשנים ממתינים, או שה-orchestrator לא פעיל, טענו את כללי ההתראה האלה של Prometheus לצד כללי ההתראה לדוגמה:

• צי קבוע: ClaudeRunnersBelowFloor
• runners לפי דרישה: ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh ו-ClaudeOrchestratorAbsent

#התראה כשצי קבוע מאבד runners

ClaudeRunnersBelowFloor מופעל כשמספר ה-runners הרשומים שנגרדו נמוך מהרצפה במשך 10 דקות:

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."

• רצפה: הגדירו את 2 ב-expr לכמחצית מספר ה-replicas, מעוגל כלפי מעלה. עם שלושה replicas השאירו 2, וההתראה מופעלת כשנותר runner אחד או אף אחד.
• Namespace: החליפו את claude-runners ב-matcher וב-labels, והעתיקו את ההתראה לכל namespace נוסף. אם ליעדים שלכם אין תווית namespace, הסירו את ה-matcher ואת התווית, אחרת ההתראה קוראת 0 ומופעלת.
• ClaudeRunnerPollStale ו-ClaudeRunnerPollErrors: השאירו אותם טעונים מתוך כללי ההתראה לדוגמה, כי ClaudeRunnersBelowFloor עדיין סופר runner שלא יכול לבצע poll

#התראה כשסשנים ממתינים ל-runners לפי דרישה

ClaudeOrchestratorSessionsWaiting מופעל כשמספר הסשנים שממתינים ל-runner נשאר מעל 0 במשך 10 דקות. ClaudeOrchestratorQueueWaitHigh מופעל כשיותר מ-1% מההמתנות בתור ב-10 הדקות האחרונות חרגו מ-160 שניות, וזה נמשך 5 דקות:

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."

• סף: אם סשן כלשהו תמיד ממתין, העלו את > 0 ב-ClaudeOrchestratorSessionsWaiting מעל המספר שאתם רואים בדרך כלל
• ClaudeOrchestratorDisconnected: השאירו אותו טעון מתוך כללי ההתראה לדוגמה, כי ClaudeOrchestratorSessionsWaiting מפסיק להיות מופעל כ-2 דקות אחרי שה-orchestrator האחרון ב-namespace מתנתק

#התראה כשה-orchestrator לא פעיל

כדי לדעת שה-orchestrator עצמו לא פעיל, טענו את ClaudeOrchestratorAbsent. הוא מופעל כשאף orchestrator ב-namespace לא נגרד במשך 5 דקות:

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: החליפו את claude-runners ב-namespace של ה-orchestrator, והעתיקו את ההתראה לכל namespace נוסף שמריץ orchestrator. אם ליעדים שלכם אין תווית namespace, הסירו את ה-matcher, אחרת ההתראה מופעלת אחרי 5 דקות ונשארת פעילה.
• שרתי Prometheus שלא גורדים את ה-orchestrator: השאירו את ההתראה מחוץ לקובצי הכללים שלהם, כי בשרת כזה היא מופעלת אחרי 5 דקות ונשארת פעילה
• אל תסתמכו על ההתראות האחרות של ה-orchestrator: הן קוראות מדדים שה-orchestrator עצמו מגיש. ClaudeOrchestratorSessionsWaiting, ClaudeOrchestratorQueueWaitHigh וכללי ההתראה לדוגמה של ה-orchestrator מפסיקים כולם להיות מופעלים בתוך כ-10 דקות מרגע שה-orchestrator יורד.

#העברת מדדי תהליך בן של סשן

כל סשן רץ בתהליך בן משלו עם מדדי OpenTelemetry משלו. כש---capacity מעל אחד, ה-runner משכתב את אופן החשיפה של מדדי הבן האלה. הגדרת OTEL_METRICS_EXPORTER=prometheus על מארח ה-runner ו-CLAUDE_CODE_ENABLE_TELEMETRY=1 בסביבת הסשן, למשל מתוך סקריפט העטיפה או מסביבת ה-runner עצמו, שסשנים יורשים, חושפת מחדש את מכשירי ה-counter וה-gauge של כל בן בנקודת הקצה /metrics של ה-runner עצמו, לצד הסדרות של ה-runner. ה-runner משכתב את ה-exporter של הבן כך שידחוף ב-OTLP למקלט על loopback בלבד בפורט הבריאות, מתייג כל סדרה בתוויות session_id ו-client_platform, ומפנה את הסדרות של סשן כשהסשן מסתיים. היסטוגרמות לא עוברות, ומדד בן ששמו היה מתנגש עם הקידומת של ה-runner עצמו מושמט.

ברירת המחדל --capacity 1, השכתוב לא חל: תהליך הבן של הסשן קושר נקודת קצה Prometheus משלו בפורט 9464 כרגיל.

#צירוף מדדי סשן למדדי ה-runner

כדי לראות מה עלו סשנים במצב idle, צרפו את claude_code_self_hosted_runner_session_idle_seconds של ה-runner למדד העלות של Claude Code על ccr_session_id. למדד של ה-runner אין את התווית הזאת, אז תנו לו אחת עם label_replace, כמו בשאילתה הזאת:

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

השאילתה מחזירה תוצאה אחת לכל סשן ב-idle יותר מעשר דקות: העלות בדולר אמריקאי שתהליך Claude Code שלו ספר עד כה. כדי לצרף מדד Claude Code אחר, החליפו את claude_code_cost_usage_total בשאילתה. השאילתה עובדת בכל --capacity.

• session_id: בפורט 9464, התווית הזאת על מדדי Claude Code מחזיקה את session.id של Claude Code עצמו, שלא תואם לאף סדרה של ה-runner. צירוף עליה לא מחזיר כלום, אז צרפו על ccr_session_id.
• למדדי Claude Code אין ccr_session_id: בדקו ש-OTEL_METRICS_INCLUDE_SESSION_ID לא מוגדר ל-false

#סמנטיקה של מוני מחזור חיי סשן

המונים sessions_started_total, sessions_completed_total, sessions_failed_total ו-sessions_interrupted_total מסווגים כל סשן לפי אופן הסיום שלו. כל תהליך בן של סשן שנוצר מגדיל את sessions_started_total בזמן ה-spawn, ובדיוק אחד משלושת האחרים גדל ביציאה, כך ש-sessions_started_total פחות סכום שלושת האחרים שווה למספר תהליכי הבן של סשנים שרצים כרגע.

• completed: הסשן הסתיים בצורה נקייה. זה מכסה יציאה עצמית של הבן עם קוד 0, ארכוב או מחיקה של הסשן בזמן שהבן עדיין היה מחובר, והחזרה נקייה של המשבצת על ידי ה-runner: שחרור הסשן ב-timeout של idle, בזמן ה-retire, או במגבלת --kill-session-after-min, timeout של הפעלה, או deassign מצד השרת שלולאת ה-poll הבחינה בו לפני שהבן יצא. מגדיל את sessions_completed_total.
• failed: הבן יצא בעצמו עם קוד שאינו אפס, קריסה או כשל הגדרה אחרי spawn. מגדיל את sessions_failed_total.
• interrupted: ה-runner סיים את הבן מסיבה תפעולית שהיא לא הצלחת סשן ולא תקלה של ה-runner, למשל drain, או סיום סשן שעדיין היה על ה-runner כשחלון החסד SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS אחרי מגבלת --kill-session-after-min שלו הסתיים. הפעלה מחדש מתגלגלת ב-Kubernetes ששולחת SIGTERM היא דוגמה אחת ל-drain. מגדיל את sessions_interrupted_total.

לפני v2.1.260, ה-runner סיים כל סשן שהגיע למגבלת --kill-session-after-min שלו וספר אותו ב-sessions_interrupted_total.

CLAUDE_RUNNER_EXIT_REASON של ה-hook מסוג post-session מסווג מסירות נקיות אחרת. ה-hook מדווח על אלה כ-interrupted, כי ה-runner עצר את הבן: שחרור, timeout של הפעלה, deassign מהשרת, וארכוב או מחיקה שה-poll הבחין בהם קודם. המונים האלה רושמים את אותם אירועים כ-completed, כי המשבצת הוחזרה בצורה נקייה.

אם משווים קבלות של ה-hook מול sessions_completed_total ישירות, סופרים פחות השלמות. השתמשו ב-hook לערבויות לכל סשן ובמונים לשיעורים מצטברים.

בסביבה חד פעמית, --capacity 1 עם ברירת המחדל --drain-grace-sec 0, כל תהליך runner יוצא רגעים אחרי שהסשן היחיד שלו מסתיים. sessions_completed_total, sessions_failed_total ו-sessions_interrupted_total גדלים רק בסוף הסשן, ממש לפני היציאה הזאת, כך ש-scrape של Prometheus כל 15 עד 60 שניות כמעט לא תופס את ההגדלה לפני שסדרות ה-runner נעלמות. שלושת מוני סוף הסשן האלה הם המונים הסופיים ששאר הסעיף הזה מתייחס אליהם. sessions_started_total גדל ב-spawn ונשאר גלוי למשך חיי הסשן, ולכן הוא מופיע באופן אמין, אבל בסביבה חד פעמית הוא קרוב יותר ל"סשנים שרצים כרגע" מאשר לספירה מצטברת.

השתמשו בסדרות בטבלה הזאת למטרה המתאימה במקום במונים הסופיים:

שורות orchestrator_* קיימות רק בסביבות שמריצות את ה-orchestrator לפי דרישה. בצי קבוע שה-runners שלו מאריכים ימים אחרי הסשנים, עם --drain-grace-sec מעל 0, השתמשו ב-sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) לתפוקה. בצי חד פעמי לסדרה הזאת יש אותה בעיית חלון scrape כמו למונים הסופיים, אז הסתמכו במקום זאת על ספירת הסשנים בתור. בדקו צבר בלשונית Activity של הסביבה, בדף הניהול Cloud environments: ה-runners לא מייצאים סדרת עומק תור.

לדיווח תוצאה לכל סשן, השתמשו ב-hook מסוג post-session: הוא מופעל בכל סוף סשן שבו נוצר תהליך בן, מלבד סיום פתאומי של ה-runner כמו preemption של VM, לפי החוזה של ה-hook עצמו.

#מה הלאה

• סביבות self-hosted: מודל הסביבה, ה-runner והסשן. ההתחלה המהירה ו-פריסה לייצור מכילים הקמה ותפעול
• התאמת סשנים: סקריפטי עטיפה, hooks של מחזור חיים, ו-runners לפי דרישה
• אימות זהות סשן: טוקן הסשן, ה-claims שלו, ואיך לאמת אותו