Pool Classifier

Pool Classifier is a Cloud Run service and Flask dashboard for monitoring Taskcluster worker pools. It periodically classifies recent task results, matches task logs against failure patterns, and surfaces pool health, alerting workers, success rates, and unclassified failures.

The Python package remains named worker_health for compatibility after the repository extraction. Those package-path references are vestigial.

Quick start

uv sync --group dev
./pc_db.sh init
./pc_start.sh

The local dashboard is available at http://localhost:8080/. A Taskcluster token is required at ~/.tc_token; see the development guide for its format and the complete local workflow.

To inspect current detail-page code without waiting for a classifier to replace a cached dashboard snapshot, start a separate local listener with snapshots disabled:

PC_PORT=8081 POOL_CLASSIFIER_DISABLE_DASHBOARD_SNAPSHOTS=1 ./pc_start.sh

Documentation

Development

• Local setup, configuration, tests, and local tools

Operations

• Cloud Run runbook
• Release and ad-hoc deployment procedure
• Production database maintenance
• Backfill observed start-lag metadata
• Backfill recent job-source metadata

API reference

• Public API
• Utilization API
• Observed scheduled-to-start lag API

Design and history

• Utilization and queue lag for pool sizing
• Fitness and Pool Classifier comparison
• Cloud Run migration history
• Dashboard query refactor
• 2026-07-30 database migration-lock incident

Repository layout

worker_health/
  pool_classifier.py                  # Taskcluster polling and classification
  pool_classifier_web/                # Flask app, storage, migrations, and Terraform
tests/                                # pytest suite
scripts/                              # test, build, benchmark, and maintenance helpers