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 BetterStack monitors
• Supports custom date ranges for calculations (defaults to past 12 full months if not specified)
• Defaults to status page monitors only (use --all-monitors to include all monitors)
• Search functionality to filter monitors by name (supports multiple search terms)
• Regional breakdown option to group monitors by geographic region
• Automatic PNG chart generation showing monthly regional uptime trends (defaults to chart.png)
• 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 calculates uptime for the past 12 full months (e.g., if today is 10/13/2025, it uses 09/30/2024 to 09/30/2025)
• By default, only monitors published on status pages are included (use --all-monitors to include all monitors)
• A PNG chart (chart.png) is automatically generated showing monthly regional uptime trends

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

   # Uses defaults: past 12 full months, status page monitors only, generates chart.png
   ./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 defaults: past 12 full months, status page monitors only, generates chart.png
   betterstack-report
   
   # Or specify custom date range
   betterstack-report --start-date MM/DD/YYYY --end-date MM/DD/YYYY

Examples:

# Default: status page monitors, past 12 full months, generates chart.png
betterstack-report

# Include all monitors (not just status page monitors)
betterstack-report --all-monitors

# Search for monitors containing specific text
betterstack-report --search "api"

# Show regional breakdown instead of individual monitors (still generates chart.png)
betterstack-report --by-region

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

# Custom date range with status page monitors (default)
betterstack-report --start-date 01/01/2024 --end-date 12/31/2024

# Custom date range with all monitors
betterstack-report --start-date 01/01/2024 --end-date 12/31/2024 --all-monitors

# Search for monitors with spaces in the search term
betterstack-report --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 all monitors flag
betterstack-report --all-monitors --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

# Specify custom PNG chart filename (default is chart.png)
betterstack-report --output-png regional_uptime.png

# Custom filename with date range
betterstack-report --start-date 01/01/2024 --end-date 12/31/2024 --output-png uptime_2024.png

# Custom filename with search filters
betterstack-report --search "premium" --output-png premium_regions.png

Date Ranges:

• If no dates are specified, defaults to the past 12 full months (e.g., if today is 10/13/2025, uses 09/30/2024 to 09/30/2025)
• 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:

• By default, only monitors published on status pages are included
• --all-monitors: Include all monitors, not just those published on status pages
• --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>: Specify PNG chart filename (default: chart.png). Chart is always generated showing monthly regional uptime trends
• --skip-no-downtime: When all monitors have 100% uptime, skip the detailed table and show only the summary statistics

During development, you can build and run:

# Build the project
cargo build --release

# Run with defaults: past 12 full months, status page monitors, generates chart.png
./target/release/betterstack-report

# Or with custom options
./target/release/betterstack-report --start-date MM/DD/YYYY --end-date MM/DD/YYYY
./target/release/betterstack-report --all-monitors
./target/release/betterstack-report --output-png my_chart.png

Output

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

PNG Chart Output (always generated):

• Automatically generates a visual line chart saved as chart.png (or custom filename via --output-png)
• Shows regional uptime trends over time with monthly buckets
• 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

Standard Format (default console output):

• 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
• Note: When using --by-region, only the PNG chart and regional summary are generated (no individual monitor table)

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

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. Default: 12 full months ago
--end-date	-e	End date in MM/DD/YYYY or MM-DD-YYYY format. Requires --start-date. Default: end of last full month
--all-monitors		Include all monitors (default is status page monitors only)
--search <term>		Filter monitors by name (case-insensitive). Can be used multiple times
--by-region		Show regional breakdown instead of individual monitor table (PNG chart still generated)
--output-png <filename>		Specify PNG chart filename. Default: chart.png
--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.