docs: Add Prometheus metrics documentation (#5395)

Author: khvn26

.github/workflows/api-pull-request.yml

@@ -17,6 +17,9 @@ defaults:
   run:
     working-directory: api
 
+env:
+  DOTENV_OVERRIDE_FILE: .env-ci
+
 jobs:
   test:
     runs-on: General-Purpose-8c-Runner
@@ -60,16 +63,18 @@ jobs:
 
       - name: Check for missing migrations
         env:
-          DOTENV_OVERRIDE_FILE: .env-ci
           opts: --no-input --dry-run --check
         run: make django-make-migrations
 
       - name: Check for new typing errors
         run: make typecheck
 
+      - name: Check autogenerated documentation
+        uses: nickcharlton/diff-check@v1.0.0
+        with:
+          command: make -C api generate-docs
+  
       - name: Run Tests
-        env:
-          DOTENV_OVERRIDE_FILE: .env-ci
         run: make test
 
       - name: Upload Coverage

.pre-commit-config.yaml

@@ -28,6 +28,12 @@ repos:
         args:
           - --check
         types: [javascript, jsx, ts, tsx, markdown, mdx, html, css, json, yaml]
+      - id: generate-docs
+        name: generate-docs
+        language: system
+        entry: make -C api generate-docs
+        pass_filenames: false
+        types: [python,toml]
       - id: python-typecheck
         name: python-typecheck
         language: system
@@ -43,5 +49,5 @@ repos:
         args: ["-C", "api"]
 
 ci:
-  skip: [python-typecheck]
+  skip: [generate-docs, python-typecheck]
   autoupdate_commit_msg: "ci: pre-commit autoupdate"

api/Makefile

@@ -140,3 +140,7 @@ integrate-private-tests:
 
 	git clone https://github.com/flagsmith/flagsmith-task-processor --depth 1 --branch ${TASK_PROCESSOR_REVISION} && mv ./flagsmith-task-processor/tests tests/task_processor_tests
 	rm -rf ./flagsmith-saml ./flagsmith-rbac ./flagsmith-workflows ./flagsmith-auth-controller ./flagsmith-task-processor
+
+.PHONY: generate-docs
+generate-docs:
+	poetry run flagsmith docgen metrics > ../docs/docs/system-administration/metrics.md

api/app/settings/common.py

@@ -1407,3 +1407,5 @@
         default=prometheus_client.Histogram.DEFAULT_BUCKETS,
     )
 )
+
+DOCGEN_MODE = env.bool("DOCGEN_MODE", default=False)

api/environments/metrics.py

@@ -5,6 +5,6 @@
 
 flagsmith_environment_document_cache_queries_total = prometheus_client.Counter(
     "flagsmith_environment_document_cache_queries_total",
-    "Results of cache retrieval for environment document (hit or miss)",
+    "Results of cache retrieval for environment document. `result` label is either `hit` or `miss`.",
     ["result"],
 )

api/poetry.lock

@@ -66,7 +66,13 @@ exclude_also = [
 omit = ["scripts/*", "manage.py"]
 
 [tool.pytest.ini_options]
-addopts = ['--ds=app.settings.test', '-vvvv', '-p', 'no:warnings', '--dist=worksteal']
+addopts = [
+  '--ds=app.settings.test',
+  '-vvvv',
+  '-p',
+  'no:warnings',
+  '--dist=worksteal',
+]
 console_output_style = 'count'
 
 [tool.mypy]
@@ -154,7 +160,7 @@ pygithub = "2.1.1"
 hubspot-api-client = "^8.2.1"
 djangorestframework-dataclasses = "^1.3.1"
 pyotp = "^2.9.0"
-flagsmith-common = "^1.11.0"
+flagsmith-common = "^1.12.0"
 django-stubs = "^5.1.3"
 tzdata = "^2024.1"
 djangorestframework-simplejwt = "^5.3.1"

api/pyproject.toml

@@ -0,0 +1,94 @@
+---
+title: Metrics
+---
+
+## Prometheus
+
+To enable the Prometheus `/metrics` endpoint, set the `PROMETHEUS_ENABLED` environment variable to `true`. 
+
+The metrics provided by Flagsmith are described below.
+
+
+### `flagsmith_build_info`
+
+Gauge.
+
+Flagsmith version and build information.
+
+Labels:
+ - `ci_commit_sha`
+ - `version`
+
+### `flagsmith_environment_document_cache_queries`
+
+Counter.
+
+Results of cache retrieval for environment document. `result` label is either `hit` or `miss`.
+
+Labels:
+ - `result`
+
+### `flagsmith_http_server_request_duration_seconds`
+
+Histogram.
+
+HTTP request duration in seconds.
+
+Labels:
+ - `route`
+ - `method`
+ - `response_status`
+
+### `flagsmith_http_server_requests`
+
+Counter.
+
+Total number of HTTP requests.
+
+Labels:
+ - `route`
+ - `method`
+ - `response_status`
+
+### `flagsmith_http_server_response_size_bytes`
+
+Histogram.
+
+HTTP response size in bytes.
+
+Labels:
+ - `route`
+ - `method`
+ - `response_status`
+
+### `flagsmith_task_processor_enqueued_tasks`
+
+Counter.
+
+Total number of enqueued tasks.
+
+Labels:
+ - `task_identifier`
+
+### `flagsmith_task_processor_finished_tasks`
+
+Counter.
+
+Total number of finished tasks. Only collected by Task Processor. `task_type` label is either `recurring` or `standard`.
+
+Labels:
+ - `task_identifier`
+ - `task_type`
+ - `result`
+
+### `flagsmith_task_processor_task_duration_seconds`
+
+Histogram.
+
+Task processor task duration in seconds. Only collected by Task Processor. `task_type` label is either `recurring` or `standard`.
+
+Labels:
+ - `task_identifier`
+ - `task_type`
+ - `result`
+