Guide: Heartbeat Monitoring

Heartbeat Monitors are designed to track any process, script, or service that can make an outbound HTTP request. They work like a dead man’s switch: your job sends a regular “pulse” to 9n9s to signal that it’s alive and well. If 9n9s doesn’t receive a pulse within a configured time, it will alert you.

Start with the Dashboard: Create and configure your heartbeat monitors through the web interface first. This guide covers both dashboard setup and advanced technical implementation. For API-only configuration, see our API Reference or SDK documentation.

This guide covers advanced features of Heartbeat Monitoring. For a basic introduction, see the Getting Started guide.

Common Use Cases

Heartbeat Monitors are incredibly versatile. You can use them for:

• Scheduled Tasks: System cron jobs, Windows Scheduled Tasks, Kubernetes CronJobs.
• Serverless Functions: AWS Lambda, Google Cloud Functions, Azure Functions.
• Data Pipelines: ETL/Data processing jobs, backup scripts, batch processes.
• Message Queue Consumers: Background workers processing jobs from queues like RabbitMQ or SQS.
• Deployment Processes: CI/CD pipeline steps.

Advanced Pulsing Techniques

While a simple GET request is enough to signal success, you can provide much more context with your pulses.

Signaling Job Start and Runtimes

You can track the execution time of your jobs by signaling when they start. To do this, send a request to the /start endpoint before your job’s main logic begins.

• GET /{uuid}/start: Signals the job has started. This resets the timer and sets the monitor status to “Started”.
• GET /{uuid}: Signals the job completed successfully. 9n9s will calculate the runtime.

You can configure your monitor to alert you if a job runs too long or finishes too quickly, which can be an indicator of problems.

#!/bin/bash

HEARTBEAT_UUID="your-unique-heartbeat-uuid"

# Signal the start of the job
curl -fsS "https://pulse.9n9s.com/${HEARTBEAT_UUID}/start"

# Your job's logic here
echo "Doing important work..."
sleep 10

# Signal successful completion
curl -fsS "https://pulse.9n9s.com/${HEARTBEAT_UUID}"

Capturing Logs and Output

When a job fails, you often need logs or error messages to diagnose the problem. You can send a POST request with a request body (up to 1MB) to capture this data. This works for success, failure, and start pulses.

#!/bin/bash

HEARTBEAT_UUID="your-unique-heartbeat-uuid"

# ... (error handling trap) ...

function run_job() {
    echo "Starting the job."
    # This command might produce a lot of output
    output=$(some_long_running_command)
    echo "Job finished."
    # Send the output to 9n9s on success
    curl -fsS -X POST -d "$output" "https://pulse.9n9s.com/${HEARTBEAT_UUID}"
}

function handle_error() {
  ERROR_MESSAGE="Job failed at line $1."
  # Send the error message to 9n9s on failure
  curl -fsS -X POST -d "$ERROR_MESSAGE" "https://pulse.9n9s.com/${HEARTBEAT_UUID}/fail"
  exit 1
}

trap 'handle_error $LINENO' ERR

run_job

The captured output will be visible in the pulse history in the 9n9s web UI, making debugging much easier.

Signaling with Exit Codes

For shell scripts, it’s common to use exit codes to signal success (0) or failure (non-zero). You can append the exit code to the pulse URL.

• /{uuid}/0: Signals success.
• /{uuid}/1: Signals failure.

This is especially useful with the 9n9s-cli wrapper.

#!/bin/bash
# A script that might fail
do_something_risky
# The exit code of the last command is captured in $?

# Pulse with the exit code
/usr/local/bin/9n9s-cli heartbeat pulse your-uuid --exit-code $?

This makes integrating 9n9s into existing shell scripts trivial.