# Streamlit HealthCheck
 |  | [](https://codecov.io/gh/saradindusengupta/streamlit-healthcheck) | [](https://github.com/saradindusengupta/streamlit-healthcheck/actions/workflows/main.yml)
> **Monitor, visualize, and manage the health of your Streamlit multi-page applications with ease.**
---
## Overview
Streamlit HealthCheck is a comprehensive health monitoring solution for Streamlit apps. It tracks system resources, external dependencies, and custom application checks, providing a real-time dashboard for operational insights and troubleshooting.
- **System Resource Monitoring:** CPU, memory, disk usage with configurable thresholds
- **Dependency Checks:** API endpoints and database connectivity status
- **Custom Health Checks:** Easily register and visualize custom checks for your app
- **Streamlit Page Error Tracking:** Detects exceptions and `st.error` calls across pages
- **Live Dashboard:** Interactive Streamlit UI with tabs for system, dependencies, custom checks, and page errors
- **Configurable:** All checks and thresholds are managed via a simple JSON config file
---
## How to Set Up & Run
Follow these steps to set up and launch the Streamlit HealthCheck dashboard using the `status_page` app:
### 1. Install Dependencies
Make sure you have Python 3.11+ and Streamlit installed. You can install all required packages using:
```bash
pip install -r requirements.txt
```
Or, to install just the healthcheck package:
```bash
pip install streamlit_healthcheck
```
### 2. Configure Health Checks
Edit `config/health_check_config.json` to customize system thresholds, endpoints, and custom checks. Example config:
```json
{
"system": { "cpu": 80, "memory": 75 },
"dependencies": ["https://api.example.com", "postgresql://..."],
"custom_checks": ["my_custom_check"]
}
```
### 3. Run the Streamlit Dashboard
Launch the main dashboard app:
```bash
streamlit run status_page/Home.py
```
This will open the healthcheck dashboard in your browser. Use the sidebar to navigate between system, dependency, and custom check tabs.
### 4. Add More Pages (Optional)
You can extend the dashboard by adding new pages to the `status_page/pages/` directory. Each `.py` file will appear as a tab in the Streamlit app.
### 5. Troubleshooting
If you encounter issues:
- Ensure your config file is valid JSON
- Check that all dependencies are reachable
- Review error messages in the dashboard tabs
---
---
## Features
| Feature | Description |
| ------------------- | ----------------------------------------------------------------- |
| System Health | Monitors CPU, memory, disk usage with warning/critical thresholds |
| Dependency Checks | Verifies API endpoints and database connections |
| Custom Checks | Register custom health checks for your app logic |
| Page Error Tracking | Captures exceptions and Streamlit errors per page |
| Live Dashboard | Interactive UI with tabs and status indicators |
| Configurable | JSON-based config for checks and thresholds |
---
## Configuration
All health check settings are managed via `config/health_check_config.json`. You can customize:
- Check intervals
- System resource thresholds
- API endpoints and database connections
- Custom checks
- Supports environment variables and optional YAML/JSON config for check registration.
- Default timeouts and thresholds are overridable per-check.
> [!TIP]
> Use the dashboard's configuration expander to adjust thresholds and save changes on the fly.
---
## Project Structure
```text
src/streamlit_healthcheck/ # Core healthcheck logic
status_page/ # Streamlit UI pages
config/health_check_config.json # Health check configuration
requirements.txt # Python dependencies
Makefile # Build and test commands
tests/ # Unit tests
```
The project structure and control flow looks like below
```text
Project Control Flow
[System Metrics] [Dependency Probes] [Custom Checks]
| | |
+--------+----------+----------+-----------+
| |
Collector (polls / hooks / events)
|
Checker Engine
(thresholds, retries, caching)
|
Aggregator
(status rollup + history store)
|
Streamlit Dashboard
(status panels, graphs, runbooks)
|
Alerts / Notifications / Webhooks
```
Figure: high-level architecture and control flow (image from assets/).
---
## Key features
- Run synchronous or async health checks with timeouts and recovery hints
- Register custom checks (liveness, readiness, dependency checks)
- Expose HTTP/Streamlit endpoints for machine-readable and human-readable status
- Emit structured metrics/events suitable for scraping or CI validation
- Simple integration helpers for common backends (Redis, Postgres, external APIs)
## Quickstart
---
1) Install:
```{bash}
pip install streamlit_healthcheck
```
2) Basic usage:
```{python}
from streamlit_healthcheck import healthcheck
report = healthcheck.run_all(timeout=5)
if not report:
# handle degraded state (log, alert, fail pipeline)
print(report.summary)
```
## API (common surface)
- healthcheck.run_all(timeout: float = 5) -> HealthReport
Runs all registered checks and returns a HealthReport object with:
- ok: bool
- summary: str
- details: dict
- duration: float
- healthcheck.register(name: str, fn: Callable, *, critical: bool = False)
Register a custom check function. Critical checks mark the whole service unhealthy.
- healthcheck.serve(endpoint: str = "/health", host: str = "0.0.0.0", port: int = 8000)
Expose a simple HTTP endpoint (or embed in Streamlit) that returns JSON health status.
## DevOps alignment
- Reliable: Designed to reduce deployment failures and improve service uptime.
- Automatable: Designed to be executed in CI/CD pipelines (pre-deploy checks, post-deploy smoke tests).
- Observable: Emits structured outputs and metrics for dashboards and alerting.
- Lean: Small, focused checks to enable frequent, low-risk deployments.
- Measurable: Integrates with monitoring to improve MTTR and change failure rate.
- Shareable: Clear APIs, runbooks examples, and integration docs for teams.
## Integration tips
- Use canary deployments or blue-green deployments to minimize impact during rollouts.
- Use feature flags or conditional checks to avoid noisy alerts during rollouts.
- Run healthcheck.run_all in CI as a gating step for deployments.
- Expose metrics to Prometheus or your metrics backend for SLA tracking.
## Contributing
- Tests, type hints, and small, focused PRs welcome.
- Follow the repository's [CONTRIBUTING.md](CONTRIBUTING.md) and code-of-conduct.
- Add unit tests for new checks and integrations; CI runs linting and tests.
- Use GitHub issues for bugs, feature requests, and discussions.
To publish to PyPI run the GitHub Action [release.yml](https://github.com/saradindusengupta/streamlit-healthcheck/actions/workflows/release.yml)
## License
GNU GENERAL PUBLIC LICENSE v3
## Troubleshooting
> [!WARNING]
> If the dashboard reports a "critical" status, check the error details in the relevant tab. For API/database issues, verify connectivity and credentials. For system resource alerts, consider scaling your infrastructure.
---
## Getting Help
- [Library Documentation](https://saradindusengupta.co.in/streamlit-healthcheck/streamlit_healthcheck.html)
- [Issues & Discussions](https://github.com/saradindusengupta/streamlit-healthcheck/issues)
---
Raw data
{
"_id": null,
"home_page": null,
"name": "streamlit-healthcheck",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "streamlit, healthcheck, system, monitoring, app, dashboard",
"author": null,
"author_email": "Saradindu Sengupta <saradindu.mi1@iiitmk.ac.in>",
"download_url": "https://files.pythonhosted.org/packages/95/3e/abccdfbbfe241741a640c310588db6d669fea33c4b39824a9a965a6b599b/streamlit_healthcheck-0.1.7.tar.gz",
"platform": null,
"description": "# Streamlit HealthCheck\n\n  |  | [](https://codecov.io/gh/saradindusengupta/streamlit-healthcheck) | [](https://github.com/saradindusengupta/streamlit-healthcheck/actions/workflows/main.yml)\n\n> **Monitor, visualize, and manage the health of your Streamlit multi-page applications with ease.**\n\n---\n\n## Overview\n\nStreamlit HealthCheck is a comprehensive health monitoring solution for Streamlit apps. It tracks system resources, external dependencies, and custom application checks, providing a real-time dashboard for operational insights and troubleshooting.\n\n- **System Resource Monitoring:** CPU, memory, disk usage with configurable thresholds\n- **Dependency Checks:** API endpoints and database connectivity status\n- **Custom Health Checks:** Easily register and visualize custom checks for your app\n- **Streamlit Page Error Tracking:** Detects exceptions and `st.error` calls across pages\n- **Live Dashboard:** Interactive Streamlit UI with tabs for system, dependencies, custom checks, and page errors\n- **Configurable:** All checks and thresholds are managed via a simple JSON config file\n\n---\n\n## How to Set Up & Run\n\nFollow these steps to set up and launch the Streamlit HealthCheck dashboard using the `status_page` app:\n\n### 1. Install Dependencies\n\nMake sure you have Python 3.11+ and Streamlit installed. You can install all required packages using:\n\n```bash\npip install -r requirements.txt\n```\n\nOr, to install just the healthcheck package:\n\n```bash\npip install streamlit_healthcheck\n```\n\n### 2. Configure Health Checks\n\nEdit `config/health_check_config.json` to customize system thresholds, endpoints, and custom checks. Example config:\n\n```json\n{\n \"system\": { \"cpu\": 80, \"memory\": 75 },\n \"dependencies\": [\"https://api.example.com\", \"postgresql://...\"],\n \"custom_checks\": [\"my_custom_check\"]\n}\n```\n\n### 3. Run the Streamlit Dashboard\n\nLaunch the main dashboard app:\n\n```bash\nstreamlit run status_page/Home.py\n```\n\nThis will open the healthcheck dashboard in your browser. Use the sidebar to navigate between system, dependency, and custom check tabs.\n\n### 4. Add More Pages (Optional)\n\nYou can extend the dashboard by adding new pages to the `status_page/pages/` directory. Each `.py` file will appear as a tab in the Streamlit app.\n\n### 5. Troubleshooting\n\nIf you encounter issues:\n\n- Ensure your config file is valid JSON\n- Check that all dependencies are reachable\n- Review error messages in the dashboard tabs\n\n---\n\n---\n\n## Features\n\n| Feature | Description |\n| ------------------- | ----------------------------------------------------------------- |\n| System Health | Monitors CPU, memory, disk usage with warning/critical thresholds |\n| Dependency Checks | Verifies API endpoints and database connections |\n| Custom Checks | Register custom health checks for your app logic |\n| Page Error Tracking | Captures exceptions and Streamlit errors per page |\n| Live Dashboard | Interactive UI with tabs and status indicators |\n| Configurable | JSON-based config for checks and thresholds |\n\n---\n\n## Configuration\n\nAll health check settings are managed via `config/health_check_config.json`. You can customize:\n\n- Check intervals\n- System resource thresholds\n- API endpoints and database connections\n- Custom checks\n- Supports environment variables and optional YAML/JSON config for check registration.\n- Default timeouts and thresholds are overridable per-check.\n\n> [!TIP]\n> Use the dashboard's configuration expander to adjust thresholds and save changes on the fly.\n\n---\n\n## Project Structure\n\n```text\nsrc/streamlit_healthcheck/ # Core healthcheck logic\nstatus_page/ # Streamlit UI pages\nconfig/health_check_config.json # Health check configuration\nrequirements.txt # Python dependencies\nMakefile # Build and test commands\ntests/ # Unit tests\n```\n\nThe project structure and control flow looks like below\n\n```text\nProject Control Flow\n\n [System Metrics] [Dependency Probes] [Custom Checks]\n | | |\n +--------+----------+----------+-----------+\n | |\n Collector (polls / hooks / events)\n |\n Checker Engine\n (thresholds, retries, caching)\n |\n Aggregator\n (status rollup + history store)\n |\n Streamlit Dashboard\n (status panels, graphs, runbooks)\n |\n Alerts / Notifications / Webhooks\n```\n\n\n\nFigure: high-level architecture and control flow (image from assets/).\n\n---\n\n## Key features\n\n- Run synchronous or async health checks with timeouts and recovery hints\n- Register custom checks (liveness, readiness, dependency checks)\n- Expose HTTP/Streamlit endpoints for machine-readable and human-readable status\n- Emit structured metrics/events suitable for scraping or CI validation\n- Simple integration helpers for common backends (Redis, Postgres, external APIs)\n\n## Quickstart\n\n---\n\n1) Install:\n\n```{bash}\npip install streamlit_healthcheck\n```\n\n2) Basic usage:\n\n```{python}\nfrom streamlit_healthcheck import healthcheck\nreport = healthcheck.run_all(timeout=5)\nif not report:\n # handle degraded state (log, alert, fail pipeline)\n print(report.summary)\n```\n\n## API (common surface)\n\n- healthcheck.run_all(timeout: float = 5) -> HealthReport\n Runs all registered checks and returns a HealthReport object with:\n\n - ok: bool\n - summary: str\n - details: dict\n - duration: float\n- healthcheck.register(name: str, fn: Callable, *, critical: bool = False)\n Register a custom check function. Critical checks mark the whole service unhealthy.\n- healthcheck.serve(endpoint: str = \"/health\", host: str = \"0.0.0.0\", port: int = 8000)\n Expose a simple HTTP endpoint (or embed in Streamlit) that returns JSON health status.\n\n## DevOps alignment\n\n- Reliable: Designed to reduce deployment failures and improve service uptime.\n- Automatable: Designed to be executed in CI/CD pipelines (pre-deploy checks, post-deploy smoke tests).\n- Observable: Emits structured outputs and metrics for dashboards and alerting.\n- Lean: Small, focused checks to enable frequent, low-risk deployments.\n- Measurable: Integrates with monitoring to improve MTTR and change failure rate.\n- Shareable: Clear APIs, runbooks examples, and integration docs for teams.\n\n## Integration tips\n\n- Use canary deployments or blue-green deployments to minimize impact during rollouts.\n- Use feature flags or conditional checks to avoid noisy alerts during rollouts.\n- Run healthcheck.run_all in CI as a gating step for deployments.\n- Expose metrics to Prometheus or your metrics backend for SLA tracking.\n\n## Contributing\n\n- Tests, type hints, and small, focused PRs welcome.\n- Follow the repository's [CONTRIBUTING.md](CONTRIBUTING.md) and code-of-conduct.\n- Add unit tests for new checks and integrations; CI runs linting and tests.\n- Use GitHub issues for bugs, feature requests, and discussions.\n\nTo publish to PyPI run the GitHub Action [release.yml](https://github.com/saradindusengupta/streamlit-healthcheck/actions/workflows/release.yml)\n\n## License\n\nGNU GENERAL PUBLIC LICENSE v3\n\n## Troubleshooting\n\n> [!WARNING]\n> If the dashboard reports a \"critical\" status, check the error details in the relevant tab. For API/database issues, verify connectivity and credentials. For system resource alerts, consider scaling your infrastructure.\n\n---\n\n## Getting Help\n\n- [Library Documentation](https://saradindusengupta.co.in/streamlit-healthcheck/streamlit_healthcheck.html)\n- [Issues & Discussions](https://github.com/saradindusengupta/streamlit-healthcheck/issues)\n\n---\n",
"bugtrack_url": null,
"license": null,
"summary": "Comprehensive health monitoring for Streamlit apps: system, dependencies, custom checks, and page errors.",
"version": "0.1.7",
"project_urls": {
"Documentation": "https://saradindusengupta.co.in/streamlit-healthcheck/streamlit_healthcheck.html",
"Homepage": "https://github.com/saradindusengupta/streamlit-healthcheck",
"Issues": "https://github.com/saradindusengupta/streamlit-healthcheck/issues",
"Repository": "https://github.com/saradindusengupta/streamlit-healthcheck"
},
"split_keywords": [
"streamlit",
" healthcheck",
" system",
" monitoring",
" app",
" dashboard"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1e5c9e940f2b54c44c459b82f8e024587da5cc03fdb017d5a19baaf24bf5a7ab",
"md5": "de0451ff0f6b648f1e3fc36a4947052d",
"sha256": "ed47b43c158267942b6ffb6fb0ac824ad3ed8a73a92591813c035f66b800199e"
},
"downloads": -1,
"filename": "streamlit_healthcheck-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de0451ff0f6b648f1e3fc36a4947052d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 44118,
"upload_time": "2025-10-20T13:43:58",
"upload_time_iso_8601": "2025-10-20T13:43:58.487928Z",
"url": "https://files.pythonhosted.org/packages/1e/5c/9e940f2b54c44c459b82f8e024587da5cc03fdb017d5a19baaf24bf5a7ab/streamlit_healthcheck-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "953eabccdfbbfe241741a640c310588db6d669fea33c4b39824a9a965a6b599b",
"md5": "e32214975ec059dba2dfc5aeaa064e9c",
"sha256": "93684edb3c5eb200a8232c2e592159baaff62956e21582fb96fe55f2bec6f317"
},
"downloads": -1,
"filename": "streamlit_healthcheck-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "e32214975ec059dba2dfc5aeaa064e9c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 386185,
"upload_time": "2025-10-20T13:43:59",
"upload_time_iso_8601": "2025-10-20T13:43:59.750342Z",
"url": "https://files.pythonhosted.org/packages/95/3e/abccdfbbfe241741a640c310588db6d669fea33c4b39824a9a965a6b599b/streamlit_healthcheck-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 13:43:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "saradindusengupta",
"github_project": "streamlit-healthcheck",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "streamlit",
"specs": []
},
{
"name": "fastapi",
"specs": [
[
">=",
"0.68.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.15.0"
]
]
},
{
"name": "joblib",
"specs": []
},
{
"name": "psutil",
"specs": []
},
{
"name": "click",
"specs": []
}
],
"lcname": "streamlit-healthcheck"
}
JSON
