BetterStack Uptime Calculator

Overview

The BetterStack Uptime Calculator is a Rust-based command-line tool designed to calculate and report uptime statistics for BetterStack monitors over a specified date range. This tool leverages asynchronous programming to efficiently process multiple monitors concurrently, providing fast and accurate uptime calculations.

Originally created by Ron McCorkle for Pingdom (mack42 on GitHub): https://github.com/ZerosAndOnesLLC/pingdom-report-tool

Modified for BetterStack by Mitch Lewandowski for SugarCRM (mitch-sugarcrm on GitHub)

Features

• Calculates uptime percentages and downtime minutes for all BetterStack monitors
• Supports custom date ranges for calculations (defaults to past 12 months if not specified)
• Optional filtering to only include monitors published on status pages
• Search functionality to filter monitors by name (supports multiple search terms)
• Regional breakdown option to group monitors by geographic region
• PNG chart generation to visualize regional uptime trends over time
• Option to skip detailed table when all monitors have 100% uptime
• Utilizes asynchronous programming for improved performance
• Processes multiple monitors concurrently (up to 10 at a time)
• Reads BetterStack API credentials from environment variables or a .env file
• Provides a user-friendly command-line interface with usage instructions

Prerequisites

• Rust programming language (latest stable version)
• BetterStack account with API access

Setup

1. Clone the repository:

   git clone https://github.com/mitch-sugarcrm/betterstack-report-tool.git
   cd betterstack-report-tool

2. Set up your BetterStack API credentials: You have two options:

   a. Create a .env file in the project root:

   BETTERSTACK_API_TOKEN=your_api_token_here
   BETTERSTACK_API_URL=https://uptime.betterstack.com/api/v2
   

   b. Set environment variables directly in your shell:

   export BETTERSTACK_API_TOKEN=your_api_token_here
   export BETTERSTACK_API_URL=https://uptime.betterstack.com/api/v2

   NOTE: You can create an API token in your BetterStack account settings under the API section.

3. Build the project:

   cargo build --release

Usage

After compiling, you can run the tool directly without using cargo run. The compiled binary will be in the target/release directory.

Default Behavior: If no dates are specified, the tool defaults to calculating uptime for the past year (365 days).

1. If you're in the project root, you can run:

   # Uses default date range (past year)
   ./target/release/betterstack-report
   
   # Or specify custom date range
   ./target/release/betterstack-report --start-date MM/DD/YYYY --end-date MM/DD/YYYY

2. Alternatively, you can move the binary to a directory in your PATH and run it from anywhere:

   # Uses default date range (past year) 
   betterstack-report
   
   # Or specify custom date range
   betterstack-report --start-date MM/DD/YYYY --end-date MM/DD/YYYY

Examples:

# Calculate uptime for all monitors (uses default: past year)
betterstack-report

# Calculate uptime only for monitors published on status pages (past year)
betterstack-report --status-page-only

# Search for monitors containing specific text (past year)
betterstack-report --search "api"

# Show regional breakdown instead of individual monitors
betterstack-report --by-region

# Skip detailed table when all monitors have perfect uptime (show only summary)
betterstack-report --skip-no-downtime

# Calculate uptime for all monitors with custom date range
betterstack-report --start-date 01/01/2024 --end-date 12/31/2024

# Calculate uptime only for monitors published on status pages with custom dates
betterstack-report --start-date 01/01/2024 --end-date 12/31/2024 --status-page-only

# Search for monitors with spaces in the search term
betterstack-report --start-date 01/01/2024 --end-date 12/31/2024 --search "premium us 02"

# Search for monitors matching any of multiple terms (OR operator)
betterstack-report --search "production" --search "staging" --search "dev"

# Combine search with status page filtering (uses default date range)
betterstack-report --status-page-only --search "api server" --search "web app"

# Regional breakdown with custom date range
betterstack-report --by-region --start-date 01/01/2024 --end-date 12/31/2024

# Regional breakdown for status page monitors only
betterstack-report --by-region --status-page-only

# Generate PNG chart showing monthly regional uptime trends (defaults to past 12 months)
betterstack-report --output-png regional_uptime.png

# Generate chart for custom date range
betterstack-report --start-date 01/01/2024 --end-date 12/31/2024 --output-png uptime_2024.png

# Generate chart with search filters
betterstack-report --search "premium" --output-png premium_regions.png

Date Ranges:

• If no dates are specified, defaults to the past 12 months from today (accurate month calculation)
• If not specified, start_date defaults to 12 months ago and end_date defaults to today
• You can override the defaults by specifying both --start-date and --end-date parameters
• Supported date formats: MM/DD/YYYY or MM-DD-YYYY (e.g., 01/15/2024 or 01-15-2024)

Filtering and Display Options:

• --status-page-only: Filter to only include monitors published on status pages (useful for customer-facing reports)
• --search <term>: Filter monitors by name (case-insensitive). Use multiple times to match any of the terms (OR operator)
• --by-region: Group monitors by geographic region instead of showing individual monitor details
• --output-png <filename>: Generate a PNG chart showing monthly regional uptime trends over time
• --skip-no-downtime: When all monitors have 100% uptime, skip the detailed table and show only the summary statistics

If you prefer to run it with cargo during development, you can still use:

# Uses default date range (past year)
cargo run

# Or with custom date range  
cargo run -- --start-date MM/DD/YYYY --end-date MM/DD/YYYY

Output

The tool provides different output formats depending on the options used:

Standard Format (default):

• Lists monitors with uptime percentage and downtime details
• Monitors with 100% uptime are shown first (alphabetically)
• Monitors with downtime are listed from best to worst uptime
• Includes detailed downtime periods with timestamps when available

Regional Breakdown (--by-region):

• Groups monitors by geographic region (US, UK, EU, APAC, Other)
• Shows average uptime and total downtime per region
• Lists individual monitors with downtime within each region
• Provides overall statistics across all regions

Summary Only (--skip-no-downtime):

• When all monitors have 100% uptime, shows only summary statistics
• Includes average uptime percentage and total monitor count
• Skips the detailed per-monitor table for cleaner output

PNG Chart Output (--output-png):

• Generates a visual line chart showing regional uptime trends over time
• Monthly buckets based on the specified date range (defaults to 12 months)
• Color-coded lines for each geographic region (US, UK, EU, APAC, Other)
• Auto-scaling Y-axis based on actual data values for optimal readability
• Includes legend with larger font sizes for clarity
• Chart dimensions: 1200x600 pixels

Notes

• The tool uses concurrent processing with a semaphore (up to 10 simultaneous requests) for optimal performance while respecting API limits
• Ensure your BetterStack API token has the necessary permissions to access monitor information and SLA data
• If you're using the .env file, make sure it's in the same directory as the binary when running the compiled version
• For debugging API issues, you can enable verbose logging with RUST_LOG=debug environment variable

Command Line Options

Option	Short	Description
--start-date	-s	Start date in MM/DD/YYYY or MM-DD-YYYY format. Requires --end-date
--end-date	-e	End date in MM/DD/YYYY or MM-DD-YYYY format. Requires --start-date
--status-page-only		Only include monitors published on status pages
--search <term>		Filter monitors by name (case-insensitive). Can be used multiple times
--by-region		Group monitors by geographic region instead of individual listing
--output-png <filename>		Generate PNG chart showing monthly regional uptime trends
--skip-no-downtime		Skip detailed table when all monitors have 100% uptime

Dependencies

• reqwest: HTTP client for making API requests
• serde and serde_json: For JSON serialization and deserialization
• chrono: For date and time handling
• tokio: Asynchronous runtime
• clap: For parsing command-line arguments
• dotenv: For loading environment variables from a .env file
• futures: For concurrent processing of API requests
• tracing: For structured logging
• url: For URL parsing and manipulation
• plotters: For generating PNG charts and visualizations

Contributing

Contributions to improve the BetterStack Uptime Calculator are welcome. Please feel free to submit issues or pull requests.

License

This project is licensed under the MIT License with an additional clause restricting resale.

MIT License

Copyright (c) [2025] SugarCRM, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or use copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

2. The Software, or any modifications or derivative works based on the Software, shall not be resold or redistributed for a fee without explicit permission from the copyright holder.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.