Core Concepts

Understanding monitors, check-ins, projects, and how Telemetry.host works

Overview

Telemetry.host is built around a few core concepts that make monitoring simple and flexible. Understanding these concepts will help you make the most of the platform.

Projects

A project is a container for organizing related monitors. Each project has:

  • A unique ping key (secret, ~11 characters)
  • A collection of monitors
  • Shared team access settings

When to Use Multiple Projects

  • Different environments: separate dev/staging/production
  • Different clients: if you manage infrastructure for multiple customers
  • Different teams: isolate monitors by department or team

Project Key Security

Your project ping key is secret and should be treated like a password:

  • Used in ping URLs for auto-provisioning
  • Required to create new monitors via URL
  • Can be regenerated if compromised

Monitors

A monitor tracks a specific task or process. Each monitor has:

  • A unique ID (short hashid)
  • A name and description
  • A monitoring mode (Timeout, Auto, or Frequency)
  • Notification settings
  • Check-in history

Monitor States

  • UP: Receiving check-ins as expected
  • DOWN: Missed expected check-in or received error status
  • LEARNING: Auto mode collecting check-in patterns
  • INACTIVE: Monitoring disabled

Check-Ins

A check-in is a report from your task to the monitor. Check-ins can include:

  • Status: success, error, warning (optional)
  • Message: Text description, command output, or full logs
  • Duration: Execution time in seconds
  • Metrics: Numeric metrics for timeline visualization (CPU, memory, custom values)
  • Metadata: Custom data (file sizes, counts, etc.)
  • Status code: HTTP-style codes (200, 500, etc.)

The ping endpoint can receive structured JSON or arbitrary text. With Data Visualization & Alerts, you can send script output, logs, or JSON and let AI infer useful charts and alert rules from recent check-ins.

Check-In Formats

JSON (Structured Data)

{
  "status": "success",
  "message": "Backup completed",
  "duration": 120,
  "metrics": {
    "cpu_load": 45.2,
    "memory_mb": 1024,
    "rows_processed": 50000
  }
}

With Metrics for Timeline Visualization

Send numeric metrics with your check-ins to track system health over time. Metrics are displayed in interactive synchronized charts on the monitor detail page.

{
  "status": "success",
  "metrics": {
    "cpu_percent": 65.5,
    "memory_used_mb": 2048,
    "disk_free_gb": 150,
    "active_connections": 42,
    "queue_size": 0
  }
}

Supported metric values: integers and floating-point numbers. Metric names can be any string (use underscores for readability).

Plain Text (Log Output)

[2025-01-15 02:30:00] Starting backup
[2025-01-15 02:32:45] Backup completed
Total size: 2.5GB
Tables: 15

Plain text is ideal for piping command output directly to monitoring endpoints.

AI-Assisted Data Visualization & Alerts

Data Visualization & Alerts can inspect recent check-ins, generate a DATA PREP extraction pipeline, render an ECharts visualization, and suggest alert rules from the data you already send.

You do not need to predefine every metric. Send your output and let AI find what matters: values to chart, trends to track, and alerts to set.

Monitor Modes

Telemetry.host supports three monitoring modes to accommodate different use cases.

How it works: Alert if no check-in received within the specified timeout period.

When to use:

  • Predictable schedules (daily, hourly, etc.)
  • Simple timeout-based monitoring
  • Most cron jobs

URL pattern: /ping/{PROJECT_KEY}/timeout/{TIMEOUT}/{ MONITOR_SLUG}

Example: Check in at least once per day

# Create monitor that expects check-in within 24 hours
curl -X POST \
  https://telemetry.host/ping/abc123/timeout/1d/daily-backup?create=1 \
  -d '{"status":"success"}'

Timeout format:

  • 30m - 30 minutes
  • 1h - 1 hour
  • 1d - 1 day
  • 1d6h - 1 day + 6 hours
  • 2w - 2 weeks

Auto Mode (Adaptive)

How it works: Learns check-in patterns from history and adapts automatically.

When to use:

  • Variable but predictable intervals
  • Processes that adapt based on load
  • Unknown exact schedule

URL pattern: /ping/{PROJECT_KEY}/auto/{MONITOR_SLUG}

Example: Monitor learns your check-in pattern

curl -X POST \
  https://telemetry.host/ping/abc123/auto/adaptive-task?create=1 \
  -d '{"status":"success"}'

How it learns:

  1. Learning phase (first 2-4 check-ins): Collects patterns
  2. Active monitoring (5+ check-ins): Uses median interval + deviation
  3. Continuous adaptation: Updates based on recent check-ins

Frequency Mode (Legacy)

How it works: Traditional “expected frequency + grace period” model.

When to use:

  • Migrating from healthchecks.io
  • Need explicit grace period control
  • Backward compatibility

URL pattern: /ping/{PROJECT_KEY}/{FREQUENCY}/{GRACE}/{MONITOR_SLUG}

Example: Expect check-in every 24 hours with 30 min grace

curl -X POST \
  https://telemetry.host/ping/abc123/24h/30m/legacy-job?create=1 \
  -d '{"status":"success"}'

Deadlines and Grace Periods

Timeout Mode

  • Deadline: Current time + timeout interval
  • Alert: Triggered when deadline expires without check-in
  • Reset: Each check-in resets the deadline

Auto Mode

  • Deadline: Calculated from learned median interval + variance
  • Grace period: Automatically adjusted based on pattern stability
  • Adaptation: Updates as patterns change

Frequency Mode

  • Deadline: Current time + frequency + grace period
  • Grace period: Explicit additional time buffer
  • Alert: Triggered when deadline expires

Notifications

Notifications are sent when:

  • A monitor transitions from UP to DOWN
  • A check-in reports an error status
  • A monitor recovers (DOWN to UP)

Notification Channels

Telemetry.host supports 50+ channels via Apprise:

  • Email (built-in)
  • Discord
  • Slack
  • Telegram
  • Microsoft Teams
  • PagerDuty
  • And many more…

Notification Settings

Configure per monitor:

  • Which channels to use
  • When to send (failures only, recoveries, etc.)
  • Notification message templates

Auto-Provisioning

Auto-provisioning allows you to create monitors through the ping URL itself, without using the dashboard.

Benefits

  • Infrastructure as Code: Define monitors in your scripts
  • Self-service: Services can create their own monitors
  • Dynamic scaling: Automatically create monitors for new instances

Example

# This URL will:
# 1. Create a monitor named "daily-backup" if it doesn't exist
# 2. Set timeout mode with 1 day timeout
# 3. Record the check-in

curl -X POST \
  "https://telemetry.host/ping/abc123/timeout/1d/daily-backup?create=1" \
  -d '{"status":"success"}'

URL Components

  • abc123: Your project ping key
  • timeout: Monitor mode
  • 1d: Timeout period (1 day)
  • daily-backup: Monitor slug (URL-friendly name)
  • ?create=1: Enable auto-creation

Teams and Collaboration

Roles

  • Admin: Full access, can manage team and monitors
  • Editor: Can create/edit monitors and view all data
  • Viewer: Read-only access to monitors and history

Shared Access

  • All team members see the same monitors
  • Activity is tracked per user
  • Notifications can be user-specific or team-wide

Security

Authentication

  • JWT-based session management
  • Secure password hashing (pbkdf2)
  • Google OAuth 2.0 support
  • Email verification required

Monitor Access

  • Monitors use unique, unguessable IDs
  • No authentication required for ping endpoints
  • URLs themselves are the security mechanism

Best Practices

  • Keep project ping keys secret
  • Use environment variables for keys in scripts
  • Regenerate keys if exposed
  • Use separate projects for different security zones

Data Retention

  • Free tier: 7 days of check-in history
  • Professional: 90 days of check-in history
  • Enterprise: 1 year of check-in history

Rate Limits

  • Check-ins: 1 per second per monitor
  • Dashboard API: 100 requests per minute
  • Monitor creation: 10 per minute

Exceeded limits return HTTP 429 (Too Many Requests).

Next Steps

Now that you understand the core concepts: