| Name | service-ping-sping JSON |
| Version |
0.2.4
JSON |
| download |
| home_page | None |
| Summary | The sping command provides modern HTTP/TCP latency monitoring with real-time terminal visualization |
| upload_time | 2025-08-24 02:41:54 |
| maintainer | dseltzer |
| docs_url | None |
| author | dseltzer |
| requires_python | >=3.9 |
| license | # MIT License
Copyright (c) 2025 sping contributors
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 sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
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. |
| keywords |
cli
http
httping
latency
monitoring
network
ping
tcp
terminal
tui
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# service-ping (sping)
Modern terminal HTTP/TCP latency monitoring tool with real-time visualization. Think `httping` meets modern CLI design with rich terminal UI, phase timing, and advanced analytics.
**Status**: Feature-complete MVP with HTTP/TCP support, phase timing, outlier detection, and comprehensive monitoring capabilities.
## Features
- 🌐 **HTTP & TCP Monitoring**: Support for `http://`, `https://`, and `tcp://` protocols
- 📊 **Real-time Visualization**: Interactive charts and live statistics in your terminal
- 🔍 **Phase Breakdown**: DNS, connection, TLS, request, and response timing
- 🚨 **Outlier Detection**: Automatic outlier detection using MAD (Median Absolute Deviation)
- ⚠️ **Threshold Alerting**: Warning and critical thresholds with exit codes
- 🌍 **DNS Control**: IPv4/IPv6 selection and DNS resolution caching
- 📈 **Advanced Statistics**: Percentiles (p50, p90, p95, p99), standard deviation
- 💾 **Multiple Output Formats**: Interactive UI, plain text, JSON, and JSON export
- 🔐 **Authentication**: Bearer tokens and basic auth support
- 🎨 **Rich Terminal UI**: Beautiful charts, color-coded logs, and responsive layouts
- 🌈 **Color Palettes**: Choose from 8 themed color schemes (sunset, ocean, forest, volcano, galaxy, arctic, neon, monochrome)
## Demo
<img src="https://gitlab.com/dseltzer/sping/-/raw/master/demo/sping-graph-demo.gif" alt="sping Interactive Demo" width="50%">
*Real-time latency monitoring with interactive charts showing HTTP response times, outlier detection, and live statistics.*
## Install
```bash
pip install service-ping-sping
```
For development:
```bash
pip install -e .[dev]
```
## Quick Start
```bash
# HTTP monitoring with interactive UI
sping google.com
# TCP connection monitoring
sping tcp://google.com:80
# HTTPS with custom options
sping https://api.example.com --interval 0.5 --count 20
# JSON output for automation
sping google.com --json --count 5
# Advanced monitoring with thresholds
sping example.com --warn 100 --crit 500 --percentiles
# Try different color themes
sping example.com --palette ocean
```
## Usage Examples
### HTTP/HTTPS Monitoring
```bash
# Basic HTTP monitoring (auto-adds http://)
sping example.com
# HTTPS with custom method and body transfer
sping https://api.example.com --method POST --body
# IPv4 only with DNS caching
sping google.com --ipv4 --resolve-once
# With authentication
sping api.example.com --auth "bearer:your-token"
sping api.example.com --auth "user:password"
```
### TCP Connection Monitoring
```bash
# Test TCP connectivity
sping tcp://google.com:80
sping tcp://example.com:443
# Monitor database connections
sping tcp://localhost:5432 --interval 0.1
```
### Advanced Features
```bash
# Outlier detection and thresholds
sping example.com --warn 100 --crit 500 --count 100
# Export detailed timing data
sping example.com --export-file results.json --count 50
# Show percentile statistics
sping example.com --percentiles --count 100
# Plain output for scripting
sping example.com --plain --count 5
```
## Outlier Detection
sping automatically detects unusual latency spikes using **Median Absolute Deviation (MAD)** analysis:
### What Counts as an Outlier
- **Latency outliers**: Response times that deviate significantly from recent baseline performance
- **Statistical threshold**: Latencies that are more than **6x the MAD** away from the median
- **Baseline requirement**: Needs at least 10 successful samples to establish baseline
- **Rolling window**: Uses the last 30 successful requests to calculate normal behavior
- **Successful requests only**: Only analyzes successful responses (errors are tracked separately)
### How It Works
1. **Baseline calculation**: Median of recent 30 successful latencies (e.g., 100ms)
2. **Variability measure**: MAD of those latencies (e.g., 15ms)
3. **Outlier threshold**: `|current_latency - median| / MAD > 6.0`
4. **Example**: If baseline is 100ms ± 15ms MAD, requests > 190ms or < 10ms would be outliers
### Visual Indicators
- **Interactive mode**: Outlier requests show `[OUTLIER]` marker in the log
- **Statistics bar**: Shows red outlier count when detected (e.g., `outliers 3`)
- **JSON output**: `"anomaly": true` field in export data (kept for API compatibility)
*Note: Outlier detection helps identify performance degradation, network issues, or service problems that might not trigger error thresholds.*
## Command Line Options
### Core Options
- `-i, --interval FLOAT`: Seconds between probes (default: 1.0)
- `-c, --count INT`: Number of probes then exit
- `--timeout FLOAT`: Request timeout in seconds (default: 10.0)
- `-X, --method TEXT`: HTTP method (default: HEAD)
### Protocol & DNS
- `--ipv4`: Force IPv4 only
- `--ipv6`: Force IPv6 only
- `--resolve-once`: Resolve DNS only once and cache
### HTTP Options
- `--body`: Include full body transfer time
- `--no-keepalive`: Disable persistent connections
- `--user-agent TEXT`: Custom User-Agent string
- `--auth TEXT`: Authentication (user:pass or bearer:token)
- `--insecure`: Skip TLS verification
### Monitoring & Alerts
- `--warn FLOAT`: Warning threshold in milliseconds
- `--crit FLOAT`: Critical threshold in milliseconds
- `--percentiles`: Show percentile statistics in summary
### UI & Display
- `--refresh-rate FLOAT`: UI update throttling in Hz (default: 4.0, higher = more responsive, lower = less CPU)
- `--palette PALETTE`: Color palette for latency visualization (default: sunset)
### Color Palettes
Choose from beautiful themed color palettes to customize your latency visualization:
- `sunset` (default): Warm oranges and reds reminiscent of a beautiful sunset
- `ocean`: Cool blues and teals like ocean depths
- `forest`: Natural greens from deep forest to bright sunlight
- `volcano`: Fiery reds and oranges like molten lava
- `galaxy`: Cosmic purples and magentas of deep space
- `arctic`: Crisp blues and whites of polar ice
- `neon`: Bright electric colors for a cyberpunk feel
- `monochrome`: Classic grayscale gradient
```bash
# Examples with different palettes
sping example.com --palette ocean
sping example.com --palette volcano --count 20
sping example.com --palette neon --percentiles
```
### Output Formats
- `--json`: JSON output mode (one object per line)
- `--plain`: Plain text output mode
- `--export-file FILE`: Export JSON results to file
## Output Formats
### Interactive Mode (Default)
Real-time terminal UI with:
- Live latency chart with gradient coloring
- Recent requests log with timing details
- Statistics panel with min/mean/max/stdev
- Outlier highlighting and threshold indicators
### Plain Text Mode (`--plain`)
```
[1] 1755658486.287: 484.313ms 200 (application/json) from httpbin.org (52.1.207.236)
--- https://httpbin.org/get sping summary ---
1 probes, 1 ok, 0 errors
Latency (ms): min 484.313 mean 484.313 max 484.313
```
### JSON Mode (`--json`)
```json
{"seq": 1, "timestamp": 1755658729.193, "latency_ms": 11.110, "status_code": 0, "error": null, "bytes_read": 0, "content_type": "tcp/connection", "host_address": "google.com (142.250.65.238)", "anomaly": false, "phases": {"dns_ms": 5.444, "connect_ms": 5.598, "tls_ms": null, "request_write_ms": null, "ttfb_ms": null, "body_read_ms": null, "total_ms": 11.110}}
```
## Phase Timing Breakdown
sping provides detailed timing for each phase of the connection:
- **DNS**: Domain name resolution time
- **Connect**: TCP connection establishment
- **TLS**: TLS/SSL handshake time (HTTPS only)
- **Request Write**: Time to send HTTP request
- **TTFB**: Time to first byte (response headers)
- **Body Read**: Time to read response body
- **Total**: End-to-end request time
## Exit Codes
- `0`: Success
- `1`: Warning threshold exceeded (when `--warn` specified)
- `2`: Critical threshold exceeded (when `--crit` specified)
Perfect for monitoring scripts and alerting systems.
## Quit Interactive Mode
Press `Ctrl+C` to gracefully exit and see the final summary.
## Requirements
- Python 3.9+
- Modern terminal with color support recommended
- Works on Linux, macOS, and Windows
## License
MIT - see [LICENSE.md](https://gitlab.com/dseltzer/sping/-/blob/master/LICENSE.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "service-ping-sping",
"maintainer": "dseltzer",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cli, http, httping, latency, monitoring, network, ping, tcp, terminal, tui",
"author": "dseltzer",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e2/89/cec1e6ef819fbc6fd1b89bef5719fc2fd6be33fa1dbdb91f6b8c503028b4/service_ping_sping-0.2.4.tar.gz",
"platform": null,
"description": "# service-ping (sping)\n\nModern terminal HTTP/TCP latency monitoring tool with real-time visualization. Think `httping` meets modern CLI design with rich terminal UI, phase timing, and advanced analytics.\n\n**Status**: Feature-complete MVP with HTTP/TCP support, phase timing, outlier detection, and comprehensive monitoring capabilities.\n\n## Features\n\n- \ud83c\udf10 **HTTP & TCP Monitoring**: Support for `http://`, `https://`, and `tcp://` protocols\n- \ud83d\udcca **Real-time Visualization**: Interactive charts and live statistics in your terminal\n- \ud83d\udd0d **Phase Breakdown**: DNS, connection, TLS, request, and response timing\n- \ud83d\udea8 **Outlier Detection**: Automatic outlier detection using MAD (Median Absolute Deviation)\n- \u26a0\ufe0f **Threshold Alerting**: Warning and critical thresholds with exit codes\n- \ud83c\udf0d **DNS Control**: IPv4/IPv6 selection and DNS resolution caching\n- \ud83d\udcc8 **Advanced Statistics**: Percentiles (p50, p90, p95, p99), standard deviation\n- \ud83d\udcbe **Multiple Output Formats**: Interactive UI, plain text, JSON, and JSON export\n- \ud83d\udd10 **Authentication**: Bearer tokens and basic auth support\n- \ud83c\udfa8 **Rich Terminal UI**: Beautiful charts, color-coded logs, and responsive layouts\n- \ud83c\udf08 **Color Palettes**: Choose from 8 themed color schemes (sunset, ocean, forest, volcano, galaxy, arctic, neon, monochrome)\n\n## Demo\n\n<img src=\"https://gitlab.com/dseltzer/sping/-/raw/master/demo/sping-graph-demo.gif\" alt=\"sping Interactive Demo\" width=\"50%\">\n\n*Real-time latency monitoring with interactive charts showing HTTP response times, outlier detection, and live statistics.*\n\n## Install\n\n```bash\npip install service-ping-sping\n```\n\nFor development:\n```bash\npip install -e .[dev]\n```\n\n## Quick Start\n\n```bash\n# HTTP monitoring with interactive UI\nsping google.com\n\n# TCP connection monitoring\nsping tcp://google.com:80\n\n# HTTPS with custom options\nsping https://api.example.com --interval 0.5 --count 20\n\n# JSON output for automation\nsping google.com --json --count 5\n\n# Advanced monitoring with thresholds\nsping example.com --warn 100 --crit 500 --percentiles\n\n# Try different color themes\nsping example.com --palette ocean\n```\n\n## Usage Examples\n\n### HTTP/HTTPS Monitoring\n```bash\n# Basic HTTP monitoring (auto-adds http://)\nsping example.com\n\n# HTTPS with custom method and body transfer\nsping https://api.example.com --method POST --body\n\n# IPv4 only with DNS caching\nsping google.com --ipv4 --resolve-once\n\n# With authentication\nsping api.example.com --auth \"bearer:your-token\"\nsping api.example.com --auth \"user:password\"\n```\n\n### TCP Connection Monitoring\n```bash\n# Test TCP connectivity\nsping tcp://google.com:80\nsping tcp://example.com:443\n\n# Monitor database connections\nsping tcp://localhost:5432 --interval 0.1\n```\n\n### Advanced Features\n```bash\n# Outlier detection and thresholds\nsping example.com --warn 100 --crit 500 --count 100\n\n# Export detailed timing data\nsping example.com --export-file results.json --count 50\n\n# Show percentile statistics\nsping example.com --percentiles --count 100\n\n# Plain output for scripting\nsping example.com --plain --count 5\n```\n\n## Outlier Detection\n\nsping automatically detects unusual latency spikes using **Median Absolute Deviation (MAD)** analysis:\n\n### What Counts as an Outlier\n- **Latency outliers**: Response times that deviate significantly from recent baseline performance\n- **Statistical threshold**: Latencies that are more than **6x the MAD** away from the median\n- **Baseline requirement**: Needs at least 10 successful samples to establish baseline \n- **Rolling window**: Uses the last 30 successful requests to calculate normal behavior\n- **Successful requests only**: Only analyzes successful responses (errors are tracked separately)\n\n### How It Works\n1. **Baseline calculation**: Median of recent 30 successful latencies (e.g., 100ms)\n2. **Variability measure**: MAD of those latencies (e.g., 15ms) \n3. **Outlier threshold**: `|current_latency - median| / MAD > 6.0`\n4. **Example**: If baseline is 100ms \u00b1 15ms MAD, requests > 190ms or < 10ms would be outliers\n\n### Visual Indicators\n- **Interactive mode**: Outlier requests show `[OUTLIER]` marker in the log\n- **Statistics bar**: Shows red outlier count when detected (e.g., `outliers 3`)\n- **JSON output**: `\"anomaly\": true` field in export data (kept for API compatibility)\n\n*Note: Outlier detection helps identify performance degradation, network issues, or service problems that might not trigger error thresholds.*\n\n## Command Line Options\n\n### Core Options\n- `-i, --interval FLOAT`: Seconds between probes (default: 1.0)\n- `-c, --count INT`: Number of probes then exit\n- `--timeout FLOAT`: Request timeout in seconds (default: 10.0)\n- `-X, --method TEXT`: HTTP method (default: HEAD)\n\n### Protocol & DNS\n- `--ipv4`: Force IPv4 only\n- `--ipv6`: Force IPv6 only \n- `--resolve-once`: Resolve DNS only once and cache\n\n### HTTP Options\n- `--body`: Include full body transfer time\n- `--no-keepalive`: Disable persistent connections\n- `--user-agent TEXT`: Custom User-Agent string\n- `--auth TEXT`: Authentication (user:pass or bearer:token)\n- `--insecure`: Skip TLS verification\n\n### Monitoring & Alerts\n- `--warn FLOAT`: Warning threshold in milliseconds\n- `--crit FLOAT`: Critical threshold in milliseconds\n- `--percentiles`: Show percentile statistics in summary\n\n### UI & Display\n- `--refresh-rate FLOAT`: UI update throttling in Hz (default: 4.0, higher = more responsive, lower = less CPU)\n- `--palette PALETTE`: Color palette for latency visualization (default: sunset)\n\n### Color Palettes\nChoose from beautiful themed color palettes to customize your latency visualization:\n\n- `sunset` (default): Warm oranges and reds reminiscent of a beautiful sunset\n- `ocean`: Cool blues and teals like ocean depths \n- `forest`: Natural greens from deep forest to bright sunlight\n- `volcano`: Fiery reds and oranges like molten lava\n- `galaxy`: Cosmic purples and magentas of deep space\n- `arctic`: Crisp blues and whites of polar ice\n- `neon`: Bright electric colors for a cyberpunk feel\n- `monochrome`: Classic grayscale gradient\n\n```bash\n# Examples with different palettes\nsping example.com --palette ocean\nsping example.com --palette volcano --count 20\nsping example.com --palette neon --percentiles\n```\n\n### Output Formats\n- `--json`: JSON output mode (one object per line)\n- `--plain`: Plain text output mode\n- `--export-file FILE`: Export JSON results to file\n\n## Output Formats\n\n### Interactive Mode (Default)\nReal-time terminal UI with:\n- Live latency chart with gradient coloring\n- Recent requests log with timing details\n- Statistics panel with min/mean/max/stdev\n- Outlier highlighting and threshold indicators\n\n### Plain Text Mode (`--plain`)\n```\n[1] 1755658486.287: 484.313ms 200 (application/json) from httpbin.org (52.1.207.236)\n--- https://httpbin.org/get sping summary ---\n1 probes, 1 ok, 0 errors\nLatency (ms): min 484.313 mean 484.313 max 484.313\n```\n\n### JSON Mode (`--json`)\n```json\n{\"seq\": 1, \"timestamp\": 1755658729.193, \"latency_ms\": 11.110, \"status_code\": 0, \"error\": null, \"bytes_read\": 0, \"content_type\": \"tcp/connection\", \"host_address\": \"google.com (142.250.65.238)\", \"anomaly\": false, \"phases\": {\"dns_ms\": 5.444, \"connect_ms\": 5.598, \"tls_ms\": null, \"request_write_ms\": null, \"ttfb_ms\": null, \"body_read_ms\": null, \"total_ms\": 11.110}}\n```\n\n## Phase Timing Breakdown\n\nsping provides detailed timing for each phase of the connection:\n\n- **DNS**: Domain name resolution time\n- **Connect**: TCP connection establishment \n- **TLS**: TLS/SSL handshake time (HTTPS only)\n- **Request Write**: Time to send HTTP request\n- **TTFB**: Time to first byte (response headers)\n- **Body Read**: Time to read response body\n- **Total**: End-to-end request time\n\n## Exit Codes\n\n- `0`: Success\n- `1`: Warning threshold exceeded (when `--warn` specified)\n- `2`: Critical threshold exceeded (when `--crit` specified)\n\nPerfect for monitoring scripts and alerting systems.\n\n## Quit Interactive Mode\n\nPress `Ctrl+C` to gracefully exit and see the final summary.\n\n## Requirements\n\n- Python 3.9+\n- Modern terminal with color support recommended\n- Works on Linux, macOS, and Windows\n\n## License\n\nMIT - see [LICENSE.md](https://gitlab.com/dseltzer/sping/-/blob/master/LICENSE.md)\n",
"bugtrack_url": null,
"license": "# MIT License\n \n Copyright (c) 2025 sping contributors\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "The sping command provides modern HTTP/TCP latency monitoring with real-time terminal visualization",
"version": "0.2.4",
"project_urls": {
"Author Profile": "https://gitlab.com/dseltzer",
"Changelog": "https://gitlab.com/dseltzer/sping/-/releases",
"Homepage": "https://dseltzer.gitlab.io/sping/",
"Issues": "https://gitlab.com/dseltzer/sping/-/issues",
"Repository": "https://gitlab.com/dseltzer/sping.git"
},
"split_keywords": [
"cli",
" http",
" httping",
" latency",
" monitoring",
" network",
" ping",
" tcp",
" terminal",
" tui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "264a23200176b158c99faba54e7e0bfed8678f5056f7cda9d56bbaad763ef8d8",
"md5": "baef007d346c541c65315ec78b26b668",
"sha256": "8b75c566aef6fe37886e8c53aa9ed63313ca2491a022c6aa7d94e7c8c3c7c41f"
},
"downloads": -1,
"filename": "service_ping_sping-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "baef007d346c541c65315ec78b26b668",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 38140,
"upload_time": "2025-08-24T02:41:53",
"upload_time_iso_8601": "2025-08-24T02:41:53.618140Z",
"url": "https://files.pythonhosted.org/packages/26/4a/23200176b158c99faba54e7e0bfed8678f5056f7cda9d56bbaad763ef8d8/service_ping_sping-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e289cec1e6ef819fbc6fd1b89bef5719fc2fd6be33fa1dbdb91f6b8c503028b4",
"md5": "b5f1b5d394c6068070217bfc3817b59c",
"sha256": "cdbca920cb462c3a3c6bf4ecc927baf37ebfb95017ce666da0717605b7354bdb"
},
"downloads": -1,
"filename": "service_ping_sping-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "b5f1b5d394c6068070217bfc3817b59c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 30875,
"upload_time": "2025-08-24T02:41:54",
"upload_time_iso_8601": "2025-08-24T02:41:54.834762Z",
"url": "https://files.pythonhosted.org/packages/e2/89/cec1e6ef819fbc6fd1b89bef5719fc2fd6be33fa1dbdb91f6b8c503028b4/service_ping_sping-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 02:41:54",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "dseltzer",
"gitlab_project": "sping",
"lcname": "service-ping-sping"
}
