Skip to content

Owloops/updo

BranchesTags

Repository files navigation

🐤 Updo - Website Monitoring Tool

Updo demo

Updo is a command-line tool for monitoring website uptime and performance. It provides real-time metrics on website status, response time, SSL certificate expiry, and more, with alert notifications.

License:MIT Latest Release Go Report Card

Features

  • Real-time monitoring with uptime percentage, response times, and SSL certificate tracking
  • Multi-target monitoring - Monitor multiple URLs concurrently from the command line or config files
  • Multi-region AWS Lambda - Deploy across 13 global regions for worldwide monitoring coverage
  • Prometheus & Grafana integration - Export metrics for visualization and long-term storage
  • Alert notifications - Desktop notifications and webhook integration (Slack, Discord, custom endpoints)
  • Flexible HTTP support - Custom headers, POST/PUT requests, SSL verification options, response assertions
  • Multiple output modes - Interactive TUI, simple text output, or structured JSON logging

Demo

Basic Monitoring

updo-basic-monitoring.mp4

Multi-Region Monitoring

updo-multi-region-grafana.mp4

Installation

macOS - Homebrew (Recommended) 
brew tap owloops/tap
brew install updo
Linux - Package Managers (Recommended)

Debian/Ubuntu:

# Replace VERSION with actual version (e.g., 0.3.7)
curl -L -O https://github.com/Owloops/updo/releases/latest/download/updo_VERSION_linux_amd64.deb
sudo dpkg -i updo_VERSION_linux_amd64.deb

Red Hat/Fedora/CentOS:

# Replace VERSION with actual version (e.g., 0.3.7)
curl -L -O https://github.com/Owloops/updo/releases/latest/download/updo_VERSION_linux_amd64.rpm
sudo rpm -i updo_VERSION_linux_amd64.rpm

Alpine Linux:

# Replace VERSION with actual version (e.g., 0.3.7)
curl -L -O https://github.com/Owloops/updo/releases/latest/download/updo_VERSION_linux_amd64.apk
sudo apk add --allow-untrusted updo_VERSION_linux_amd64.apk

Arch Linux:

# Replace VERSION with actual version (e.g., 0.3.7)
curl -L -O https://github.com/Owloops/updo/releases/latest/download/updo_VERSION_linux_amd64.pkg.tar.zst
sudo pacman -U updo_VERSION_linux_amd64.pkg.tar.zst

openSUSE:

# Replace VERSION with actual version (e.g., 0.3.7)
curl -L -O https://github.com/Owloops/updo/releases/latest/download/updo_VERSION_linux_amd64.rpm
sudo zypper install --allow-unsigned-rpm updo_VERSION_linux_amd64.rpm
Windows - Direct Download

PowerShell:

# Download and install updo
Invoke-WebRequest -Uri "https://github.com/Owloops/updo/releases/latest/download/updo_Windows_amd64.exe" -OutFile "updo.exe"
# Move to a directory in your PATH (or create a custom directory)
Move-Item updo.exe C:\Windows\System32\updo.exe

Manual Download: Download the Windows executable from the latest release and add it to your PATH.

Quick install script (Linux, macOS, Windows/MSYS) 
curl -sSL https://raw.githubusercontent.com/Owloops/updo/main/install.sh | bash
Build from source

Requires Go installed.

git clone https://github.com/Owloops/updo.git
cd updo
go build

Or install directly:

go install github.com/Owloops/updo@latest
Docker 
# Build and run
docker build -t updo https://github.com/Owloops/updo.git
docker run updo monitor <website-url> [options]

Usage

# Monitor URLs
./updo monitor <website-url> [options]
./updo monitor <url1> <url2> <url3>

# Using configuration file
./updo monitor --config <config-file>

# Generate shell completions
./updo completion bash > updo_completion.bash

Options

Basic:

  • --url, --config: Target URL or TOML config file
  • --refresh: Check interval in seconds (default: 5)
  • --timeout: Request timeout in seconds (default: 10)
  • --count: Number of checks (0 = infinite)
  • --simple: Text output instead of TUI

HTTP:

  • --header: Custom HTTP headers (repeatable)
  • --request: HTTP method (default: GET)
  • --data: Request body data
  • --skip-ssl, --follow-redirects, --accept-redirects: SSL and redirect options
  • --assert-text: Expected response text

Multi-region:

  • --regions: AWS regions (comma-separated or 'all')
  • --profile: AWS profile for remote executors

Output & Alerts:

  • --log: JSON structured logging
  • --webhook-url, --webhook-header: Webhook notifications
  • --only, --skip: Target filtering

Note: When using CLI flags, all settings (headers, webhook URL, timeouts, etc.) apply globally to all monitored targets. For per-target configuration, use a TOML configuration file.

Examples

# Basic monitoring
./updo monitor https://example.com

# Set custom refresh and timeout
./updo monitor --refresh 10 --timeout 5 https://example.com

# Simple mode and logging
./updo monitor --simple --count 10 https://example.com
./updo monitor --log --count 10 https://example.com > output.json

# Custom requests
./updo monitor --header "Authorization: Bearer token" --assert-text "Welcome" https://example.com
./updo monitor --request POST --header "Content-Type: application/json" --data '{"test":"data"}' https://api.example.com

# Multi-target monitoring
./updo monitor https://google.com https://github.com https://cloudflare.com
./updo monitor --config example-config.toml --only Google,GitHub

# Multi-region monitoring
./updo monitor --regions us-east-1,eu-west-1 https://example.com
./updo monitor --regions all --profile production https://example.com

# Webhook notifications
./updo monitor --webhook-url "https://hooks.slack.com/services/YOUR/WEBHOOK" https://example.com

Configuration File

Use TOML configuration for complex monitoring setups with multiple targets.

Example Configuration

[global]
refresh_interval = 5
timeout = 10
webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK"
only = ["Google", "API"]  # Monitor only these targets

[[targets]]
url = "https://www.google.com"
name = "Google"
refresh_interval = 3
assert_text = "Google"

[[targets]]
url = "https://api.example.com/health"
name = "API"
method = "POST"
headers = ["Authorization: Bearer token"]

Configuration Options

Global settings (apply to all targets unless overridden):

  • refresh_interval, timeout, follow_redirects, accept_redirects, receive_alert, count
  • webhook_url, webhook_headers: Default webhook settings
  • only, skip: Target filtering arrays
  • regions: AWS regions for remote executors

Target settings (can override global):

  • url (required), name: Target identification
  • method, headers, body: HTTP request options
  • assert_text, should_fail: Response validation
  • skip_ssl, follow_redirects, accept_redirects: Connection options
  • webhook_url, webhook_headers: Per-target notifications
  • regions: Target-specific AWS regions

Multi-Region Monitoring

Deploy remote executors as AWS Lambda functions across 13 global regions for distributed monitoring from multiple geographic locations.

# Deploy remote executors to AWS regions
updo aws deploy --regions us-east-1,eu-west-1

# Monitor using remote executors
updo monitor --regions us-east-1,eu-west-1 https://example.com

# Cleanup when done
updo aws destroy --regions all

Prerequisites

AWS CLI configured with appropriate credentials and the following permissions:

Service Required Permissions
Lambda CreateFunction, UpdateFunctionCode, DeleteFunction, GetFunction, InvokeFunction
IAM CreateRole, AttachRolePolicy, DetachRolePolicy, DeleteRole, GetRole
STS GetCallerIdentity

Supported regions: us-east-1, us-west-1, us-west-2, eu-west-1, eu-central-1, eu-west-2, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2, ap-south-1, sa-east-1, ca-central-1

Troubleshooting: If you get credential errors, run aws sso login --profile your-profile to refresh expired sessions.

Webhook Notifications

Updo can send webhook notifications when targets go up or down. This enables integration with various services like Slack, Discord, PagerDuty, or custom alerting systems.

Webhook Payload

When a target status changes, Updo sends a JSON payload:

{
  "event": "target_down",  // or "target_up"
  "target": "Critical API",
  "url": "https://api.example.com",
  "timestamp": "2024-01-01T12:00:00Z",
  "response_time_ms": 1500,
  "status_code": 500,
  "error": "Internal Server Error"  // only for down events
}

Integration Examples

Slack Webhook:

[[targets]]
url = "https://api.example.com"
name = "Production API"
webhook_url = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

Custom Webhook with Headers:

[[targets]]
url = "https://critical-service.example.com"
name = "Critical Service"
webhook_url = "https://alerts.internal.com/webhook"
webhook_headers = [
  "Authorization: Bearer YOUR_TOKEN",
  "X-Service: updo-monitor"
]

Prometheus & Grafana Integration

Export updo metrics to Prometheus for long-term storage, visualization, and alerting:

# Basic Prometheus integration
./updo monitor --prometheus-url http://localhost:9090/api/v1/write https://example.com

# Via environment variables (CLI flag optional if URL provided via env)
export UPDO_PROMETHEUS_RW_SERVER_URL="https://prometheus.example.com/api/v1/write"
export UPDO_PROMETHEUS_USERNAME="admin"
export UPDO_PROMETHEUS_PASSWORD="secret"
./updo monitor https://example.com

Available metrics:

  • Target uptime and response times
  • HTTP status codes and timing breakdown (DNS, TCP, TTFB, download)
  • SSL certificate expiry and assertion results

Quick start with Docker:

# Clone and start the monitoring stack
git clone https://github.com/Owloops/updo.git
cd updo/examples/prometheus-grafana
docker compose up -d

Access Grafana at http://localhost:3000 for pre-built dashboards.

📖 Full Documentation: See examples/prometheus-grafana/README.md for complete setup, authentication options, metrics reference, and PromQL examples.

Structured Logging

The --log flag outputs JSON-formatted logs for programmatic consumption:

  • Check logs (stdout): HTTP requests, responses, and timing information
  • Metrics logs (stdout): Uptime, response time stats, success rate
  • Error logs (stderr): Failures, warnings, and assertion results

Usage examples:

# All logs to one file
./updo monitor --log https://example.com > all.json 2>&1

# Metrics to one file, errors to another
./updo monitor --log https://example.com > metrics.json 2> errors.json

# Processing with jq
./updo monitor --log https://example.com | jq 'select(.type=="check") | .response_time_ms'

Keyboard Shortcuts

When monitoring multiple targets:

  • ↑/↓: Navigate targets
  • Tab: Collapse/expand all target groups
  • Enter: Collapse/expand individual target group
  • /: Search mode, ESC to exit
  • l: Toggle logs per target
  • q or Ctrl+C: Quit

Mentions

Contributing

Contributions to Updo are welcome! Feel free to create issues or submit pull requests.

License

This project is licensed under the MIT License.

About

Uptime monitoring CLI tool with alerting and advanced settings

www.owloops.com/landings/open-source

Topics

cli monitoring termui

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

638 stars

Watchers

11 watching

Forks

29 forks
Report repository

Releases 39

v0.4.3 Latest
Aug 18, 2025
+ 38 releases

Contributors 3

Languages