Monitor a Jenkins scheduled build

A Jenkins job on a timer fails in ways nobody sees. The build goes red in a folder nobody opens, an agent is offline so the build waits in the queue, or the controller restarts and the job is disabled. A heartbeat check catches all of these: the pipeline reports to Pingstack after it succeeds, and Pingstack alerts you when that report doesn’t arrive on time.

1. Create a heartbeat check that matches the trigger

Find the pipeline’s cron trigger:

triggers {
    cron('TZ=UTC\n0 2 * * *')
}

Jenkins often uses H in place of a fixed minute (H 2 * * *), which picks a consistent but unpredictable minute in that hour for each job. Pingstack needs a fixed time. Either replace H with a minute, or keep H, set the check to the start of the hour, and make the grace period at least an hour.

Create a heartbeat check with the matching expression. Jenkins uses the controller’s timezone unless the trigger starts with a TZ= line, as above. Choose the same timezone in Pingstack. See schedules and timezones.

Set a grace period that covers the build’s runtime and time waiting for an agent. Attach a notification group.

2. Store the ping URL as a credential

Copy the location’s ping URL from the check in Pingstack. In Jenkins, add a Secret text credential with the URL as its secret and an ID such as pingstack-nightly-export. Jenkins masks it in build logs.

3. Report in a success post action

pipeline {
    agent any
    triggers {
        cron('TZ=UTC\n0 2 * * *')
    }
    stages {
        stage('Export') {
            steps {
                sh './scripts/export.sh'
            }
        }
    }
    post {
        success {
            withCredentials([string(credentialsId: 'pingstack-nightly-export', variable: 'PINGSTACK_PING_URL')]) {
                sh 'curl --fail --silent --show-error --max-time 10 --retry 3 "$PINGSTACK_PING_URL" > /dev/null'
            }
        }
    }
}

The success post condition runs only when the whole build succeeded, so a failed build sends nothing and Pingstack alerts you when the deadline passes. Use single quotes around the sh command so Groovy doesn’t interpolate the secret into the command line.

4. Confirm the first report

Choose Build Now on the job. When the build succeeds, open the check in Pingstack and confirm the location received a heartbeat and shows a next deadline.

Optional: report a number

Read a count from an earlier step and add --get --data-urlencode "value=$COUNT" to the curl call to send it as a numeric value. Then set warning and critical thresholds on the check.

Why a healthy build might still alert

• H in the schedule. The build runs at a hashed minute in its hour. Keep the grace period at an hour or more, or use a fixed minute.
• Queued builds. A build waiting for an agent with the right label starts late. Check the queue and your agents.
• Disabled job. A disabled job never runs. Pingstack alerts, which is usually what you want.
• Unstable builds. An unstable build (for example, failing tests marked unstable) isn’t success, so it doesn’t report. Use post { always { ... } } only if unstable runs should count as healthy.

If alerts still don’t match what you expect, see troubleshooting monitoring.