feat: Generate metrics documentation

Author: khvn26

settings/dev.py

@@ -8,6 +8,14 @@
 
 env = Env()
 
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": ["templates"],
+        "APP_DIRS": True,
+    },
+]
+
 # Settings expected by `mypy_django_plugin`
 AWS_SES_REGION_ENDPOINT: str
 SEGMENT_RULES_CONDITIONS_LIMIT: int
@@ -48,7 +56,8 @@
 TASK_DELETE_RETENTION_DAYS = 15
 TASK_DELETE_RUN_EVERY = timedelta(days=1)
 TASK_DELETE_RUN_TIME = time(5, 0, 0)
-TASK_PROCESSOR_MODE = False
+TASK_PROCESSOR_MODE = env.bool("RUN_BY_PROCESSOR", default=False)
+DOCGEN_MODE = env.bool("DOCGEN_MODE", default=False)
 TASK_RUN_METHOD = TaskRunMethod.TASK_PROCESSOR
 
 # Avoid models.W042 warnings

src/common/core/main.py

@@ -52,6 +52,9 @@ def ensure_cli_env() -> typing.Generator[None, None, None]:
         )
         os.environ["PROMETHEUS_MULTIPROC_DIR"] = prometheus_multiproc_dir_name
 
+    if "docgen" in sys.argv:
+        os.environ["DOCGEN_MODE"] = "true"
+
     if "task-processor" in sys.argv:
         # A hacky way to signal we're not running the API
         os.environ["RUN_BY_PROCESSOR"] = "true"

src/common/core/management/commands/docgen.py

@@ -0,0 +1,64 @@
+from operator import itemgetter
+from typing import Any, Callable
+
+import prometheus_client
+from django.core.management import BaseCommand, CommandParser
+from django.template.loader import get_template
+from django.utils.module_loading import autodiscover_modules
+from prometheus_client.metrics import MetricWrapperBase
+
+
+class Command(BaseCommand):
+    help = "Generate documentation for the Flagsmith codebase."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        subparsers = parser.add_subparsers(
+            title="sub-commands",
+            required=True,
+        )
+
+        metric_parser = subparsers.add_parser(
+            "metrics",
+            help="Start the Metrics service.",
+        )
+        metric_parser.set_defaults(handle_method=self.handle_metrics)
+
+    def initialise(self) -> None:
+        from common.gunicorn import metrics
+
+        autodiscover_modules(
+            "metrics",
+        )
+
+    def handle(
+        self,
+        *args: Any,
+        handle_method: Callable[..., None],
+        **options: Any,
+    ) -> None:
+        self.initialise()
+        handle_method(*args, **options)
+
+    def handle_metrics(self, *args: Any, **options: Any) -> None:
+        template = get_template("docgen-metrics.md")
+
+        flagsmith_metrics = sorted(
+            (
+                {
+                    "name": collector._name,
+                    "documentation": collector._documentation,
+                    "labels": collector._labelnames,
+                    "type": collector._type,
+                }
+                for collector in prometheus_client.REGISTRY._collector_to_names
+                if isinstance(collector, MetricWrapperBase)
+                and collector._name.startswith("flagsmith")
+            ),
+            key=itemgetter("name"),
+        )
+
+        self.stdout.write(
+            template.render(
+                context={"flagsmith_metrics": flagsmith_metrics},
+            )
+        )

src/common/core/templates/docgen-metrics.md

@@ -0,0 +1,11 @@
+# Prometheus metrics
+
+Flagsmith exports Prometheus metrics described below.
+{% for metric in flagsmith_metrics %}
+## `{{ metric.name }}` {{ metric.type }}
+
+{{ metric.documentation }}
+
+Labels:
+{% for label in metric.labels %} - `{{ label }}`
+{% endfor %}{% endfor %}

src/task_processor/metrics.py

@@ -9,7 +9,7 @@
     ["task_identifier"],
 )
 
-if settings.TASK_PROCESSOR_MODE:
+if settings.DOCGEN_MODE or settings.TASK_PROCESSOR_MODE:
     flagsmith_task_processor_finished_tasks_total = prometheus_client.Counter(
         "flagsmith_task_processor_finished_tasks_total",
         "Total number of finished tasks",