Managing cron tasks using the management console

Managing cron tasks using the management console

Websites use cron to perform maintenance tasks to help ensure they remain healthy. Since websites need these maintenance tasks to run regularly, it’s helpful to have cron run on a recurring, automated schedule. To enable you to control the frequency of cron’s execution on your websites, Site Factory provides a Cron jobs page, allowing you to create, modify, and delete scheduled cron jobs.

The cron jobs you create are specific to the environment (glossary term, activate to view definition) and stack in which they exist. For example, if you create a cron job on your Testing environment, that job will not exist on your Production environment unless you manually create the same job in the Production environment, using the same command line and schedule.

Your created cron jobs will execute in batches to prevent your server from overloading, and there is no guarantee that cron jobs will first run on specific websites. While cron jobs execute for an environment, your task logs will display one or more CronController message entries.

Creating a cron job

To create a cron job for your Factory environment:

1. Sign in to the Site Factory Management Console using an account with the platform admin role.

2. In the admin menu, click Administration, and then, under Site Factory management, click the Cron link.

   The Cron jobs page displays and lists any pre-configured cron jobs in your Site Factory environment.

3. Click Add Cron job.

   

4. Enter a descriptive Name for your new cron job.
5. Ensure the Enabled checkbox is selected. If you clear this checkbox, Site Factory will create the cron job, but will not execute the job based on its defined interval until you enable the job.
6. If your Site Factory has more than one stack, select the stacks this cron job should apply to.
7. In the Scope section, select from the following options based on your needs:
   • Sites with custom domains only
   • Sites without custom domains only
   • All sites

8. In the Drush command field, enter the command you want to schedule for execution. For example, to schedule cron to run on your websites, enter cron in the field. Do not include a --uri option or Drush aliases, as Site Factory will add them to your command.

   Acquia recommends wrapping complex cron jobs in a shell script to reduce errors. For information about advanced options available for this field, see Evaluating PHP in cron jobs.

9. In the field, enter how often you want to run the command using the .

Modifying or removing cron jobs

You can manage your created cron jobs from the Cron jobs page, including editing or deleting cron jobs.

Editing cron jobs

To edit an existing cron job:

1. Sign in to the Site Factory Management Console using an account with the platform admin role.
2. In the admin menu, click Administration, and then, under Site Factory management, click Cron jobs link.
3. Find the cron job you want to edit, and then in its Actions list, click Edit job.
4. Modify the values for the cron job to meet your needs, and then click Continue.

The Cron jobs page displays your cron job with its new, revised values.

Deleting cron jobs

To delete a cron job value:

1. Sign in to the Site Factory Management Console using an account with the platform admin role.
2. In the admin menu, click Administration, and then, under Site Factory management, click Cron jobs.
3. Find the cron job you want to delete, and then in its Actions list, click Delete job.
4. To confirm the deletion of the cron job, click Delete.

Troubleshooting cron jobs

If a Drush command fails, troubleshoot the cron job by reproducing the failure on the command line. To simplify troubleshooting, limit the scope of the command to a single website as shown in this example, replacing [DOMAIN_NAME] with the domain name and [DRUSH_COMMAND] with the command you are testing:

drush --root=/var/www/html/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT/docroot --uri=[DOMAIN_NAME] [DRUSH_COMMAND]

After executing the command for a single website, review the command-line output and Drupal Watchdog log for errors.

If your cron job requires logging, Acquia recommends one of the following options:

• Adding code to the Drush command to send logging information to Drupal’s watchdog logs
• Writing debugging information to a separate file

For additional methods for debugging cron jobs, see Debugging cron.

Evaluating PHP in cron jobs

You can evaluate PHP as part of executing a cron job by placing a php-eval command in the Drush field, assuming all command-line arguments are escaped properly. For example, the following php-eval statement tests for a non-production environment, and executes a command if a module is installed there:

php-eval \"if (\\\$_ENV[\"AH_SITE_ENVIRONMENT\"] != \\\"01live\\\" && module_exists(\"nprode_import\")) nprode_import_start_import();\"

Site Factory will include the necessary --uri option and Drush alias.

For PHP statements too complicated to execute in a single php-eval statement, you can use one of the following approaches to execute your custom scripts with a cron job:

• Convert the commands to a PHP file, and then execute the file using Drush with the php-script command, setting the --script-path variable to the full path for your script.
• Convert your command into smaller individual commands, creating cron jobs to run each command in sequence. Before attempting this approach, contact Acquia Support with details about your proposed cron jobs to determine if your environment supports enough concurrency for this approach to succeed.

Allocating resources for cron jobs

Site Factory lets you specify the amount of resources that your cron jobs can utilize. To do so, you can use the Percentage of threads to use field while creating a new cron job.

The Percentage of threads to use value dictates the amount of resources that your cron job uses out of the aggregate resources of all web servers. The impact of this value is on how often a specific web server can run the workload and is dependent on server resources and the command being run. As the same servers distribute web content, improper setting of this value can affect site responsiveness and availability.

Each web server running your sites have two slots of workload. The Percentage of threads to use value indicates how many of these slots are used to run a particular cron command.

For example, you have 9 web servers distributing site content and a cron job where Percentage of threads to use is set to 60. There are 18 available slots. 60% of 18 is 11 slots on which the command can run, rounded to the nearest integer. When a cron task needs to run, at any given time, 11 commands run, evenly distributed across the 9 webs with a maximum of 2 commands per server.

Your created cron jobs will execute in batches to prevent your server from overloading, and there is no guarantee that cron jobs will first run on specific websites. While cron jobs execute for an environment, your task logs will display one or more CronController message entries.

Creating a cron job

To create a cron job for your Factory environment:

1. Sign in to the Site Factory Management Console using an account with the platform admin role.

2. In the admin menu, click Administration, and then, under Site Factory management, click the Cron link.

   The Cron jobs page displays and lists any pre-configured cron jobs in your Site Factory environment.

3. Click Add Cron job.

   

4. Enter a descriptive Name for your new cron job.
5. Ensure the Enabled checkbox is selected. If you clear this checkbox, Site Factory will create the cron job, but will not execute the job based on its defined interval until you enable the job.
6. If your Site Factory has more than one stack, select the stacks this cron job should apply to.
7. In the Scope section, select from the following options based on your needs:
   • Sites with custom domains only
   • Sites without custom domains only
   • All sites

8. In the Drush command field, enter the command you want to schedule for execution. For example, to schedule cron to run on your websites, enter cron in the field. Do not include a --uri option or Drush aliases, as Site Factory will add them to your command.

   Acquia recommends wrapping complex cron jobs in a shell script to reduce errors. For information about advanced options available for this field, see Evaluating PHP in cron jobs.

9. In the Interval field, enter how often you want to run the command using the cron time string format.

   Note

   • Acquia recommends you run cron based on a 12-hour interval (for example, * */12 * * *).
   • Running cron jobs too frequently can affect performance.
10. Based on your Drush command and its interval, enter a value for the Percentage of threads to use. Acquia recommends a value of 60 to balance the cron job’s utilization against any other cron jobs you may have already created for the environment. For more information, see Allocating resources for cron jobs.
11. Click Continue.

Modifying or removing cron jobs

You can manage your created cron jobs from the Cron jobs page, including editing or deleting cron jobs.

Editing cron jobs

To edit an existing cron job:

1. Sign in to the Site Factory Management Console using an account with the platform admin role.
2. In the admin menu, click Administration, and then, under Site Factory management, click Cron jobs link.
3. Find the cron job you want to edit, and then in its Actions list, click Edit job.
4. Modify the values for the cron job to meet your needs, and then click Continue.

The Cron jobs page displays your cron job with its new, revised values.

Deleting cron jobs

To delete a cron job value:

1. Sign in to the Site Factory Management Console using an account with the platform admin role.
2. In the admin menu, click Administration, and then, under Site Factory management, click Cron jobs.
3. Find the cron job you want to delete, and then in its Actions list, click Delete job.
4. To confirm the deletion of the cron job, click Delete.

Troubleshooting cron jobs

If a Drush command fails, troubleshoot the cron job by reproducing the failure on the command line. To simplify troubleshooting, limit the scope of the command to a single website as shown in this example, replacing [DOMAIN_NAME] with the domain name and [DRUSH_COMMAND] with the command you are testing:

After executing the command for a single website, review the command-line output and Drupal Watchdog log for errors.

If your cron job requires logging, Acquia recommends one of the following options:

• Adding code to the Drush command to send logging information to Drupal’s watchdog logs
• Writing debugging information to a separate file

For additional methods for debugging cron jobs, see Debugging cron.

Evaluating PHP in cron jobs

You can evaluate PHP as part of executing a cron job by placing a php-eval command in the Drush field, assuming all command-line arguments are escaped properly. For example, the following php-eval statement tests for a non-production environment, and executes a command if a module is installed there:

Site Factory will include the necessary --uri option and Drush alias.

For PHP statements too complicated to execute in a single php-eval statement, you can use one of the following approaches to execute your custom scripts with a cron job:

• Convert the commands to a PHP file, and then execute the file using Drush with the php-script command, setting the --script-path variable to the full path for your script.
• Convert your command into smaller individual commands, creating cron jobs to run each command in sequence. Before attempting this approach, contact Acquia Support with details about your proposed cron jobs to determine if your environment supports enough concurrency for this approach to succeed.

Allocating resources for cron jobs

Site Factory lets you specify the amount of resources that your cron jobs can utilize. To do so, you can use the Percentage of threads to use field while creating a new cron job.

The Percentage of threads to use value dictates the amount of resources that your cron job uses out of the aggregate resources of all web servers. The impact of this value is on how often a specific web server can run the workload and is dependent on server resources and the command being run. As the same servers distribute web content, improper setting of this value can affect site responsiveness and availability.

Each web server running your sites have two slots of workload. The Percentage of threads to use value indicates how many of these slots are used to run a particular cron command.

For example, you have 9 web servers distributing site content and a cron job where Percentage of threads to use is set to 60. There are 18 available slots. 60% of 18 is 11 slots on which the command can run, rounded to the nearest integer. When a cron task needs to run, at any given time, 11 commands run, evenly distributed across the 9 webs with a maximum of 2 commands per server.