Information for: DEVELOPERS   PARTNERS

Using scheduled jobs to support your application

To help your application run more efficiently, you must conduct regular website maintenance. You can automate maintenance tasks or jobs to run at scheduled intervals using the Scheduled Jobs page in the Acquia Cloud user interface.

Note for Acquia Cloud Site Factory subscribers

For information about cron and scheduling tasks on Acquia Cloud Site Factory, see Managing cron tasks using the management console.

Scheduled jobs are specific to the environment where they’re created. Although you can’t create a job executing a command across several environments based on the same schedule, you can create a job for each environment, with each job using the same command line and schedule.

You must use the Scheduled Jobs page for scheduled jobs, rather than the default Drupal cron. Compared to Drupal cron, using the Scheduled Jobs page is more reliable, and provides support for adding extensive and integrated logging for Acquia Cloud applications.

Disabling Drupal cron

By default, Drupal cron (also known as poor man’s cron) is enabled for websites. Acquia recommends you disable Drupal cron and rely on Acquia Cloud for running scheduled jobs. Using Acquia Cloud for scheduled jobs ensures cron jobs are run on the schedule you specify. Application activity and visiting the application triggers default Drupal cron. Disabling Drupal cron improves reliability and avoids the performance reduction on page requests.

To disable Drupal cron, complete the following steps:

  1. Sign in to your Drupal website as an administrator.
  2. Go to Configuration > System > Cron (http://[site_URL]/admin/config/system/cron).
  3. In the Run cron every list, click Never.
  4. Click Save configuration.

Creating scheduled jobs

Dedicated cron servers on Acquia Cloud Enterprise

Some Acquia Cloud Enterprise subscriptions have a dedicated cron server because of the particular performance needs of their applications. To configure a scheduled job on a dedicated cron server, contact Acquia Support.

Limitations apply when creating scheduled jobs. To create a new cron job for an environment, complete the following steps:

  1. Sign in to Acquia Cloud.

  2. Select an application and an environment.

  3. Click Scheduled Jobs.

  4. Click Add Job to add a scheduled job.

    Add a scheduled job image

  5. In the Create a new scheduled job on [env] dialog, enter a descriptive name for the job in the Job name field.

  6. In the Command field, enter the command you want Acquia Cloud to routinely run for the environment. You can enter any commands allowed from an SSH connection to the environment, as long as they meet the limits and special considerations for scheduled jobs.

    Note

    For some common cron examples you can use in this field, see Cron command examples. You must test commands using SSH in your Acquia Cloud environment to ensure they work before adding the commands as automated cron commands.

    Enter information about the scheduled job image

  7. Select how often you want to run the command from the menus in the Command frequency section:

    • Every minute
    • Every hour, at a number of minutes past the hour
    • Every day, at a certain time
    • Every week, at a certain day of the week and time of day
    • Every month, at a certain day of the month and time of day
    • Every year, at a certain month, day of the month, and time of day

    All times are UTC. As an alternative, you can enter the cron frequency as a string. For more information, see Cron time string format.

    Note

    Running cron too often can affect performance.

  8. Click Add.

    After you create a new job, Acquia Cloud displays the job in the list of scheduled jobs for the environment where it was created.

Limitations

When creating scheduled jobs, the following limitations apply:

  • Commands in scheduled jobs can’t be longer than 255 characters. If you must run a command longer than 255 characters, you must incorporate it by running a shell script you run as a scheduled job.
  • The % character is a special character in cron commands. If your command uses this special character, be sure to precede it with a backslash (\). For example: your_log_file_$(date +\%F).log.

Scheduled job output

When a scheduled job runs, and the output isn’t redirected to stdout, the cron user sends an email to the application user on the same server. Acquia Cloud saves the email in /var/mail.

Important

If the messages are never picked up or cleared, the messages fill the disk, which can cause serious problems, including possibly bringing down your application.

To avoid issues, scheduled jobs must always include a logging statement. For example, you could use the following statement, replacing [site-uri] with the base URL to the website where you want to run cron:

/usr/local/bin/drush9 --uri=http://[site-uri] --root=/var/www/html/${AH_SITE_NAME}/docroot -dv cron &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log

In the following example, &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log logs the cron output to a drush-cron.log file in the server’s logs directory, where the output will be rotated along with the other logs in the logs directory. The log file will be rotated only if the file is named drush-cron.log. For more information, see About Acquia Cloud logging.

To improve usability, you can also add a timestamp to the log messages, as displayed in the following example, replacing [SITEURL] with the base URL to the website where you want to run cron. You must run the following example as a standalone script, because it exceeds the 255 character limit for scheduled jobs. The following example serves as a general guide for creating similar scripts:

/usr/local/bin/drush9 --uri=http://[SITEURL] --root=/var/www/html/${AH_SITE_NAME}.${AH_SITE_ENVIRONMENT}/docroot -dv cron 2>&1 | awk '{print "["strftime("\%Y-\%m-\%d \%H:\%M:\%S \%Z")"] "$0}' &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log

Managing scheduled jobs

Each job you create on the Scheduled Jobs page has links to help you manage the job, which allow you to do the following:

  • Disable: Stops the scheduled job from running until you click Enable. Disabled jobs move to the Disabled list that follows the Enabled list.
  • Edit: Opens a window allowing you to change the attributes of the scheduled job. After you make your changes, click Edit.
  • Remove: Opens a window deleting the scheduled job when you click Remove. If you remove a scheduled job, you can’t recover it, and you must manually recreate it to restore the job.

Note

You can’t edit or remove administrative jobs you didn’t create for your environments, including automated nightly backups.

Cron and memory limits

Two approaches in using drush cron are to Use the Acquia Cloud wrapper script for drush cron or to Run drush cron directly. The preceding approaches have different memory limits. When you use the Acquia cron wrapper, the cron job uses the PHP memory limit for your environment (by default, 128 MB).

When you use cron directly, it uses the command line process memory limit, which is 512 MB. If you find your cron jobs fail to complete, try defining them to use drush cron directly to take advantage of the greater memory limit. For related information, see Debugging cron.

Cron command examples

Use the following examples as you create scheduled jobs for your application’s environments.

Using drush cron

To use drush cron for enhanced cron performance, select from the following methods:

In each of the following examples:

  • [site] is the name of your application on Acquia Cloud.
  • [env] is your environment (typically one of dev, test, or prod).
  • [site_URL] is your environment’s URL (as listed on the Cloud > Domains page). If you are using Drupal multisite, your cron jobs are specific to each website in the multisite installation. Use the URL of the website in the installation you want to target.

Using the Acquia Cloud wrapper script for drush cron

Use a cron command like the following example:

/usr/local/bin/cron-wrapper.sh [site].[env] http://[site_URL]

You must not append a cron_key to the website URL. Acquia Cloud logs the output of drush cron to a file with a name like /var/log/sites/[site].[env]/logs/[server]/drush-cron.log. For example, if you named your website example, you could name the log file for the prod environment /var/log/sites/example.prod/logs/web-9876/drush-cron.log.

Running drush cron directly

/usr/local/bin/drush9 --uri=http://[site-uri] --root=/var/www/html/${AH_SITE_NAME}/docroot -dv cron &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log

In the following example, &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log logs the cron output to a drush-cron.log file in the server’s logs directory. As already noted, cron jobs must always include a logging statement.

For instances where you want a single hook, you can also run a specific cron hook directly. The command structure will vary based on your Drupal version and module. For example:

drush -v ev "mymodule_cron();"  &>> /var/log/sites/${AH_SITE_NAME}/logs/$(hostname -s)/drush-cron.log

The previous command will log output to the standard log files, ensuring log rotation and maintenance continues.

Running a shell script

You can create scheduled jobs to run shell scripts you have written.

Note

Acquia recommends using a shell script for running complex or long cron commands. This method ensures complex commands can be stored in version control when necessary, enables more controlled error logging, and prevents potential problems submitting the commands to the Acquia Cloud interface.

The following example assumes you have added scripts/my-script.sh to your repository:

/var/www/html/[site].[env]/scripts/my-script.sh

where [site].[env] is your site name and environment.

Note

Acquia highly recommends adding your shell scripts to your source code repository. Acquia also recommends adding a library or scripts folder to your repository in the same directory as acquia-utils and docroot.