Metrics Plugin + Datadog Example Metrics Plugin (#302)

Author: savathoon

api/plugins/conditional_access.py

@@ -12,7 +12,7 @@
 hookspec = pluggy.HookspecMarker(conditional_access_plugin_name)
 hookimpl = pluggy.HookimplMarker(conditional_access_plugin_name)
 
-_cached_conditional_access_hook = None
+_cached_conditional_access_hook: pluggy.HookRelay | None = None
 
 logger = logging.getLogger(__name__)
 

api/plugins/metrics_reporter.py

@@ -0,0 +1,119 @@
+import logging
+import sys
+from typing import ContextManager, Dict, List, Optional
+
+import pluggy
+
+metrics_reporter_plugin_name = "access_metrics_reporter"
+hookspec = pluggy.HookspecMarker(metrics_reporter_plugin_name)
+hookimpl = pluggy.HookimplMarker(metrics_reporter_plugin_name)
+
+_cached_metrics_reporter_hook: Optional[pluggy.HookRelay] = None
+
+logger = logging.getLogger(__name__)
+
+
+class MetricsReporterPluginSpec:
+    @hookspec
+    def record_counter(
+        self,
+        metric_name: str,
+        value: float = 1.0,
+        tags: Optional[Dict[str, str]] = None,
+        monotonic: bool = True,
+    ) -> None:
+        """
+        Record a counter metric value.
+
+        Args:
+            metric_name: The metric name
+            value: The value to add (default 1.0)
+            tags: Optional tags
+            monotonic: If True, counter only increases. If False, can decrease.
+        """
+
+    @hookspec
+    def record_gauge(
+        self,
+        metric_name: str,
+        value: float,
+        tags: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """Record a gauge metric value (snapshot/current value)."""
+
+    @hookspec
+    def record_histogram(
+        self,
+        metric_name: str,
+        value: float,
+        tags: Optional[Dict[str, str]] = None,
+        buckets: Optional[List[float]] = None,
+    ) -> None:
+        """
+        Record a value in a histogram/distribution.
+
+        Args:
+            metric_name: The metric name
+            value: The value to record
+            tags: Optional tags
+            buckets: Optional bucket boundaries for the histogram
+        """
+
+    @hookspec
+    def record_summary(
+        self,
+        metric_name: str,
+        value: float,
+        tags: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """
+        Record a value for summary statistics (percentiles, min, max, etc).
+        This is similar to histogram but may be implemented differently by backends.
+        """
+
+    @hookspec
+    def batch_metrics(self) -> ContextManager[None]:
+        """
+        Context manager for batching multiple metric operations.
+
+        Returns a context manager that batches metric operations for efficiency.
+        Particularly useful for HTTP-based backends to reduce network calls.
+
+        Example:
+            with metrics.batch_metrics():
+                metrics.record_counter("requests", 1)
+                metrics.record_gauge("queue_size", 42)
+                metrics.record_histogram("response_time", 0.123)
+            # All metrics sent in one batch here
+        """
+        return NotImplemented
+
+    @hookspec
+    def set_global_tags(
+        self,
+        tags: Dict[str, str],
+    ) -> None:
+        """Set global tags to be included with all metrics."""
+
+    @hookspec
+    def flush(self) -> None:
+        """Force flush any buffered metrics to the backend."""
+
+
+def get_metrics_reporter_hook() -> pluggy.HookRelay:
+    global _cached_metrics_reporter_hook
+
+    if _cached_metrics_reporter_hook is not None:
+        return _cached_metrics_reporter_hook
+
+    pm = pluggy.PluginManager(metrics_reporter_plugin_name)
+    pm.add_hookspecs(MetricsReporterPluginSpec)
+
+    # Register the hook wrappers
+    pm.register(sys.modules[__name__])
+
+    count = pm.load_setuptools_entrypoints(metrics_reporter_plugin_name)
+    logger.debug(f"Count of loaded metrics reporter plugins: {count}")
+    _cached_metrics_reporter_hook = pm.hook
+
+    return _cached_metrics_reporter_hook

api/plugins/notifications.py

@@ -11,7 +11,7 @@
 hookspec = pluggy.HookspecMarker(notification_plugin_name)
 hookimpl = pluggy.HookimplMarker(notification_plugin_name)
 
-_cached_notification_hook = None
+_cached_notification_hook: pluggy.HookRelay | None = None
 
 logger = logging.getLogger(__name__)
 

examples/plugins/datadog_metrics_reporter/README.md

@@ -0,0 +1,71 @@
+# Discord Access Datadog Metrics Plugin
+
+This plugin integrates Discord access metrics with Datadog, allowing users to track and monitor access request patterns, approval rates, and system health metrics.
+
+## Installation
+
+Update the Dockerfile used to build the App container includes the following section for installing the metrics plugin before starting gunicorn:
+
+```dockerfile
+# Add the specific plugins and install metrics
+WORKDIR /app/plugins
+ADD ./examples/plugins/metrics_reporter ./metrics_reporter
+RUN pip install -r ./metrics_reporter/requirements.txt && pip install ./metrics_reporter
+
+# Reset working directory
+WORKDIR /app
+
+ENV FLASK_ENV production
+ENV FLASK_APP api.app:create_app
+ENV SENTRY_RELEASE $SENTRY_RELEASE
+
+EXPOSE 3000
+
+CMD ["gunicorn", "-w", "4", "-t", "600", "-b", ":3000", "--access-logfile", "-", "api.wsgi:app"]
+```
+
+## Build the Docker image, run and test
+
+You may use the original Discord Access container build processes from the primary README.md:
+```bash
+docker compose up --build
+```
+
+Verify metrics collection is working as designed.
+
+## Configuration
+
+The following environment variables need to be configured for the Datadog metrics plugin to work properly:
+
+### Required Environment Variables
+
+- `FLASK_ENV`: Application environment (e.g., `production`, `staging`, `development`)
+  - Used to determine the environment tag for metrics
+  - Maps to: `production` → `prd`, `staging` → `stg`, other → `dev`
+
+### Optional Environment Variables
+
+- `STATSD_HOST_IP`: IP address of the StatsD/DogStatsD server
+  - If not set, falls back to `DD_AGENT_HOST`
+  - Default: `127.0.0.1`
+
+- `DD_AGENT_HOST`: Datadog Agent host address
+  - Used when `STATSD_HOST_IP` is not provided
+  - Default: `127.0.0.1`
+
+- `DD_DOGSTATSD_PORT`: Port for DogStatsD communication
+  - Default: `8125`
+
+## Development
+
+To contribute to the development of this plugin, please follow the standard Git workflow:
+
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix.
+3. Make your changes and commit them.
+4. Push your branch and create a pull request.
+
+## License
+
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
+