Checking Airflow Health Status

Airflow has two methods to check the health of components - HTTP checks and CLI checks. All available checks are accessible through the CLI, but only some are accessible through HTTP due to the role of the component being checked and the tools being used to monitor the deployment.

For example, when running on Kubernetes, use a Liveness probes (livenessProbe property) with CLI checks on the scheduler deployment to restart it when it fails. For the webserver, you can configure the readiness probe (readinessProbe property) using Health Check Endpoint.

For an example for a Docker Compose environment, see the docker-compose.yaml file available in the Running Airflow in Docker.

Health Check Endpoint

To check the health status of your Airflow instance, you can simply access the endpoint /health. It will return a JSON object in which a high-level glance is provided.

    "latest_scheduler_heartbeat":"2018-12-26 17:15:11+00:00"
  • The status of each component can be either “healthy” or “unhealthy”

    • The status of metadatabase depends on whether a valid connection can be initiated with the database

    • The status of scheduler depends on when the latest scheduler heartbeat was received

      • If the last heartbeat was received more than 30 seconds (default value) earlier than the current time, the scheduler is considered unhealthy

      • This threshold value can be specified using the option scheduler_health_check_threshold within the [scheduler] section in airflow.cfg

      • If you run more than one scheduler, only the state of one scheduler will be reported, i.e. only one working scheduler is enough for the scheduler state to be considered healthy

Please keep in mind that the HTTP response code of /health endpoint should not be used to determine the health status of the application. The return code is only indicative of the state of the rest call (200 for success).


For this check to work, at least one working web server is required. Suppose you use this check for scheduler monitoring, then in case of failure of the web server, you will lose the ability to monitor scheduler, which means that it can be restarted even if it is in good condition. For greater confidence, consider using CLI Check for Scheduler.

CLI Check for Scheduler

Scheduler creates an entry in the table with information about the host and timestamp (heartbeat) at startup, and then updates it regularly. You can use this to check if the scheduler is working correctly. To do this, you can use the airflow jobs checks command. On failure, the command will exit with a non-zero error code.

To check if the local scheduler is still working properly, run:

airflow jobs check --job-type SchedulerJob --hostname "$(hostname)"

To check if any scheduler is running when you are using high availability, run:

airflow jobs check --job-type SchedulerJob --allow-multiple --limit 100

CLI Check for Database

To verify that the database is working correctly, you can use the airflow db check command. On failure, the command will exit with a non-zero error code.

HTTP monitoring for Celery Cluster

You can optionally use Flower to monitor the health of the Celery cluster. It also provides an HTTP API that you can use to build a health check for your environment.

For details about installation, see: Celery Executor. For details about usage, see: The Flower project documentation.

CLI Check for Celery Workers

To verify that the Celery workers are working correctly, you can use the celery inspect ping command. On failure, the command will exit with a non-zero error code.

To check if the worker running on the local host is working correctly, run:

celery --app inspect ping -d celery@${HOSTNAME}

To check if the all workers in the cluster running is working correctly, run:

celery --app inspect ping

For more information, see: Management Command-line Utilities (inspect/control) and Workers Guide in the Celery documentation.

Was this entry helpful?