Use the cron.xml
file to define scheduled tasks for your application.
To learn more about scheduling tasks, including how to test, deploy, or delete Cron jobs, see Scheduling Tasks with Cron.
Example
The following is an example cron.xml
file:
<?xml version="1.0" encoding="UTF-8"?>
<cronentries>
<cron>
<url>/recache</url>
<description>Repopulate the cache every 2 minutes</description>
<schedule>every 2 minutes</schedule>
</cron>
<cron>
<url>/weeklyreport</url>
<description>Mail out a weekly report</description>
<schedule>every monday 08:30</schedule>
<timezone>America/New_York</timezone>
</cron>
<cron>
<url>/weeklyreport</url>
<description>Mail out a weekly report</description>
<schedule>every monday 08:30</schedule>
<timezone>America/New_York</timezone>
<target>version-2</target>
</cron>
</cronentries>
For an XSD describing the format, check the file docs/cron.xsd
in the SDK.
Syntax
Thecron.xml
file should reside in the WEB-INF
directory of your application alongside
appengine-web.xml
:
cron.xml
configures scheduled tasks for your Java 8 application.
Cron job definitions
Element | Description |
---|---|
<description> |
Optional. The description is visible in the Cloud Console and the development server's admin interface. |
<retry-parameters> |
Optional. If a cron job's request handler returns a HTTP status code
that is not in the range 200–299 (inclusive) App Engine considers the
job to have failed. By default, failed jobs are not retried. You can
cause failed jobs to be retried by including a retry-parameters block in
your configuration file.
See the Cron retries section for more information. |
<schedule> |
Required. Defines the schedule of when the cron job runs, see the syntax below. |
<target> |
The
If the service name that is specified for |
<timezone> |
The timezone should be the name of a standard
zoneinfo time zone name. If you don't specify a timezone,
jobs run
in UTC (also known as GMT).
|
<url> |
Required.
The <url> field is just a URL in your application. If the
<url> element contains the special XML characters
& , < , > ,
' , or " , you should escape them.
|
Defining the cron job schedule
Cron jobs are scheduled on reoccurring intervals and are specified using a simple English-like format. You can define a schedule so that your job runs multiple times a day, or runs on specific days and months.
- Sub-daily intervals
Use a sub-daily interval to run a job multiple times a day on a repetitive schedule. You can define either an end-time interval, or a start-time interval:
End-time interval: Defines the time between the "end time" of a job and when the next job starts, where the "end time" is either the time at which the job completes or times out. The Cron service runs jobs in this type of interval throughout the 24 hour day, starting at
00:00
, and waits for the specified duration of time between each job.Example: For the
every 5 minutes
schedule, the job is run daily using a 5-minute interval. If one instance of a job that is running on this schedule complete at 02:01, then the next job waits 5 minute and starts again at 02:06.Start-time interval: Defines a regular time interval for the Cron service to start each job. Unlike the end-time interval, the start-time interval runs each job independent of when the prior job completes or times-out. You can set a time range within which you want your job to run, or run jobs 24 hours a day, starting at
00:00
.Because the start time of a job is strict, if an instance of a job runs longer than the defined time interval, then the Cron service can skip a job. An individual start time in the interval can be skipped if the prior job has not completed or times out.
Example: For the
every 5 minutes from 10:00 to 14:00
schedule, the first job starts running at10:00
, and then every 5 minutes thereafter. If that first job runs for 7 minutes, then the10:05
job is skipped, and therefore, the Cron service does not run another instance of this job until10:10
.
- Custom interval
You can use a custom interval to define a schedule where your job can run once per day on one or more select days, and in one or more select months. Jobs that run on a custom schedule run year-round, only at the specific time on the select days and months.
Example: For the
1,2,3 of month 07:00
schedule, the job runs one time at07:00
on the first three days of each month.
Important considerations for schedule
:
- You must decide if you want to use either a sub-daily interval or a custom
interval. You cannot mix and use elements from the various interval
types. The following is an example of an invalid schedule definition:
<schedule>every 6 hours mon,wed,fri</schedule>
. - Only a single instance of a job should run at any time. The Cron service is designed to provide "at least once" delivery; that is, if a job is scheduled, App Engine sends the job request at least one time. In some rare circumstances, it is possible for multiple instances of the same job to be requested, therefore, your request handler should be idempotent, and your code should ensure that there are no harmful side-effects if this occurs.
Formatting the schedule
To specify when your job runs, you must define the schedule
element using the
following syntax:
<schedule>[TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]</schedule>
Choose an interval type to define your schedule
element:
- [TYPE]: Daily intervals must include the
every
prefix.Example:
<schedule>every 12 hours</schedule>
- [INTERVAL_VALUE]: An integer value and the corresponding unit of
time. Valid values for the unit of time:
minutes
ormins
hours
- [INTERVAL_SCOPE]: Not applicable. To set a specific start time or range within which you want your jobs to run, see the syntax for either the Start-time interval or Custom interval.
- End-time interval examples
- Use the following examples to help you understand how to define job
schedules that use an end-time interval:
- Starts running every day at 00:00 and waits 5 minutes in between
each job. After each job ends, the Cron service waits 5 minutes
before running the next job:
<schedule>every 5 minutes</schedule>
- Starts running every day at 00:00 and waits 30 minute in between
each job. After each job ends, the Cron service waits 30 minutes
before running the next job:
<schedule>every 30 mins</schedule>
- Starts running every day at 00:00 and waits 5 minutes in between
each job. After each job ends, the Cron service waits 5 minutes
before running the next job:
- [TYPE]: Daily intervals must include the
every
prefix.Example:
<schedule>every 12 hours</schedule>
- [INTERVAL_VALUE]: An integer value and the corresponding unit of
time. Valid values for the unit of time:
minutes
ormins
hours
- [INTERVAL_SCOPE] Specifies a clause that corresponds with the
[INTERVAL_VALUE]. You can define a custom time range or use the 24 hr
synchronized
option.- Include the
from [HH:MM] to [HH:MM]
clause to define a specific start time and range within which you want to run jobs.You must specify the time values in the 24 hour format,
HH:MM
, where:HH
are integers from00
to23
.MM
are integers from00
to59
.
- Use
synchronized
to specify a 24 hour time range (from 00:00 to 23:59
) that is evenly divided by the [INTERVAL_VALUE] value.Important: The [INTERVAL_VALUE] must divide 24 into an integer, otherwise the an error occurs. Valid values for [INTERVAL_VALUE] include:
1
,2
,3
,4
,6
,8
,12
, or24
.
- Include the
- Start-time interval examples
- Use the following examples to help you understand how to define job
schedules that use a start-time interval:
- Runs every 5 minutes from 10:00 to 14:00, every day:
<schedule>every 5 minutes from 10:00 to 14:00</schedule>
- Runs once every hour from 08:00 to 16:00, every day:
<schedule>every 1 hours from 08:00 to 16:00</schedule>
- Runs once every two hours, every day starting at 00:00:
<schedule>every 2 hours synchronized</schedule>
- Runs every 5 minutes from 10:00 to 14:00, every day:
- [TYPE]: Custom intervals can include the
every
prefix to define a repetitive interval, or you can define a specific list of days in a month:- To define a repetitive interval you can use the
every
prefix.Examples:
<schedule>every day 00:00</schedule> <schedule>every monday 09:00</schedule>
- To define specific days, you must use ordinal numbers. Valid
values are from the 1st day of a month, through to the maximum
number of days in that month, for example:
1st
orfirst
2nd
orsecond
3rd
orthird
- And up to:
31st
orthirtyfirst
Example:
<schedule>1st,3rd tuesday</schedule> <schedule>2nd,third wednesday of month 09:00</schedule>
- To define a repetitive interval you can use the
- [INTERVAL_VALUE]: Custom intervals include a list of the
specific days that you want the job to run. The list must
be defined in a comma-separated list and can include either of the
following values:
- The integer value of the day in the month through to a maximum
of 31 days, for example:
1
2
3
- And up to:
31
- The name of the day in a mix of any of the following long or
abbreviated values:
monday
ormon
tuesday
ortue
wednesday
orwed
thursday
orthu
friday
orfri
saturday
orsat
sunday
orsun
- Use
day
to specify all days of the week.
Examples:
<schedule>2nd monday,thu</schedule> <schedule>1,8,15,22 of month 09:00</schedule> <schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>
- The integer value of the day in the month through to a maximum
of 31 days, for example:
- [INTERVAL_SCOPE]: Specifies a clause that corresponds with the
specified [INTERVAL_VALUE]. Custom intervals can include the
of [MONTH]
clause, which specifies a single month in a year, or a comma-separated list of multiple months. You must also define a specific time for when you want the job to run, for example:of [MONTH] [HH:MM]
.By default, if the
of
clause is excluded, the custom interval is run every month.- [MONTH]: You must specify the months in a comma-separated list
and can include a mix of the following long or abbreviated values:
january
orjan
february
orfeb
march
ormar
april
orapr
may
june
orjun
july
orjul
august
oraug
september
orsep
october
oroct
november
ornov
december
ordec
- Use
month
to specify all months in the year.
- [HH:MM]: You must specify the time values in the 24 hour format,
HH:MM
, where:HH
are integers from00
to23
.MM
are integers from00
to59
.
Example:
<schedule>1st monday of sep,oct,nov 09:00</schedule> <schedule>1 of jan,april,july,oct 00:00</schedule>
- [MONTH]: You must specify the months in a comma-separated list
and can include a mix of the following long or abbreviated values:
- Custom interval examples
- Use the following examples to help you understand how to define job
schedules that use a custom interval:
- Runs every day at 00:00:
<schedule>every day 00:00</schedule>
- Runs every Monday at 09:00:
<schedule>every monday 09:00</schedule>
- Runs one time on the second Wednesday in March at 17:00:
<schedule>2nd wednesday of march 17:00</schedule>
- Runs six times in May. During the first two weeks, it runs one
time on each Monday, Wednesday, and Friday at 10:00:
<schedule>1st,second mon,wed,fri of may 10:00</schedule>
- Runs once a week. Every seven days starting of the first day of
every month, it runs once at 09:00:
<schedule>1,8,15,22 of month 09:00</schedule>
- Runs every other week. On the first and third Monday every month,
it runs one time at 04:00:
<schedule>1st,third monday of month 04:00</schedule>
- Runs three times each year. On the first Monday of September,
October, and November, it runs one time at 09:00:
<schedule>1st monday of sep,oct,nov 09:00</schedule>
- Runs one time each quarter. On the first day of January, April,
July, and October, it runs one time at 00:00:
<schedule>1 of jan,april,july,oct 00:00</schedule>
- Runs every day at 00:00:
Cron retries
If a cron job's request handler returns a status code that is not in the range
200–299 (inclusive) App Engine considers the job to have failed. By default,
failed jobs are not retried. You can cause failed jobs to be retried by
including a
block in your configuration file.<retry-parameters>
cron.xml
file that contains a single cron job configured to
retry up to five times (the default) with a starting backoff of 2.5 seconds that
doubles each time.
<cronentries>
<cron>
<url>/retry</url>
<description>Retry on jsdk</description>
<schedule>every 10 minutes</schedule>
<retry-parameters>
<min-backoff-seconds>2.5</min-backoff-seconds>
<max-doublings>5</max-doublings>
</retry-parameters>
</cron>
</cronentries>
Cron retries syntax
The retry parameters are described in the table below.
Element | Description |
---|---|
<job-retry-limit> |
The maximum number of retry attempts for a failed cron job not to exceed
5. If specified with , App Engine retries
the cron job until both limits are reached. When omitted from the
parameters, the limit is set to 5 by default.
|
<job-age-limit> |
The time limit for retrying a failed cron job, measured from when the
cron job was first run. The value is a number followed by a unit of
time, where the unit is s for seconds, m for
minutes, h for hours, or d
for days. For example, the value 5d specifies a limit of
five days after
the cron job's first execution attempt. If specified with
<job-retry-limit> , App Engine retries the cron job until both limits are
reached.
|
<min-backoff-seconds> |
The minimum number of seconds to wait before retrying a cron job after it fails. |
<max-backoff-seconds> |
The maximum number of seconds to wait before retrying a cron job after it fails. |
<max-doublings> |
The maximum number of times that the interval between failed cron job
retries will be doubled before the increase becomes constant. The
constant is:
2**(max_doublings - 1) * min_backoff .
|
Cron requests
Request headers
Requests from the Cron Service will contain a HTTP header:
X-Appengine-Cron: true
The X-Appengine-Cron
header is set internally by Google App Engine. If your
request handler finds this header it can trust that the request is a cron
request. If the header is present in an external user request to your app, it is
stripped. The exception being requests from logged in administrators of the
application, who are allowed to set the header for testing purposes.
Originating IP address
Google App Engine issues Cron requests from the IP address 0.1.0.1.
Deadlines
The cron timeout deadline depends on the instance class and scaling type that is configured for your app:
- Automatic scaling
- Timeout is about 10 minutes.
- Basic scaling and manual scaling
- Timeout can be up to 24 hours.
For more information, see Scaling types and instance classes
Limits
Free applications can have up to 20 scheduled tasks. Paid applications can have up to 250 scheduled tasks.
Cron support in the development server
The development server doesn't automatically run your cron jobs. You can use your local desktop's cron or scheduled tasks interface to trigger the URLs of your jobs with curl or a similar tool.
Deploying cron jobs
You can use the appcfg.sh
tool to deploy your cron jobs to App Engine.
- Option 1: Upload your whole application
To upload your whole application, which also updates the Cron Service with the entries from your
cron.xml
file, run the following command:./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
- Option 2: Upload only your cron updates
To update just the cron configuration without uploading the rest of the application, run the following command:
./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]
Deleting all cron jobs
To delete all cron jobs:
Edit the contents of the
cron.xml
file to:<?xml version="1.0" encoding="UTF-8"?> <cronentries/>
Deploy the
cron.xml
file to App Engine.
Cron support in the Cloud Console
The Cloud Console Task queues page has a tab that shows the tasks that are running cron jobs.
You can also visit the Logs page to see when cron jobs were added or removed.