Advanced usage of our cron job monitoring

We aim to keep our cron job monitoring as simple to use as possible, but that doesn't mean we don't support some more advanced usage cases.

Bypassing CDNs or caching layers #

Our default usage suggests using a GET method to ping your cron URL, to let us know your cron job ran on time. In some cases, this may not work as intended because of proxies or middleware between your servers and our endpoint.

If you have a caching layer in between, subsequent GET calls may be returned by your proxy instead of our system, and we'd never see the pingback.

If that is the case, you can modify your code to perform a POST call to us, instead. This can be done as follows:

curl -X POST --retry 3 https://ping.ohdear.app/e536e771-9ff6

Note the addition of the -X POST parameter.

Any proxy or caching layer should always let POST calls be sent to our endpoint, these should never be cached.

Providing memory usage, script duration and exit codes #

Our Ping URL has support for providing the total memory consumption and the duration of your script, as optional parameters.

To send this data along, you can change the pingback URL to a POST call with a payload of memory, runtime, exit_code or failure_message formatted as a plain form submission.

That sounds complex, so here's an example implemented in curl:

$ curl -X POST https://ping.ohdear.app/e536e771-9ff6 \
    -F 'memory=29360128' \
    -F 'runtime=0.25' \
    -F 'exit_code=0' \
    -F 'failure_message="Oh Dear, something went wrong"'

You provide the form fields using the -F option parameter to curl.

The data should be provided as:

  • memory: numeric, the total memory consumption of your cron job, measured in bytes (in the example above, the script used 28MB of memory)
  • runtime: numeric, the total duration of your cron job, measured in seconds (in this example: 0.25 seconds)
  • exit_code: numeric, the exit code of your script. A value of 0 means your script executed successfully.
  • failure_message: string, a text-version (human readable) for why the script has failed. This can be your debug information. Max 255 characters.

You can choose to pass along just one of these items or all of them at once:

$ curl -X POST https://ping.ohdear.app/e536e771-9ff6 \
    -F 'memory=29360128' \
    -F 'runtime=0.25'

Every payload field is entirely optional.

Providing active callbacks for failure states #

Our default method of operating is to send you a notification when we have not received a pingback to your unique URL on time.

There are 2 ways you can provide an active callback to us that report the cron job has failed.

This has the benefit that we don't have to wait for the frequency or grace time to expire, we can fire notifications directly when we receive a failure confirmation from your scripts.

Reporting failure via a simple GET call #

Every ping URL you see in your Oh Dear account can have the /failed path appended to it.

If that URL receives a ping, we consider it a confirmation from your end that your script has failed and we'll send out the alert to your notification channels.

Take this as an example:

curl https://ping.ohdear.app/e536e771-9ff6/failed

By adding the /failed path to the end of the ping URL, you can confirm us that this particular cron job has failed.

You can also optionally make this a POST call with the same meta data as runtime, memory and failure_message.

$ curl -X POST https://ping.ohdear.app/e536e771-9ff6/failed \
    -F 'memory=29360128' \
    -F 'runtime=0.25' \
    -F 'exit_code=3' \
    -F 'failure_message="Oh Dear, something went wrong"'

These extra parameters are entirely optional.

Reporting failure with details through a POST call #

You can also perform a POST call to your endpoint with a non-zero exit_code to let us know your script has failed.

This way, you can do a pingback to us and use the exit-code in your script to let us know the state of your cron jobs. Additionally, you can provide memory and runtime information as well (see above).

To do so, implement the following API call to your pingback URL.

$ curl -X POST https://ping.ohdear.app/e536e771-9ff6 \
    -F 'exit_code=1'

The exit_code parameter should be an integer (numeric) value. A value of 0 means the script exited correctly, and we interpret that as a success state.

Any non-zero value submitted back to us will be interpreted as a failed job, and will lead to notifications being sent.

Was this page helpful to you? Feel free to reach out via support@ohdear.app or on Twitter via @OhDearApp if you have any other questions. We'd love to help!