Blue Triangle CLI Reporter

A powerful Python CLI that connects to the Blue Triangle API to analyze real user monitoring (RUM) data and revenue impact, helping teams track performance regressions, identify slow resources, and uncover revenue opportunities.

Features

Fetch real-time and historical performance data (LCP, TBT, CLS, INP, etc.)
Compare current vs. previous time ranges (delta and % change)
Get revenue and lost revenue opportunity estimates
Identify slow/fast resources per domain, file, or service
Generate reports across multiple time ranges
Export to Markdown, JSON, CSV, HTML, or PDF formats
Colored terminal output with progress indicators
Supports top N pages by page views
Percentile analysis (p50, p75, p90, p95, p99) in addition to averages
Multiple data types: RUM, Synthetic, Native, Basepage
Data filtering by traffic segment, country, and device type
Executive friction summary for quick performance insights
Resource file analysis with pattern matching
Slack, Microsoft Teams, and Email notifications

Sample Report Screenshot

Requirements

Python 3.9+
Blue Triangle site prefix, API Key, and email

Quick Start

1. Clone and Install

git clone https://github.com/konfirmed/bluetriangle-cli-reporter.git
cd bluetriangle-cli-reporter
pip install -r requirements.txt

2. Configure Credentials

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env with your Blue Triangle credentials:

BT_API_EMAIL=your@email.com
BT_API_KEY=your_api_key_here
BT_SITE_PREFIX=your_site_prefix

3. Test Your Connection

python bt_insights.py --test-connection

4. Generate a Report

python bt_insights.py --page homepage checkout --time-range 7d --output report.md

Configuration

Required Environment Variables

Variable	Description
`BT_API_EMAIL`	Your Blue Triangle account email
`BT_API_KEY`	Your Blue Triangle API key
`BT_SITE_PREFIX`	Your site prefix (from dashboard URL)

Optional Environment Variables

Variable	Default	Description
`BT_REQUEST_TIMEOUT`	`30`	API request timeout in seconds
`BT_LOG_LEVEL`	`INFO`	Log level: DEBUG, INFO, WARNING, ERROR

Usage Examples

Basic Usage

# Analyze specific pages over 7 days
python bt_insights.py --page homepage checkout --time-range 7d

# Analyze top 20 pages by traffic
python bt_insights.py --top-pages --time-range 28d

# Focus on specific metrics only
python bt_insights.py --page homepage --metrics LCP INP CLS

Output Formats

# Default: Markdown report
python bt_insights.py --page homepage -o report.md

# Export as JSON (for programmatic use)
python bt_insights.py --page homepage --format json -o metrics.json

# Export as CSV (for spreadsheets)
python bt_insights.py --page homepage --format csv -o metrics.csv

# Export as PDF with charts
python bt_insights.py --page homepage --format pdf -o report.pdf

Multi-Range Reports

# Compare across multiple time ranges
python bt_insights.py --page homepage --multi-range 24h,7d,28d -o comparison.md

Quiet Mode (for scripts)

# Suppress progress output
python bt_insights.py --page homepage --quiet -o report.md

# Disable colors (for piping/logging)
python bt_insights.py --page homepage --no-color

HTML Reports with Charts

# Generate HTML report with embedded Chart.js visualizations
python bt_insights.py --page homepage checkout --format html -o report.html

API Caching

# Enable caching to speed up repeated requests (1 hour TTL)
python bt_insights.py --page homepage --cache

# Clear the cache
python bt_insights.py --clear-cache

Configuration File

# Use a custom config file
python bt_insights.py --page homepage --config my_config.yaml

# Default locations searched: bt_config.yaml, ~/.bt_config.yaml

Example bt_config.yaml:

api:
  email: your-email@example.com
  key: your-api-key
  site_prefix: your-site
  timeout: 30

cache:
  enabled: true
  ttl: 300

analysis:
  percentile: 90        # Options: 50, 75, 90, 95, 99
  data_type: rum        # Options: rum, synthetic, native, basepage
  resource_group: domain  # Options: domain, file, service

thresholds:
  LCP: 2500
  TBT: 200
  CLS: 0.1
  INP: 200

Threshold Alerts

# Show alerts for metrics exceeding Web Vitals thresholds
python bt_insights.py --page homepage --alerts

Data Filtering

# Filter by traffic segment
python bt_insights.py --page homepage --segment eCommerce

# Filter by country (ISO 3166 codes)
python bt_insights.py --page homepage --country US CA GB

# Filter by device type
python bt_insights.py --page homepage --device Mobile

# Combine filters: Mobile users in Canada
python bt_insights.py --page homepage --country CA --device Mobile

# Analyze specific resource files (supports wildcards)
python bt_insights.py --page homepage --resource-file "*onelink*"

# Generate executive friction summary
python bt_insights.py --page homepage --summary

Advanced Data Analysis

# Use 90th percentile instead of averages
python bt_insights.py --page homepage --percentile 90

# Use median (50th percentile)
python bt_insights.py --page homepage --percentile 50

# Analyze synthetic monitoring data instead of RUM
python bt_insights.py --page homepage --data-type synthetic

# Group resources by file instead of domain
python bt_insights.py --page homepage --resource-group file

# Combine options: 95th percentile synthetic data grouped by service
python bt_insights.py --page homepage --percentile 95 --data-type synthetic --resource-group service

Period Comparison

# Compare two time periods (epoch timestamps)
python bt_insights.py --page homepage --compare 1704067200 1704672000 1704672000 1705276800

Shell Completion

# Generate bash completion script
python bt_insights.py --generate-completion bash > /etc/bash_completion.d/bt_insights

# Generate zsh completion script
python bt_insights.py --generate-completion zsh > ~/.zsh/completions/_bt_insights

Debugging

# Enable verbose logging
python bt_insights.py --page homepage --verbose

# Test API connection
python bt_insights.py --test-connection

Notifications (Slack/Teams/Email)

# Send report notification to Slack
python bt_insights.py --page homepage --slack-webhook https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Send report notification to Microsoft Teams
python bt_insights.py --page homepage --teams-webhook https://outlook.office.com/webhook/YOUR/WEBHOOK/URL

# Send report via email (requires SMTP environment variables)
python bt_insights.py --page homepage --email-to recipient@example.com --email-subject "Weekly Report"

# Attach report file to email
python bt_insights.py --page homepage --email-to recipient@example.com --email-attach

# Combine multiple notifications
python bt_insights.py --page homepage --slack-webhook URL --email-to user@example.com

Email Configuration: Set these environment variables for email notifications:

BT_SMTP_SERVER - SMTP server hostname (default: smtp.gmail.com)
BT_SMTP_PORT - SMTP server port (default: 587)
BT_SMTP_EMAIL - Sender email address
BT_SMTP_PASSWORD - Sender email password or app password

Command-Line Reference

python bt_insights.py --help

Page Selection

Flag	Description	Example
`--page`	Specify page names to analyze	`--page homepage checkout`
`--top-pages`	Analyze top 20 pages by views	`--top-pages`

Time Range

Flag	Description	Example
`--time-range`	Predefined time window (default: 7d)	`--time-range 28d`
`--start`	Custom start time (epoch)	`--start 1710796800`
`--end`	Custom end time (epoch)	`--end 1710883200`
`--multi-range`	Multiple ranges, comma-separated	`--multi-range 24h,7d,28d`

Output Options

Flag	Description	Example
`--output`, `-o`	Output filename	`-o report.md`
`--format`, `-f`	Output format: markdown, json, csv, html, pdf	`--format pdf`
`--metrics`	Filter to specific metrics	`--metrics LCP TBT CLS`
`--alerts`	Show threshold alerts for metrics	`--alerts`

Notification Options

Flag	Description	Example
`--slack-webhook`	Slack incoming webhook URL	`--slack-webhook URL`
`--teams-webhook`	Microsoft Teams incoming webhook URL	`--teams-webhook URL`
`--email-to`	Email recipient(s)	`--email-to user@example.com`
`--email-subject`	Email subject line	`--email-subject "Report"`
`--email-attach`	Attach report file to email	`--email-attach`

Caching & Configuration

Flag	Description	Example
`--cache`	Enable API response caching	`--cache`
`--clear-cache`	Clear cache and exit	`--clear-cache`
`--config`	Path to YAML config file	`--config my_config.yaml`

Data Filtering

Flag	Description	Example
`--segment`	Filter by traffic segment(s)	`--segment eCommerce`
`--country`	Filter by country code(s) in ISO 3166 format	`--country US CA GB`
`--device`	Filter by device type(s): Desktop, Mobile, Tablet	`--device Mobile`
`--resource-file`	Analyze specific resource files (supports wildcards)	`--resource-file "onelink"`
`--summary`	Show executive friction summary	`--summary`

Advanced Data Options

Flag	Description	Example
`--percentile`	Use percentile instead of average (50, 75, 90, 95, 99)	`--percentile 90`
`--data-type`	Data source: rum, synthetic, native, basepage (default: rum)	`--data-type synthetic`
`--resource-group`	Group resources by: domain, file, service (default: domain)	`--resource-group file`

Comparison Mode

Flag	Description	Example
`--compare`	Compare two time periods (4 epoch timestamps)	`--compare START1 END1 START2 END2`

Utility Options

Flag	Description
`--test-connection`	Test API connection and exit
`--generate-completion`	Generate shell completion (bash/zsh)
`--dry-run`	Preview actions without making API calls
`--no-color`	Disable colored output
`--quiet`, `-q`	Suppress progress output
`--verbose`, `-v`	Enable debug logging

Available Time Ranges

Code	Description
`qd`	Quarter day (~6 hours)
`hd`	Half day (12 hours)
`24h`	Last 24 hours
`xd`	1.5 days
`2d`	Last 2 days
`6d`	Last 6 days
`7d`	Last 7 days (Default)
`28d`	Last 28 days
`30d`	Last 30 days
`90d`	Last 90 days
`1y`	Last 1 year
`2y`	Last 2 years
`3y`	Last 3 years

Available Metrics

Code	Full Name
`LCP`	Largest Contentful Paint
`TBT`	Total Blocking Time
`CLS`	Cumulative Layout Shift
`INP`	Interaction to Next Paint
`FB`	First Byte (TTFB)

Sample Output

Summary Table (Markdown)

| Page     | Onload (Curr) | Onload (Prev) | LCP (Curr) | LCP (Prev) | ...
|----------|---------------|---------------|------------|------------|-----
| homepage      | 2800          | 2900          | 1800       | 2100       | ...

JSON Output

[
  {
    "page": "homepage",
    "onload_curr": 2800,
    "onload_prev": 2900,
    "lcp_curr": 1800,
    "lcp_prev": 2100
  }
]

Insights Included

Performance deltas (e.g., "LCP improved", "INP worsened")
Weighted performance scores
Resource usage breakdowns (domain-level)
Revenue & lost revenue opportunity
Event markers from the Blue Triangle dashboard

Running Tests

pip install pytest
pytest tests/ -v

Name		Name	Last commit message	Last commit date
Latest commit History 60 Commits
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
bt_config.yaml.example		bt_config.yaml.example
bt_insights.py		bt_insights.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Blue Triangle CLI Reporter

Features

Sample Report Screenshot

Requirements

Quick Start

1. Clone and Install

2. Configure Credentials

3. Test Your Connection

4. Generate a Report

Configuration

Required Environment Variables

Optional Environment Variables

Usage Examples

Basic Usage

Output Formats

Multi-Range Reports

Quiet Mode (for scripts)

HTML Reports with Charts

API Caching

Configuration File

Threshold Alerts

Data Filtering

Advanced Data Analysis

Period Comparison

Shell Completion

Debugging

Notifications (Slack/Teams/Email)

Command-Line Reference

Page Selection

Time Range

Output Options

Notification Options

Caching & Configuration

Data Filtering

Advanced Data Options

Comparison Mode

Utility Options

Available Time Ranges

Available Metrics

Sample Output

Summary Table (Markdown)

JSON Output

Insights Included

Running Tests

TODOs & Future Improvements

Author

Questions or Requests

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages