feat(metrics): More metrics and docs (#4)

* feat(metrics): Add user metrics and update handling for /me endpoint data

- Introduced new gauges for user information, activity status, password presence, and email preferences.
- Implemented `update_user_metrics` function to process data from the /me endpoint and update corresponding metrics.
- Enhanced metrics collection logic to handle missing workspace IDs gracefully.

* feat(metrics): Enhance project and client metrics collection

- Added new gauges for individual project and client information, including attributes such as project name, client ID, and status flags.
- Updated `update_aggregate_metrics` function to clear previous metrics and handle fetching of clients and projects more robustly.
- Improved error handling with informative print statements for failed API calls when fetching clients and projects.

* feat(metrics): Add new performance metrics for time entries

- Introduced gauges for average duration, billable ratio, distinct days with entries, and untagged entries metrics.
- Updated the `update_time_entries_metrics` function to aggregate and set new performance metrics based on workspace data.
- Enhanced the exporter to clear and handle new metrics during collection.
- Modified the Grafana dashboard to reflect changes in titles and layout for better clarity and organization.

* feat(grafana): Add Grafana service and configuration for metrics visualization

- Introduced a new Grafana service in the Docker Compose setup, configured to run on port 3000.
- Added datasource and dashboard configuration files for Prometheus integration.
- Updated README to include Grafana access instructions and service details.
- Modified existing Grafana dashboard JSON expressions for proper syntax.

* fix(grafana): Correct syntax in dashboard JSON expressions

- Updated Prometheus query expressions in the Grafana dashboard JSON to use correct string formatting, replacing escaped quotes with standard quotes for improved readability and functionality.

* feat(grafana): Update dashboard JSON for enhanced metrics visualization

- Set dashboard ID to 1 and updated plugin version to 11.6.0.
- Added new configuration options for percent change color mode, thresholds, and layout settings.
- Enhanced panel configurations with mappings and thresholds for better data representation.
- Adjusted the structure of the dashboard to include new panels for API error rates and GC metrics.
- Updated schema version to 41 and improved overall organization for clarity.

* feat(grafana): Revise dashboard JSON and enhance metrics integration

- Adjusted grid positions and widths for several panels to optimize layout.
- Introduced a new panel for "Timer Status History" with Prometheus data source.
- Updated existing panels to reflect new metrics, including "Total Clients" and "Total Tags."
- Modified the "Avg Entry Duration (24h)" and "Billable Ratio (24h)" panels to use updated Prometheus queries.
- Enhanced the overall organization of the dashboard for improved clarity and usability.
- Updated schema version to 7.

* feat(docs): Enhance README and Grafana dashboard integration

- Added images for Toggl and Grafana to the README for better visualization.
- Included a pre-configured Grafana dashboard in `grafana/dashboard.json` for improved metrics visualization.
- Updated Grafana dashboard queries to support dynamic timeframe selection for metrics.
- Modified exporter to handle multiple lookback periods for time entries, enhancing flexibility in metrics collection.
- Updated tests to validate new functionality for handling multiple lookback hours.

* refactor(metrics): Simplify time entry metrics processing and enhance readability

- Refactored the `update_time_entries_metrics` function to utilize helper functions for better organization and clarity.
- Introduced new helper functions for fetching workspace mappings, processing entry aggregates, and setting metrics.
- Improved error handling and logging for fetching time entries and workspace data.
- Updated type hints for better code clarity and maintainability.
- Enhanced the handling of metrics aggregation and clearing for performance metrics.

Author: johnnyhuy

README.md

@@ -1,3 +1,5 @@
+![](./docs/images/toggl.png)
+
 # Prometheus Toggl Track Exporter
 
 Extract Toggl Track API metrics via Prometheus with this exporter.
@@ -16,6 +18,9 @@ Extract Toggl Track API metrics via Prometheus with this exporter.
 - Includes Taskfile for command orchestration
 - Manages tool versions with asdf
 - Uses Ruff for lightning-fast Python linting and formatting
+- Includes a pre-configured Grafana dashboard (`grafana/dashboard.json`) for visualizing metrics
+
+![](./docs/images/grafana.png)
 
 ## Metrics
 
@@ -58,6 +63,8 @@ docker run -p 9090:9090 -e TOGGL_API_TOKEN=your_api_token ghcr.io/echohello-dev/
 
 ### Using Docker Compose
 
+The `compose.yaml` file sets up the Toggl Track exporter, a Prometheus instance, and a Grafana instance for visualization.
+
 1.  Copy the example environment file and edit it with your API token:
 
     ```bash
@@ -68,10 +75,15 @@ docker run -p 9090:9090 -e TOGGL_API_TOKEN=your_api_token ghcr.io/echohello-dev/
 2.  Then start the services:
 
     ```bash
-    docker-compose up -d
+    docker compose up -d # Or use 'task docker-compose-up'
     ```
 
-This will start both the Toggl Track exporter and a Prometheus instance configured to scrape metrics from the exporter.
+This will start:
+- The **Toggl Track exporter** (port `9090`)
+- **Prometheus** (port `9091`), pre-configured to scrape the exporter.
+- **Grafana** (port `3000`), pre-configured with Prometheus as a data source and a default Toggl Track dashboard. Credentials are `admin / admin`.
+
+Access Grafana at `http://localhost:3000` to view your metrics.
 
 ### Using Poetry
 

Taskfile.yml

@@ -62,7 +62,7 @@ tasks:
   docker-compose-up:
     desc: Run using Docker Compose
     cmds:
-      - docker compose up -d
+      - docker compose up --build -d
 
   docker-compose-down:
     desc: Stop docker-compose services

compose.yaml

@@ -31,9 +31,26 @@ services:
     networks:
       - monitoring
 
+  grafana:
+    image: grafana/grafana:latest
+    container_name: grafana
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./grafana/datasource.yml:/etc/grafana/provisioning/datasources/datasource.yml
+      - ./grafana/dashboards.yml:/etc/grafana/provisioning/dashboards/dashboards.yml
+      - ./grafana/dashboard.json:/var/lib/grafana/dashboards/dashboard.json
+      - grafana_data:/var/lib/grafana
+    networks:
+      - monitoring
+    depends_on:
+      - prometheus
+
 networks:
   monitoring:
     driver: bridge
 
 volumes:
   prometheus_data: {}
+  grafana_data: {}