From 6990e868591175cdadc4bb4b7483d44ac7372f52 Mon Sep 17 00:00:00 2001 From: Radek Date: Thu, 22 May 2025 11:25:16 +0100 Subject: [PATCH] update README --- README.md | 103 +++++++++++++++++++----------------------------------- 1 file changed, 36 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 6d2e66a..9c6ade5 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,59 @@ -# LibreNMS-power-dash +# Power Monitoring System -Python code to extract and visualise power data collected from nLogic and APC pdu's via LibreNMS API +## Overview -# Power and Current Data Dashboard - -This project consists of two main scripts: one for collecting power and current data from a LibreNMS server and storing it in a SQLite database, and another for visualizing this data using a Plotly Dash dashboard. - -## Table of Contents - -- [Prerequisites](#prerequisites) -- [Installation](#installation) -- [Data Collection Script](#data-collection-script) -- [Dashboard Script](#dashboard-script) -- [Running the Dashboard](#running-the-dashboard) -- [Accessing the Dashboard](#accessing-the-dashboard) - -## Prerequisites - -Before you begin, ensure you have the following installed: - -- Python 3.11 or later -- SQLite -- LibreNMS server with API access - -## Installation - -Install the required dependencies using pip: - -dash -plotly -pandas -sqlite3 - -You can install these dependencies by running the following command: - -pip install dash plotly pandas +The Power Monitoring System is designed to collect, store, and visualize power usage data from various devices, primarily PDUs (Power Distribution Units). The system consists of two main components: a data collection script and a dashboard for visualizing the collected data. ## Data Collection Script -The data collection script fetches power and current data from a LibreNMS server and stores it in a SQLite database. +### Purpose -### Configuration - -1. API Configuration: - - Set the API_KEY and LIBRENMS_IP variables in the script to match your LibreNMS server details. - -2. Running the Script: - - Run the script using the command: python get_all_by_room.py +The data collection script is responsible for fetching power usage data from devices via an API, processing this data, and storing it in a SQLite database. The script is designed to run at regular intervals to ensure up-to-date data collection. ### Features -- Fetches device IDs and their locations from the LibreNMS server. -- Collects sensor data for current and power. -- Stores the collected data in a SQLite database (power_data.db). +- **Concurrent API Requests**: The script uses concurrent requests to efficiently gather data from multiple devices simultaneously, reducing the overall execution time. +- **Data Rounding**: Timestamps for the collected data are rounded to the nearest 5-minute interval to ensure consistency and alignment with the dashboard's requirements. +- **Configurable Concurrency**: The concurrency level can be adjusted to balance between speed and system load, ensuring optimal performance without overloading the API server. +- **Database Storage**: Collected data is stored in a SQLite database, with separate tables for building totals, room breakdowns, and customer breakdowns. -## Dashboard Script +### Usage -The dashboard script visualizes the data stored in the SQLite database using Plotly Dash. +1. **Configuration**: Ensure that the API key, LibreNMS IP, and other necessary configurations are set in the script. +2. **Running the Script**: Execute the script with the desired options, such as enabling debug output, limiting the number of runs, disabling database updates, and setting the concurrency level. +3. **Scheduling**: Schedule the script to run at regular intervals (e.g., every 5 minutes) using a task scheduler like `cron` or the Task Scheduler. -### Configuration +### Command Line Options -1. Database Configuration: - - Ensure the SQLite database (power_data.db) is in the same directory as the script or provide the correct path. +- `--debug`: Enable debug output for troubleshooting. +- `--runs`: Limit the number of runs for testing purposes. +- `--no-db-update`: Disable updates to the database to run the script in a read-only mode. +- `--concurrency-level`: Set the concurrency level for API requests to optimize performance. -2. Running the Dashboard: - - Run the script using the command: python dash-power.py +## Dashboard + +### Purpose + +The dashboard provides a visual representation of the power usage data collected by the script. It allows users to monitor power consumption, identify trends, and make informed decisions based on the data. ### Features -- Displays graphs for building totals and individual rooms. -- Allows selection of different time ranges (e.g., last 6 hours, last 1 day, etc.). -- Dynamically updates the legend values based on the zoom level. -- Accessible on external IP addresses. +- **Data Visualization**: The dashboard displays power usage data in an easy-to-understand format, with charts and graphs for building totals, room breakdowns, and customer breakdowns. +- **Regular Updates**: The dashboard is updated at regular intervals to reflect the latest data collected by the script. +- **User-Friendly Interface**: The dashboard is designed to be intuitive and user-friendly, allowing users to quickly access the information they need. -## Running the Dashboard +### Usage -1. Start the Dashboard: - - Run the script using the command: python dash-power.py +1. **Accessing the Dashboard**: Open the dashboard in a web browser to view the power usage data. +2. **Interpreting the Data**: Use the charts and graphs to monitor power consumption and identify any trends or anomalies. +3. **Customization**: Customize the dashboard as needed to display the most relevant information for your use case. -2. Access the Dashboard: - - Open a web browser and navigate to http://127.0.0.1:8050/ to view the dashboard locally. - - To access the dashboard on an external IP, ensure your network settings allow external connections and navigate to http://:8050/. +## System Requirements -## Accessing the Dashboard +- **Python**: The data collection script is written in Python and requires a Python environment to run. +- **SQLite**: The script uses SQLite for data storage, so SQLite must be installed and accessible. +- **LibreNMS API**: The script interacts with the LibreNMS API to fetch power usage data, so access to this API is required. -- Local Access: http://127.0.0.1:8050/ -- External Access: http://:8050/ +## Conclusion -Ensure that your firewall and router settings allow incoming connections on port 8050. +The Power Monitoring System provides a comprehensive solution for collecting and visualizing power usage data. By using the data collection script and dashboard together, users can efficiently monitor power consumption and make data-driven decisions.