fix: update documentation for Prometheus extractor and GreenDIGIT CIM messenger configuration

Author: jaimeib

doc/source/configuration.rst

@@ -283,22 +283,27 @@ To publish only energy records to logstash::
 
 Options defined here configure the Prometheus extractor for gathering energy
 consumption metrics. This extractor uses the ``prometheus-api-client`` library
-to query a Prometheus instance and calculate energy consumption from 
+to query a Prometheus instance and calculate energy consumption from
 instantaneous power samples. Available options:
 
 * ``prometheus_endpoint`` (default: ``http://localhost:9090``), Prometheus
   server endpoint URL.
-* ``prometheus_metric_name`` (default: ``prometheus_value``), Name of the 
+* ``prometheus_metric_name`` (default: ``prometheus_value``), Name of the
   Prometheus metric to query for energy consumption data.
-* ``prometheus_label_type_instance`` (default: ``scaph_process_power_microwatts``),
-  Value for the ``type_instance`` label used to filter metrics in Prometheus.
+* ``vm_uuid_label_name`` (default: ``uuid``), Name of the label in the
+  Prometheus metric that matches the VM UUID.
+* ``labels`` (default: ``["type_instance:scaph_process_power_microwatts"]``),
+  List of label filters expressed as ``key:value`` pairs used to filter the
+  Prometheus metric. The VM UUID label will be automatically added to the query.
 * ``prometheus_step_seconds`` (default: ``30``), Frequency between samples in
   the time series, in seconds. This is used to calculate energy from power samples.
-* ``prometheus_verify_ssl`` (default: ``true``), Whether to verify SSL 
+* ``prometheus_verify_ssl`` (default: ``true``), Whether to verify SSL
   certificates when connecting to Prometheus.
 
 The extractor calculates energy in Watt-hours (Wh) from microwatt power samples
-using the formula: ``sum_over_time(metric{labels}[range]) * (step_seconds/3600) / 1000000``.
+using the formula:
+
+``sum_over_time(metric{labels}[range]) * (step_seconds/3600) / 1000000``
 
 To use the Prometheus extractor, add ``prometheus`` to the ``extractor`` option
 in the main configuration. For more details, see :doc:`prometheus-extractor`.

doc/source/greendigit_cim_messenger.rst

@@ -7,63 +7,62 @@ energy consumption metrics in cASO.
 Overview
 --------
 
-The GreenDIGIT CIM messenger sends `EnergyRecord` objects to the GreenDIGIT
+The GreenDIGIT CIM messenger sends ``EnergyRecord`` objects to the GreenDIGIT
 Common Information Model (CIM) Service. The messenger supports authentication
 via bearer token and allows publishing energy consumption data from cASO extractors
 to SZTAKI CIM endpoints.
 
-Additionally, the messenger verifies SSL certificates and endpoint availability  
+Additionally, the messenger verifies SSL certificates and endpoint availability
 before publishing to ensure reliability in production environments.
 
 Configuration
 -------------
 
 To use the GreenDIGIT CIM messenger, add the following configuration to your
-`caso.conf` file:
+``caso.conf`` file:
 
-```ini
-[DEFAULT]
-# Add the messenger to your list of messengers
-messengers = greendigit_cim
+.. code-block:: ini
 
-[greendigit_cim]
-# Base URL of SZTAKI GreenDIGIT CIM Service.
-# Specific endpoints for authentication (/gd-cim-api/v1/token) and publishing (/gd-cim-api/v1/submit) 
-# will be constructed internally by the messenger.
-base_url = https://greendigit-cim.sztaki.hu
+   [DEFAULT]
+   # Add the messenger to your list of messengers
+   messengers = greendigit_cim
 
-# Credentials used to obtain the bearer token
-email = user@example.org
-password = secret-password
+   [greendigit_cim]
+   # Base URL of SZTAKI GreenDIGIT CIM Service.
+   # Specific endpoints for authentication (/gd-cim-api/v1/token) and publishing (/gd-cim-api/v1/submit)
+   # will be constructed internally by the messenger.
+   base_url = https://greendigit-cim.sztaki.hu
 
-# SSL verification (recommended for production)
-verify_ssl = true
+   # Credentials used to obtain the bearer token
+   email = user@example.org
+   password = secret-password
 
-[messenger_greendigit_cim]
-# Only energy records will be published to this messenger
-record_types = energy
-```
+   # SSL verification (recommended for production)
+   verify_ssl = true
+
+   [messenger_greendigit_cim]
+   # Only energy records will be published to this messenger
+   record_types = energy
 
 How it Works
 ------------
 
 The GreenDIGIT CIM messenger performs the following steps:
 
 1. **Verify Endpoints**: Checks that the authentication and publishing endpoints are reachable and that SSL certificates are valid.
-2. **Authenticate**: Uses the configured base URL and the credentials provided in caso.conf
-to obtain a bearer token from `/gd-cim-api/v1/token`.
-3. **Serialize Records**: Converts `EnergyRecord` objects to JSON using field mappings consistent with cASO standards.
-4. **Publish Records**: Sends the JSON payload to `/gd-cim-api/v1/submit` via HTTP POST with the bearer token in the Authorization header.
-5. **Logging:** Records the number of published records and HTTP response status.
+2. **Authenticate**: Uses the configured base URL and the credentials provided in ``caso.conf`` to obtain a bearer token from ``/gd-cim-api/v1/token``.
+3. **Serialize Records**: Converts ``EnergyRecord`` objects to JSON using field mappings consistent with cASO standards.
+4. **Publish Records**: Sends the JSON payload to ``/gd-cim-api/v1/submit`` via HTTP POST with the bearer token in the ``Authorization`` header.
+5. **Logging**: Records the number of published records and HTTP response status.
 
 Testing
 -------
 
 To test the messenger:
 
 1. Verify that the SZTAKI CIM endpoints are reachable from the host running cASO.
-2. EEnsure the credentials are correctly set in `caso.conf`.
-3. Run cASO in `--dry-run` mode to preview `EnergyRecord` objects without publishing.
+2. Ensure the credentials are correctly set in ``caso.conf``.
+3. Run cASO in ``--dry-run`` mode to preview ``EnergyRecord`` objects without publishing.
 4. Check logs for successful publication messages or errors.
 
 Troubleshooting
@@ -72,25 +71,25 @@ Troubleshooting
 **Authentication errors:**
 
 - Ensure credentials are correct.
-- Verify network connectivity to base URL.
-- Ensure the endpoint accepts GET requests.
+- Verify network connectivity to ``base_url``.
+- Ensure the authentication endpoint is reachable.
 
 **Publishing errors:**
 
 - Check that the publish endpoint is reachable.
-- Validate that JSON serialization of `EnergyRecord` is correct.
+- Validate that JSON serialization of ``EnergyRecord`` is correct.
 - Review HTTP status codes in logs for hints.
 
 **No records published:**
 
-- Ensure extractors have generated `EnergyRecord` objects.
-- Confirm that the messenger is listed in `messengers` in `[DEFAULT]` section.
+- Ensure extractors have generated ``EnergyRecord`` objects.
+- Confirm that the messenger is listed in ``messengers`` in the ``[DEFAULT]`` section.
 
 Technical Details
 -----------------
 
 - Uses bearer token authentication.
-- Records are serialized using `model_dump_json` with aliases and excluding `None` values.
-- HTTP POST to `/gd-cim-api/submit` includes a JSON array of `EnergyRecord` objects.
+- Records are serialized using ``model_dump_json`` with aliases and excluding ``None`` values.
+- HTTP POST to ``/gd-cim-api/v1/submit`` includes a JSON array of ``EnergyRecord`` objects.
 - Verifies SSL and endpoint availability before publishing.
 - Logs the number of records sent and HTTP response status.