Quickstart Guide

Get your first monitor running in 5 minutes

5-Minute Setup

This guide will walk you through creating your first monitor and sending a test check-in.

Step 1: Create an Account

Visit telemetry.host and sign up using either:

  • Email: Receive a verification link to activate your account
  • Google SSO: Instant account creation with your Google account

Upon signup, a default project is automatically created for you with a unique ping key.

Step 2: Create Your First Monitor

  1. Log in to your dashboard
  2. Click “Add Monitor”
  3. Fill in the details:
    • Name: “Daily Backup”
    • Description: “Monitors nightly database backup”
    • Mode: Timeout (recommended)
    • Timeout: 1d (24 hours)
  4. Click “Create Monitor”
  5. Copy your unique ping URL

Option B: Auto-Provisioning (For Infrastructure as Code)

You can also create monitors automatically by including all configuration in the URL:

https://telemetry.host/ping/{PROJECT_KEY}/timeout/1d1h/daily-backup?create=1

The monitor will be created on first check-in. See Monitor Modes for more details.

Step 3: Send a Test Check-In

Once you have your monitor created, send a test check-in:

The ping endpoint accepts simple POSTs, JSON payloads, and plain text output from scripts or commands. If you enable Data Visualization & Alerts, you can send your output and let AI find what matters: values to chart, trends to track, and alerts to set.

Simple Success Check-In

curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID}

With Status and Message

curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} \
  -H "Content-Type: application/json" \
  -d '{
    "status": "success",
    "message": "Backup completed successfully",
    "duration": 120
  }'

With Metrics (CPU, Memory, Custom Values)

Track numeric metrics alongside your check-ins. Metrics are displayed in an interactive timeline chart on the dashboard.

curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} \
  -H "Content-Type: application/json" \
  -d '{
    "status": "success",
    "message": "Health check passed",
    "metrics": {
      "cpu_load": 45.2,
      "memory_mb": 1024,
      "disk_free_percent": 78.5,
      "active_connections": 150
    }
  }'

Plain Text (Pipe Command Output)

echo "Backup completed: 2.5GB in 2 minutes" | \
  curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} \
  -H "Content-Type: text/plain" \
  --data-binary @-

Reliable Curl Delivery

For production jobs, add retry and timeout options so temporary network failures do not drop a check-in:

/path/to/script.sh 2>&1 | curl -X POST \
  --fail-with-body \
  --retry 25 \
  --retry-all-errors \
  --retry-connrefused \
  --retry-delay 7 \
  --retry-max-time 180 \
  --connect-timeout 5 \
  --max-time 20 \
  https://telemetry.host/ping/{YOUR_MONITOR_ID} \
  -H "Content-Type: text/plain" \
  --data-binary @-

Step 4: View Results

Return to your dashboard to see:

  • ✅ Monitor status (UP/DOWN)
  • Last check-in time
  • Success rate
  • Recent activity log

Step 5: Add to Your Cron Job

Now integrate the monitoring into your actual cron job:

# Edit your crontab
crontab -e

# Add monitoring to your backup script
0 2 * * * /path/to/backup.sh && curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} -d '{"status":"success"}' || curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} -d '{"status":"error"}'

Or wrap your entire script:

#!/bin/bash
# backup-monitored.sh

# Start monitoring
curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID}/start

# Run your backup
if /path/to/backup.sh 2>&1 | tee /tmp/backup.log; then
  # Success
  curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} \
    -H "Content-Type: text/plain" \
    --data-binary @/tmp/backup.log
else
  # Failure
  curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} \
    -H "Content-Type: text/plain" \
    -d "status: error" \
    --data-binary @/tmp/backup.log
fi

Step 6: Set Up Notifications

Configure where you want to receive alerts:

  1. Go to your monitor settings
  2. Click “Notifications”
  3. Add notification channels:
    • Email: Already configured by default
    • Discord: Add a webhook URL
    • Slack: Add a webhook URL
    • Other: Use Apprise format for 50+ services

Step 7: Test a Failure

Simulate a missed check-in to verify notifications work:

  1. Wait for your timeout period to expire (or temporarily reduce it)
  2. Check your email/Discord for an alert
  3. Send a check-in to clear the alert

Common Integration Patterns

Database Backup

0 2 * * * /usr/local/bin/backup-database.sh 2>&1 | curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} -H "Content-Type: text/plain" --data-binary @-

Docker Container Health

#!/bin/bash
# healthcheck.sh
if docker ps | grep -q "my-container"; then
  curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} -d '{"status":"success"}'
else
  curl -X POST https://telemetry.host/ping/{YOUR_MONITOR_ID} -d '{"status":"error","message":"Container not running"}'
fi

Python Script

import requests
import sys

def monitor_check_in(status, message=""):
    url = "https://telemetry.host/ping/{YOUR_MONITOR_ID}"
    data = {"status": status, "message": message}
    try:
        requests.post(url, json=data)
    except Exception as e:
        print(f"Failed to send check-in: {e}", file=sys.stderr)

try:
    # Your code here
    result = do_important_task()
    monitor_check_in("success", f"Processed {result} items")
except Exception as e:
    monitor_check_in("error", str(e))
    raise

Next Steps

Troubleshooting

Monitor Not Showing Check-Ins

  • Verify the monitor ID is correct
  • Check that curl command returns 200 OK
  • Ensure your server has internet access
  • Check firewall rules

Not Receiving Notifications

  • Verify notification channel is properly configured
  • Test notification from monitor settings
  • Check spam folder for emails
  • Verify webhook URLs are correct

Auto-Provisioning Not Working

  • Ensure ?create=1 parameter is included
  • Verify project key is correct (check in dashboard)
  • Check for error messages in the response

Getting Help