Metric for expected camera position

This patch adds a new metric for the expected camera position. This
allows users to compare the expected and actual positions of a camera
and visualize those or use the information for alerting.

This fixes #82

camera-control.yml

@@ -21,8 +21,10 @@ calendar:
   # Default: 604800 (7 days)
   cutoff: 604800
 
-# The frequency in which the cameras position should be updated in seconds
-# Default: 60
+# The frequency in which to re-send the command to move the cameras to the
+# desired position in seconds. This ensure the camera position is corrected
+# eventually, even if there was an unexpected error.
+# Default: 300
 camera_update_frequency: 300
 
 # Camera Configuration

occameracontrol/camera.py

@@ -25,7 +25,8 @@
 from typing import Optional
 
 from occameracontrol.agent import Agent
-from occameracontrol.metrics import register_camera_move
+from occameracontrol.metrics import register_camera_move, \
+        register_camera_expectation
 
 
 logger = logging.getLogger(__name__)
@@ -77,6 +78,7 @@ def __str__(self) -> str:
     def move_to_preset(self, preset: int):
         '''Move the PTZ camera to the specified preset position
         '''
+        register_camera_expectation(self.url, preset)
         if self.type == CameraType.panasonic:
             params = {'cmd': f'#R{preset - 1:02}', 'res': 1}
             url = f'{self.url}/cgi-bin/aw_ptz'

occameracontrol/metrics.py

@@ -25,18 +25,26 @@
 
 logger = logging.getLogger(__name__)
 
-request_errors = Counter('request_errors',
-                         'Number of errors related to HTTP requests',
-                         ('ressource', 'type'))
-agent_calendar_update_total = Gauge('agent_calendar_update_total',
-                                    'Nuber of calendar update',
-                                    ('agent',))
-agent_calendar_update_time = Gauge('agent_calendar_update_time',
-                                   'Time of the last calendar update',
-                                   ('agent',))
-camera_position = Gauge('camera_position',
-                        'Last position (preset number) a camera moved to',
-                        ('camera',))
+request_errors = Counter(
+        'request_errors',
+        'Number of errors related to HTTP requests',
+        ('ressource', 'type'))
+agent_calendar_update_total = Gauge(
+        'agent_calendar_update_total',
+        'Nuber of calendar update',
+        ('agent',))
+agent_calendar_update_time = Gauge(
+        'agent_calendar_update_time',
+        'Time of the last calendar update',
+        ('agent',))
+camera_position = Gauge(
+        'camera_position',
+        'Last position (preset number) a camera moved to',
+        ('camera',))
+camera_position_expected = Gauge(
+        'camera_position_expected',
+        'The position (preset number) a camera should be in',
+        ('camera',))
 
 
 class RequestErrorHandler():
@@ -93,14 +101,24 @@ def register_calendar_update(agent_id: str):
 
 def register_camera_move(camera: str, position: int):
     '''Update metrics for when a camera move has happened. This ensures the
-    position the camera is available as part of the metrics.
+    position of the camera is available as part of the metrics.
 
     :param camera: Camera identifier
     :param position: New camera position
     '''
     camera_position.labels(camera).set(position)
 
 
+def register_camera_expectation(camera: str, position: int):
+    '''Update metrics for when a camera is supposed to move. This ensures the
+    position the camera is expected in is available as part of the metrics.
+
+    :param camera: Camera identifier
+    :param position: New camera position
+    '''
+    camera_position_expected.labels(camera).set(position)
+
+
 def start_metrics_exporter():
     '''Start the web server for the metrics exporter endpoint if it is enabled
     in the configuration.