Write more documentation on the metrics dashboard

This commit adds more information to the README file for the system
monitoring dashboards with information about which dashboards are
included and how they can be used.

Author: Daniel Falk

README.md

@@ -1,9 +1,13 @@
 # FixedIT Data Agent Examples
 
-This repository provides resources for the FixedIT Data Agent across different levels of customization:
+This repository provides resources for the [FixedIT Data Agent ACAP](https://fixedit.ai/products-data-agent/) for the Axis network cameras and other Axis devices.
 
 **📊 Server-side dashboards** - The [dashboard-deployments](./dashboard-deployments) directory contains visualization dashboards that work with the FixedIT Data Agent. Some work directly with the bundled configurations (just spin them up and start visualizing), while others can be used as-is or customized for your needs. Advanced users often combine edge device customization with dashboard modifications to visualize new data types.
 
+The dashboard stack in the image below is the system monitoring example for the bundled configuration in the FixedIT Data Agent, for more details see the [README](./dashboard-deployments/system-monitoring-influxdb2-flux-grafana/README.md) in the dashboard-deployments directory.
+
+![Grafana Dashboard Overview](./dashboard-deployments/system-monitoring-influxdb2-flux-grafana/.images/laptop-with-grafana-for-monitoring.png)
+
 **🛠️ Edge device customization** - Project implementation examples that show how to extend and customize the FixedIT Data Agent by uploading custom configuration files and scripts. This makes it easy to create tailored edge applications for Axis devices without starting from scratch using the AXIS ACAP SDK.
 
 [Comming soon...]

dashboard-deployments/system-monitoring-influxdb2-flux-grafana/.images/dashboard-device-details.png

@@ -1,40 +1,189 @@
-# InfluxDB and Grafana stack
+# InfluxDB and Grafana Monitoring Stack
 
-This directory contains a package with the files needed to spin up a stack with InfluxDB and Grafana where Grafana comes pre-populated with multiple dashboards useful for monitoring system metrics from the devices and the propagation of configuration parameters.
+This directory contains a complete system monitoring stack designed to work with the **FixedIT Data Agent** running on Axis devices. The stack includes InfluxDB for time-series data storage and Grafana with pre-built dashboards for visualizing system metrics and device health from your Axis device fleet.
 
-## Running the stack
+![Grafana Monitoring Overview](.images/laptop-with-grafana-for-monitoring.png)
 
-This stack (defined in `docker-compose.yml`) will run:
+## What This Stack Provides
 
-- InfluxDB storing time series data (system metrics and configuration parameters)
-- Grafana to create dashboards
+This monitoring solution gives you comprehensive visibility into your Axis devices through three specialized dashboards:
 
-To run it:
+- **System Overview**: Fleet-wide metrics including connected devices, recently lost devices, and performance outliers
+- **Overview of Devices**: Individual device information with detailed metrics, IP addresses, and system health
+- **Device Details**: Deep-dive into specific device performance including CPU, RAM, network, and geo-location data
 
-1. Run `docker compose up -d`
-2. Then go to [http://127.0.0.1:8086](http://127.0.0.1:8086) and log in with username `test` and password `testtest` (from the `docker-compose.yml` file)
-3. Open grafana UI on [http://127.0.0.1:3000](http://127.0.0.1:3000) and log in with username `admin` and password `test` (from the `docker-compose.yml` file).
+The stack is designed for DevOps and IT professionals who want to deploy monitoring infrastructure for devices running the FixedIT Data Agent, without needing to create dashboards from scratch.
 
-### Example of more secure setup
+## The Database and Query Language
 
-The supplied `docker-compose.yml` file is for development usage with hardcoded ports and credentials for simplicity. For production, you should handle keys in a more secure way. One example of a better setup is to use the `docker-compose.prod.yml` override file.
+This monitoring stack uses **InfluxDB 2** with the **Flux query language** for all data queries and dashboard visualizations.
 
-**Helper Script Available**: There's a helper script to generate the `env.sh` file with secure random values for all environment variables required by the production docker-compose setup (`docker-compose.prod.yml`), see [helper_scripts/README.md](./helper_scripts/README.md) for more details.
+**Important Note**: InfluxDB 3 has moved away from Flux to SQL-based queries. However, we chose to use InfluxDB 2 with Flux for this stack because:
 
-```bash
-# Use the helper script to generate secure environment variables
-./helper_scripts/generate-env.sh
-source env.sh
+- InfluxDB 2 with Flux is still the most widely adopted version in the community
+- Most existing time-series monitoring setups use Flux
+- The Flux query language is well-suited for time-series data analysis
 
-docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
-```
+If you're already using InfluxDB 3 in your environment, you would need to adapt the dashboard queries from Flux to SQL syntax.
 
-**Note**: The production setup uses configurable ports to allow running multiple instances on the same server. The development setup uses hardcoded ports (8086 for InfluxDB, 3000 for Grafana) for simplicity. This can be changed by editing the `env.sh` file after generation with the `helper_scripts/generate-env.sh` script or by manually setting the environment variables before launching the stack.
+## Prerequisites
 
-## Grafana
+- Docker and Docker Compose installed on your server
+- Network connectivity between your Axis devices (running FixedIT Data Agent) and the server hosting this stack
+- Basic familiarity with InfluxDB and Grafana (helpful but not required)
 
-Open the grafana UI on [http://127.0.0.1:3000](http://127.0.0.1:3000), login with user `admin` and password `test` (specified in the [./docker-compose.yml](./docker-compose.yml) file). Click on "Dashboards" and you should see the pre-populated dashboards in the "Cameras" folder.
+## Quick Start
 
-## Helper scripts
+Choose one of the deployment options below:
+
+### Option A: Simple Demo (Recommended for Testing)
+
+This is the quickest way to test the monitoring stack on your local machine. Everything is pre-configured with hardcoded values.
+
+1. **Start the stack:**
+
+   ```bash
+   docker compose up -d
+   ```
+
+2. **Verify it's running:**
+   - **InfluxDB**: [http://127.0.0.1:8086](http://127.0.0.1:8086) - login with `test` / `testtest`
+   - **Grafana**: [http://127.0.0.1:3000](http://127.0.0.1:3000) - login with `admin` / `test`
+   - Dashboards will be in the "Cameras" folder
+
+⚠️ **Note**: This uses hardcoded credentials and ports. Only use for local testing.
+
+### Option B: Production-Like Example
+
+This provides a more secure example with environment variables and additional monitoring features. It's still an **example to build upon**, not a complete production solution.
+
+1. **Generate secure environment variables:**
+
+   ```bash
+   ./helper_scripts/generate-env.sh
+   source env.sh
+   ```
+
+2. **Start the enhanced stack:**
+   ```bash
+   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+   ```
+
+This example includes:
+
+- Environment variables for all sensitive data
+- Configurable ports for multiple instances
+- Health checks for both services (needs some more work)
+
+⚠️ **Note**: This is still an example configuration. For actual production use, you'll need additional security hardening, backup strategies, and monitoring.
+
+### Port Configuration
+
+The production-like setup uses configurable ports to allow running multiple instances on the same server. The demo setup uses hardcoded ports (8086 for InfluxDB, 3000 for Grafana) for simplicity. You can change the production ports by editing the `env.sh` file after generation with the `helper_scripts/generate-env.sh` script or by manually setting the environment variables before launching the stack.
+
+### Deployment Organization
+
+The intended deployment pattern is to use **separate folders for different deployments**:
+
+- Copy the content of this directory to separate folders (e.g., `site-1-dashboard/`, `site-2-dashboard/`, etc.)
+- Each folder contains the same code and has its own `env.sh` file with unique credentials and ports
+- Data volumes mount to consistent folder names within each deployment directory
+- This makes it easy to see which code version was used for each deployment and keeps credentials isolated.
+
+## Configure Your FixedIT Data Agent
+
+After deploying the stack, configure your Axis devices to send data to it:
+
+**For Simple Demo (Option A):**
+
+- **InfluxDBHost**: `http://YOUR_SERVER_IP:8086`
+- **InfluxDBToken**: `KLoG_Z0NsDIbVzS7zVn_VwhgxUgvwaGWE1wwO9SsGfNEeMaopLMsAA2aAGbCshpetVdu86Ig3-WTKugv6Srg6w==` (demo admin token)
+- **InfluxDBOrganization**: `Whisperer`
+- **InfluxDBBucket**: `Cameras`
+
+_Note: The demo uses the admin token for simplicity. For any real testing beyond local evaluation, create dedicated tokens as described below._
+
+**For Production-Like Example (Option B):**
+
+- **InfluxDBHost**: `http://YOUR_SERVER_IP:${INFLUXDB_PORT}` (check your env.sh for port)
+- **InfluxDBToken**: Create a dedicated token in InfluxDB (see security note below)
+- **InfluxDBOrganization**: `Whisperer` (hardcoded in docker-compose.yml)
+- **InfluxDBBucket**: `Cameras` (hardcoded in docker-compose.yml)
+
+⚠️ **Security Best Practice**: Do NOT use `${INFLUXDB_ADMIN_TOKEN}` for your cameras. Instead, log into InfluxDB and create dedicated tokens with write-only permissions to the `Cameras` bucket. Ideally create one token per camera, or at minimum a shared token with restricted permissions.
+
+**To create a camera token in InfluxDB:**
+
+1. Log into InfluxDB UI with admin credentials
+2. Go to "Data" → "API Tokens" → "Generate API Token"
+3. Choose "Custom API Token"
+4. Grant only "Write" permission to the `Cameras` bucket
+5. Use this token for your FixedIT Data Agent configuration
+
+**⚠️ Grafana Security Note**: Grafana also uses the admin token by default (configured via environment variables in docker-compose files). For better security, you should:
+
+1. Create a separate token for Grafana with only "Read" permission to the `Cameras` bucket
+2. Log into Grafana → Configuration → Data Sources → InfluxDB
+3. Update the token field with your new read-only token
+4. Test the connection to ensure it works
+
+**Summary of recommended tokens for secure setup:**
+
+- **Admin token**: Keep for InfluxDB administration only
+- **Camera tokens**: Write-only access to `Cameras` bucket (one per camera ideally)
+- **Grafana token**: Read-only access to `Cameras` bucket
+
+Once configured, metrics will appear in the Grafana dashboards within a few minutes.
+
+## Grafana Dashboards
+
+Open the Grafana UI to access the pre-built dashboards. The URL and credentials depend on your deployment option:
+
+- **Option A (Simple Demo)**: [http://127.0.0.1:3000](http://127.0.0.1:3000) - login with `admin` / `test`
+- **Option B (Production-Like)**: Check your `env.sh` file for the port and admin password
+
+Click on "Dashboards" and you'll find the monitoring dashboards in the "Cameras" folder.
+
+### Accessing the Dashboards
+
+After logging into Grafana, navigate to the dashboards by clicking on the Grafana icon and selecting "Dashboards":
+
+![Dashboards tab in Grafana](.images/dashboards-tab.png)
+
+The dashboards are organized in a "Cameras" folder for easy organization:
+
+![Dashboard folder containing camera dashboards](.images/dashboard-folder-cameras.png)
+
+### Pre-built Dashboard Overview
+
+This stack includes three comprehensive dashboards designed specifically for monitoring Axis devices running the FixedIT Data Agent:
+
+#### 1. System Overview Dashboard
+
+Provides fleet-wide visibility including connected device counts, recently lost devices, and performance outliers. This dashboard is designed to give you a high-level view of your entire device ecosystem without overwhelming detail on individual devices.
+
+![System Overview Dashboard](.images/dashboard-system-overview.png)
+
+#### 2. Overview of Devices Dashboard
+
+Shows detailed information for all connected devices including last report times, AXIS OS versions, IP addresses, and individual device performance metrics. Perfect for monitoring the health and status of your device fleet.
+
+![Overview of Devices Dashboard](.images/dashboard-overview-of-devices.png)
+
+#### 3. Device Details Dashboard
+
+Provides deep-dive analytics for individual devices, including detailed system metrics, geographic tagging information, and network performance data. Access this dashboard by clicking on any device identifier from the other dashboards.
+
+![Device Details Dashboard](.images/dashboard-device-details.png)
+
+### Integration with FixedIT Data Agent
+
+These dashboards are designed to work seamlessly with the default configuration of the FixedIT Data Agent. The agent automatically collects and sends system metrics to InfluxDB, which are then visualized through these Grafana dashboards. No additional configuration is needed beyond setting up the InfluxDB connection details in your FixedIT Data Agent settings.
+
+## Known Issues and Limitations
+
+**A note on efficiency**: Some of the dashboard visualizations are rather compute-intensive and may perform slowly when used with many cameras, a large amount of data or insufficient server resources. We will continue to optimize the dashboards and the data model to improve performance.
+
+## Helper Scripts
 
 The directory [helper_scripts](./helper_scripts/) contains scripts that can assist with deployment, see the [README](./helper_scripts/README.md) for more details.

dashboard-deployments/system-monitoring-influxdb2-flux-grafana/.images/dashboard-folder-cameras.png

@@ -29,12 +29,3 @@ This will create an `env.sh` file in the project root. To use it:
 source env.sh
 docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
 ```
-
-## Deployment Organization
-
-The intended deployment pattern is to use **separate folders for different deployments**:
-
-- Copy the content of this directory to separate folders (e.g., `site-1-dashboard/`, `site-2-dashboard/`, etc.)
-- Each folder contains the same code and has its own `env.sh` file with unique credentials and ports
-- Data volumes mount to consistent folder names within each deployment directory
-- This makes it easy to see which code version was used for each deployment and keeps credentials isolated.