Feature Request: Add Prometheus Metrics Export Support

[ahpooch]

Feature Request: Add Prometheus Metrics Export Support

Summary

Add Prometheus metrics export capability to py-kms server to enable better monitoring, observability, and deeper understanding of KMS activation protocol behavior during testing and learning.

Currently, py-kms Docker containers do not support exporting metrics in Prometheus format, which limits visibility into how the KMS activation protocol works. While py-kms already has:

• A web UI with basic statistics (client counts, activation requests)
• SQLite database tracking client activation history
• Health check endpoints (/readyz, /livez)

There is no standardized way to:

• Monitor KMS service behavior in real-time during testing
• Analyze activation patterns and trends over time
• Visualize protocol interactions for learning purposes
• Integrate with standard observability tools (Prometheus, Grafana) for lab environments
• Create dashboards showing how different Windows/Office versions interact with KMS

Proposed Solution

Metrics support will be added ONLY to the python3 Docker image (not minimal), since:

• The python3 image already has Flask + Gunicorn for WebUI
• SQLite database provides historical data source
• The minimal image is designed to be lightweight and metrics would add unnecessary dependencies

Endpoint /metrics should be add to the existing Flask WebUI application (pykms_WebUI.py), served by the same Gunicorn process on port 8080.
Official prometheus_client Python library should be used.

Some considirations:

• Metrics should be served on the same port as WebUI (8080) - they will be a part of the same Flask application
• The metrics path is fixed to /metrics (Prometheus standard convention)
• No separate port configuration needed - metrics reuse the existing WebUI infrastructure
• If WEBUI=0, metrics are not available (minimal image doesn't include Flask)

Example usage:

environment:
  WEBUI: 1      # Enable WebUI (required for metrics)
  METRICS: 1    # Enable /metrics endpoint (defaults to 1 if WEBUI=1)

Metrics will be available at: http://py-kms-host:8080/metrics

Multi-Process Considerations

Since Gunicorn runs multiple worker processes, prometheus_client.multiprocess mode should be used:

from prometheus_client import CollectorRegistry, multiprocess, generate_latest

registry = CollectorRegistry()
multiprocess.MultiProcessCollector(registry)

Backward Compatibility

• Metrics endpoint is optional and controlled by METRICS environment variable
• No breaking changes to existing API or functionality
• Existing WebUI routes remain unchanged
• Works seamlessly with WEBUI=1 configuration
• Does not affect minimal image (where metrics not available)

Useful Resources

• Prometheus Python Client
• Prometheus Best Practices - Naming
• Prometheus Metric Types
• Multiprocess Mode with Gunicorn