feat: Prometheus support, core entrypoint, packaging improvements (#17)

- Add Prometheus support
- Cover Gunicorn with request metrics
- Add support for custom application metrics
- Add `flagsmith-test-tools` pytest plugin and `assert_metric` fixture
- Add `flagsmith start api` package entrypoint
- Improve packaging

---------

Co-authored-by: Rodrigo López Dato <[email protected]>

Author: khvn26

.gitignore

@@ -1,4 +1,6 @@
 .venv/
 .env
 .idea/
-*.pyc
+*.pyc
+.coverage
+common.sqlite3

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2024, Flagsmith
+Copyright (c) 2025, Flagsmith
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

README.md

@@ -1,13 +1,13 @@
 # flagsmith-common
-A repository for including code that is required in multiple flagsmith repositories
+Flagsmith's common library
 
 ### Development Setup
 
 This project uses [Poetry](https://python-poetry.org/) for dependency management and includes a Makefile to simplify common development tasks.
 
 #### Prerequisites
 
-- Python >= 3.8
+- Python >= 3.11
 - Make
 
 #### Installation
@@ -47,3 +47,49 @@ make install-packages opts="--with dev"
 # Install with specific extras
 make install-packages opts="--extras 'feature1 feature2'"
 ```
+
+### Usage
+
+#### Installation
+
+1. Make sure `"common.core"` is in the `INSTALLED_APPS` of your settings module.
+This enables the `manage.py flagsmith` commands.
+
+2. Add `"common.gunicorn.middleware.RouteLoggerMiddleware"` to `MIDDLEWARE` in your settings module.
+This enables the `route` label for Prometheus HTTP metrics.
+
+3. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
+
+#### Metrics
+
+Flagsmith uses Prometheus to track performance metrics.
+
+The following default metrics are exposed:
+
+- `flagsmith_build_info`: Has the labels `version` and `ci_commit_sha`.
+- `http_server_request_duration_seconds`: Histogram labeled with `method`, `path`, and `response_status`.
+- `http_server_requests_total`: Counter labeled with `method`, `path`, and `response_status`.
+
+##### Guidelines
+
+Try to come up with meaningful metrics to cover your feature with when developing it. Refer to [Prometheus best practices][1] when naming your metric and labels.
+
+Define your metrics in a `metrics.py` module of your Django application — see [example][2]. Contrary to Prometheus Python client examples and documentation, please name a metric variable exactly as your metric name.
+
+It's generally a good idea to allow users to define histogram buckets of their own. Flagsmith accepts a `PROMETHEUS_HISTOGRAM_BUCKETS` setting so users can customise their buckets. To honour the setting, use the `common.prometheus.Histogram` class when defining your histograms. When using `prometheus_client.Histogram` directly, please expose a dedicated setting like so:
+
+```python
+import prometheus_client
+from django.conf import settings
+
+distance_from_earth_au = prometheus.Histogram(
+    "distance_from_earth_au",
+    "Distance from Earth in astronomical units",
+    buckets=settings.DISTANCE_FROM_EARTH_AU_HISTOGRAM_BUCKETS,
+)
+```
+
+[1]: https://prometheus.io/docs/practices/naming/
+[2]: https://github.com/Flagsmith/flagsmith-common/blob/main/src/common/gunicorn/metrics.py
+[3]: https://docs.gunicorn.org/en/stable/design.html#server-model
+[4]: https://prometheus.github.io/client_python/multiprocess

poetry.lock

@@ -1,29 +1,70 @@
-[tool.poetry]
-name = "flagsmith_common"
+[project]
+name = "flagsmith-common"
 version = "1.5.0"
-description = "A repository for including code that is required in multiple flagsmith repositories"
-authors = ["Matthew Elwell <[email protected]>"]
+description = "Flagsmith's common library"
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "django (<5)",
+    "django-health-check",
+    "djangorestframework-recursive",
+    "djangorestframework",
+    "drf-writable-nested",
+    "flagsmith-flag-engine",
+    "gunicorn (>=19.1)",
+    "prometheus-client (>=0.0.16)",
+    "environs (<15)",
+]
+authors = [
+    { name = "Matthew Elwell" },
+    { name = "Gagan Trivedi" },
+    { name = "Kim Gustyr" },
+    { name = "Zach Aysan" },
+    { name = "Francesco Lo Franco" },
+    { name = "Rodrigo López Dato" },
+]
+maintainers = [{ name = "Flagsmith Team", email = "[email protected]" }]
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
 readme = "README.md"
-packages = [{ include = "common", from = "src" }]
+dynamic = ["classifiers"]
+
+[project.urls]
+Download = "https://github.com/flagsmith/flagsmith-common/releases"
+Homepage = "https://flagsmith.com"
+Issues = "https://github.com/flagsmith/flagsmith-common/issues"
+Repository = "https://github.com/flagsmith/flagsmith-common"
 
-[tool.poetry.dependencies]
-python = "^3.10"
-django = "<5.0.0"
-djangorestframework = "*"
-drf-writable-nested = "*"
-flagsmith-flag-engine = "*"
-djangorestframework-recursive = "*"
-django-health-check = "^3.18.3"
+[project.scripts]
+flagsmith = "common.core.main:main"
+
+[project.entry-points.pytest11]
+flagsmith-test-tools = "common.test_tools.plugin"
+
+[tool.poetry]
+requires-poetry = ">=2.0"
+classifiers = [
+    "Framework :: Django",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+]
+packages = [{ include = "common", from = "src" }]
 
 [tool.poetry.group.dev.dependencies]
+django-stubs = "^5.1.3"
+djangorestframework-stubs = "^3.15.3"
+mypy = "^1.15.0"
 pre-commit = "*"
-ruff = "*"
-pytest = "^8.3.4"
 pyfakefs = "^5.7.4"
+pytest = "^8.3.4"
+pytest-asyncio = "^0.25.3"
+pytest-cov = "^6.0.0"
 pytest-django = "^4.10.0"
-mypy = "^1.15.0"
-django-stubs = "^5.1.3"
-djangorestframework-stubs = "^3.15.3"
+pytest-freezegun = "^0.4.2"
+pytest-mock = "^3.14.0"
+requests = "^2.32.3"
+ruff = "*"
+setuptools = "^77.0.3"
 
 [build-system]
 requires = ["poetry-core"]

pyproject.toml

@@ -1,16 +1,28 @@
+import prometheus_client
+
 # Settings expected by `mypy_django_plugin`
-SENDGRID_API_KEY: str
 AWS_SES_REGION_ENDPOINT: str
 SEGMENT_RULES_CONDITIONS_LIMIT: int
+SENDGRID_API_KEY: str
+PROMETHEUS_ENABLED = True
 
 # Settings required for tests
-INSTALLED_APPS = [
-    "django.contrib.auth",
-    "django.contrib.contenttypes",
-]
 DATABASES = {
     "default": {
         "ENGINE": "django.db.backends.sqlite3",
-        "NAME": "common",
+        "NAME": "common.sqlite3",
     }
 }
+INSTALLED_APPS = [
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "common.core",
+]
+MIDDLEWARE = [
+    "common.gunicorn.middleware.RouteLoggerMiddleware",
+]
+LOG_FORMAT = "json"
+PROMETHEUS_HISTOGRAM_BUCKETS = prometheus_client.Histogram.DEFAULT_BUCKETS
+ROOT_URLCONF = "common.core.urls"
+TIME_ZONE = "UTC"
+USE_TZ = True

settings/dev.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class CoreConfig(AppConfig):
+    name = "common.core"
+    label = "common_core"

src/common/app/views.py

@@ -0,0 +1,24 @@
+import json
+import logging
+from typing import Any
+
+
+class JsonFormatter(logging.Formatter):
+    """Custom formatter for json logs."""
+
+    def get_json_record(self, record: logging.LogRecord) -> dict[str, Any]:
+        formatted_message = record.getMessage()
+        json_record = {
+            "levelname": record.levelname,
+            "message": formatted_message,
+            "timestamp": self.formatTime(record, self.datefmt),
+            "logger_name": record.name,
+            "pid": record.process,
+            "thread_name": record.threadName,
+        }
+        if record.exc_info:
+            json_record["exc_info"] = self.formatException(record.exc_info)
+        return json_record
+
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps(self.get_json_record(record))