## PRD: Improve AIVA Observability and Debugging

This PRD focuses on enhancing AIVA's observability by adding logging to track frequency scaling decisions and hysteresis events. This will aid in debugging and understanding AIVA's behavior in different environments.

### GPM-050: Add Basic Frequency Scaling Decision Logging
**Goal:** Log when AIVA decides to scale the frequency up or down.
**Acceptance Criteria:**
- When `adjust_frequency` in `aiva/frequency_governor.py` decides to increase frequency, a log message is emitted indicating the decision and the target frequency.
- When `adjust_frequency` in `aiva/frequency_governor.py` decides to decrease frequency, a log message is emitted indicating the decision and the target frequency.
- Log messages should include a timestamp and a clear indication of the frequency change direction (up/down).
**Files:** `aiva/frequency_governor.py`
**Spawns:** Add more details to the frequency scaling log messages, including the reason for the scaling decision.

### GPM-051: Log Hysteresis Events
**Goal:** Log when the hysteresis mechanism prevents a frequency scaling decision.
**Acceptance Criteria:**
- When `adjust_frequency` in `aiva/frequency_governor.py` detects that scaling up would violate the `UP_THRESHOLD` hysteresis, a log message is emitted.
- When `adjust_frequency` in `aiva/frequency_governor.py` detects that scaling down would violate the `DOWN_THRESHOLD` hysteresis, a log message is emitted.
- Log messages should include a timestamp and the values of the current frequency, `UP_THRESHOLD`, and `DOWN_THRESHOLD`.
**Files:** `aiva/frequency_governor.py`
**Spawns:** Provide configurable log levels for different types of events.

### GPM-052: Include CPU Utilization in Frequency Scaling Logs
**Goal:** Add CPU utilization information to frequency scaling and hysteresis log messages.
**Acceptance Criteria:**
- Log messages related to frequency scaling decisions (up/down) include the current CPU utilization percentage.
- Log messages related to hysteresis events include the current CPU utilization percentage.
- The CPU utilization percentage is calculated and logged accurately.
**Files:** `aiva/frequency_governor.py`
**Spawns:** Add memory utilization information to the logs.

### GPM-053: Implement a Dedicated Logger for Frequency Scaling
**Goal:**  Create a dedicated logger instance specifically for frequency scaling related events.
**Acceptance Criteria:**
- A new logger named 'aiva.frequency_scaling' is created and used for all frequency scaling related log messages.
- The existing log messages are updated to use the new logger.
- The logger is configured with a default log level (e.g., INFO).
**Files:** `aiva/frequency_governor.py`
**Spawns:** Allow configuration of the frequency scaling logger's log level via the configuration file.

### GPM-054: Add Unit Tests for Frequency Scaling Logging
**Goal:** Create unit tests to verify that frequency scaling events are logged correctly.
**Acceptance Criteria:**
- Unit tests are created to verify that frequency up scaling events are logged with the correct information.
- Unit tests are created to verify that frequency down scaling events are logged with the correct information.
- Unit tests are created to verify that hysteresis events are logged with the correct information.
- The tests cover different scenarios (e.g., successful scaling, hysteresis preventing scaling).
**Files:** `tests/test_frequency_governor.py` (or similar test file)
**Spawns:** Add integration tests to verify the logging behavior in a simulated environment.

### GPM-055: Refactor `adjust_frequency` for Testability
**Goal:** Refactor the `adjust_frequency` function to improve its testability by extracting side effects (logging, frequency setting) into separate, mockable functions.
**Acceptance Criteria:**
- The core logic of `adjust_frequency` remains the same, but side effects are moved into separate functions.
- The new functions are easily mockable during testing.
- Unit tests for the core logic of `adjust_frequency` can be written without relying on external dependencies (e.g., the system's frequency scaling tools).
**Files:** `aiva/frequency_governor.py`
**Spawns:** Introduce dependency injection for system utilities (e.g., frequency setting) to further improve testability.
