Jenkins + Sandglass: Heartbeat Monitoring for Jenkins Jobs

Q: Does this work with Jenkins Pipeline shared libraries?

Yes. You can wrap the heartbeat curl in a shared library step and call it from any pipeline. This is a clean way to enforce heartbeat monitoring across all scheduled jobs in your organization without duplicating the curl command in every Jenkinsfile.

Q: What if the Jenkins agent does not have curl installed?

On Linux agents, curl is almost always available. If not, install it via the agent's package manager or use wget: "wget -q --spider \"$SANDGLASS_HEARTBEAT_URL\"". On Windows agents, use PowerShell's Invoke-WebRequest as described in the capabilities section.

Q: How do I handle parallel stages in a declarative pipeline?

Put the heartbeat step in a post { success { ... } } block at the pipeline level, not inside a stage. Pipeline-level post blocks run after all stages (including parallel ones) complete, so the heartbeat only fires when everything passes.

Q: Can I monitor multiple Jenkins jobs with one Sandglass account?

Yes. Create one heartbeat check per job. Each gets its own URL and interval. You can group related jobs under a single Sandglass group to share alert channels, or keep them in separate groups for independent notification routing.

Q: What interval should I set if my Jenkins job has variable runtime?

Base the interval on the schedule period, not the job duration. For a job that runs every 4 hours and takes up to 45 minutes, set the heartbeat interval to 4.5 or 5 hours. The heartbeat fires when the job completes, so the window just needs to be wider than the schedule period plus maximum runtime.

Jenkins jobs that silently stop running are a classic blind spot. Sandglass closes it.

Ping Sandglass from a Jenkins build so you know it ran on schedule. If the job stops executing, gets stuck in the queue, or fails before the ping step, Sandglass opens an incident.

Requirements

A Jenkins instance with at least one periodically triggered job (Build periodically or Pipeline cron)
The Jenkins agent or node running the job must have outbound HTTPS access to sandglass.it
curl available on the build agent (standard on Linux/macOS agents; use Invoke-WebRequest on Windows)
A Sandglass heartbeat check with its URL stored as a Jenkins credential or environment variable

How to connect

Step 1: Create a heartbeat check in Sandglass

Add a new Heartbeat check in Sandglass. Set the expected interval to match your Jenkins job schedule, adding a few minutes of buffer for queue wait time. Copy the heartbeat URL after saving.

Tip

Name the check after the Jenkins job so the Sandglass incident subject maps directly to the job that stopped running.

Step 2: Store the heartbeat URL in Jenkins credentials

In Jenkins, go to Manage Jenkins > Credentials and add a new "Secret text" credential. Paste the heartbeat URL as the secret and give it an ID like SANDGLASS_HEARTBEAT_URL. Reference it in your pipeline with the credentials() binding so it never appears in console output.

Step 3: Add the heartbeat step to your pipeline or freestyle job

For a declarative pipeline, add a post { success { ... } } block with: "sh 'curl -fsS -m 10 --retry 3 \"$SANDGLASS_HEARTBEAT_URL\"' ". For a freestyle job, add an "Execute shell" build step at the end of the build with the same curl command. The post success block only fires when all stages pass, which is the right default.

Tip

To report failures explicitly, add a post { failure { ... } } block that curls the /fail variant of the URL. This opens a Sandglass incident immediately on build failure rather than waiting for the heartbeat window to expire.

Step 4: Trigger a manual build and verify

Run the job manually from the Jenkins dashboard. Open the console output and confirm the curl step ran and printed a 200 response. In Sandglass, the heartbeat check should flip to "Up" within seconds. If it stays pending, check that the agent can reach sandglass.it on port 443.

What you can do

Catch jobs that stop running: Jenkins does not alert you when a periodically triggered job stops executing. Sandglass does. Queue backlogs, executor shortages, or accidentally disabled triggers all look the same to Sandglass: a missing heartbeat means an incident.
Works with declarative and scripted pipelines: The heartbeat curl fits naturally into declarative pipeline post blocks, scripted pipeline try/finally blocks, and freestyle "Execute shell" steps. No Jenkins plugin required.
Supports Windows agents: On Windows build agents without curl, use PowerShell: "Invoke-WebRequest -Uri $env:SANDGLASS_HEARTBEAT_URL -Method POST -UseBasicParsing". The heartbeat endpoint accepts both GET and POST.
Explicit failure signaling: The /fail suffix on the heartbeat URL lets you open a Sandglass incident the moment a build fails, not just when the next scheduled run is missed. Combine success and failure post blocks for full coverage.

Frequently Asked Questions

Does this work with Jenkins Pipeline shared libraries?

What if the Jenkins agent does not have curl installed?

How do I handle parallel stages in a declarative pipeline?

Can I monitor multiple Jenkins jobs with one Sandglass account?

What interval should I set if my Jenkins job has variable runtime?

Know when your Jenkins jobs stop running

Start free

Free plan, no credit card required.