feat(experimentation): environment-scoped metrics & experiment results

api/audit/related_object_type.py

@@ -14,3 +14,4 @@ class RelatedObjectType(enum.Enum):
     RELEASE_PIPELINE = "Release pipeline"
     WAREHOUSE_CONNECTION = "Warehouse connection"
     EXPERIMENT = "Experiment"
+    METRIC = "Metric"

api/environments/urls.py

@@ -181,4 +181,8 @@
         "<str:environment_api_key>/experiments/",
         include("experimentation.experiment_urls"),
     ),
+    path(
+        "<str:environment_api_key>/experiment-metrics/",
+        include("experimentation.metric_urls"),
+    ),
 ]

api/experimentation/experiment_urls.py

@@ -1,10 +1,15 @@
-from rest_framework.routers import DefaultRouter
+from rest_framework_nested import routers  # type: ignore[import-untyped]
 
-from experimentation.views import ExperimentViewSet
+from experimentation.views import ExperimentMetricViewSet, ExperimentViewSet
 
 app_name = "experiments"
 
-router = DefaultRouter()
+router = routers.DefaultRouter()
 router.register(r"", ExperimentViewSet, basename="experiments")
 
-urlpatterns = router.urls
+experiments_router = routers.NestedSimpleRouter(router, r"", lookup="experiment")
+experiments_router.register(
+    r"metrics", ExperimentMetricViewSet, basename="experiment-metrics"
+)
+
+urlpatterns = router.urls + experiments_router.urls

api/experimentation/metric_urls.py

@@ -0,0 +1,10 @@
+from rest_framework.routers import DefaultRouter
+
+from experimentation.views import MetricViewSet
+
+app_name = "experiment_metrics"
+
+router = DefaultRouter()
+router.register(r"", MetricViewSet, basename="metrics")
+
+urlpatterns = router.urls

api/experimentation/migrations/0005_metrics.py

@@ -0,0 +1,124 @@
+# Generated by Django 5.2.14 on 2026-06-02 10:47
+
+import django.db.models.deletion
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("environments", "0037_add_uuid_field"),
+        ("experimentation", "0004_experiment"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Metric",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "deleted_at",
+                    models.DateTimeField(
+                        blank=True,
+                        db_index=True,
+                        default=None,
+                        editable=False,
+                        null=True,
+                    ),
+                ),
+                (
+                    "uuid",
+                    models.UUIDField(default=uuid.uuid4, editable=False, unique=True),
+                ),
+                ("name", models.CharField(max_length=255)),
+                ("description", models.TextField(blank=True, default="")),
+                (
+                    "aggregation",
+                    models.CharField(
+                        choices=[
+                            ("count", "Count"),
+                            ("sum", "Sum"),
+                            ("mean", "Mean"),
+                            ("occurrence", "Occurrence (event happened at least once)"),
+                        ],
+                        default="mean",
+                        max_length=20,
+                    ),
+                ),
+                ("definition", models.JSONField()),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "environment",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="metrics",
+                        to="environments.environment",
+                    ),
+                ),
+            ],
+            options={
+                "abstract": False,
+            },
+        ),
+        migrations.CreateModel(
+            name="ExperimentMetric",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "expected_direction",
+                    models.CharField(
+                        choices=[
+                            ("increase", "Increase"),
+                            ("decrease", "Decrease"),
+                            ("not_increase", "Should not increase"),
+                            ("not_decrease", "Should not decrease"),
+                        ],
+                        max_length=20,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                (
+                    "experiment",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="experiment_metrics",
+                        to="experimentation.experiment",
+                    ),
+                ),
+                (
+                    "metric",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="experiment_metrics",
+                        to="experimentation.metric",
+                    ),
+                ),
+            ],
+            options={
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("experiment", "metric"),
+                        name="metric_attached_once_per_experiment",
+                    )
+                ],
+            },
+        ),
+    ]

api/experimentation/models.py

@@ -117,3 +117,63 @@ class Meta:
                 name="unique_active_experiment_per_feature_env",
             ),
         ]
+
+
+class MetricAggregation(models.TextChoices):
+    COUNT = "count", "Count"
+    SUM = "sum", "Sum"
+    MEAN = "mean", "Mean"
+    OCCURRENCE = "occurrence", "Occurrence (event happened at least once)"
+
+
+class ExpectedDirection(models.TextChoices):
+    INCREASE = "increase", "Increase"
+    DECREASE = "decrease", "Decrease"
+    NOT_INCREASE = "not_increase", "Should not increase"
+    NOT_DECREASE = "not_decrease", "Should not decrease"
+
+
+class Metric(SoftDeleteExportableModel):
+    environment = models.ForeignKey(
+        Environment,
+        on_delete=models.CASCADE,
+        related_name="metrics",
+    )
+    name = models.CharField(max_length=255)
+    description = models.TextField(blank=True, default="")
+    aggregation = models.CharField(
+        max_length=20,
+        choices=MetricAggregation.choices,
+        default=MetricAggregation.MEAN,
+    )
+    definition: models.JSONField[dict[str, object], dict[str, object]] = (
+        models.JSONField()
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+
+class ExperimentMetric(models.Model):
+    experiment = models.ForeignKey(
+        Experiment,
+        on_delete=models.CASCADE,
+        related_name="experiment_metrics",
+    )
+    metric = models.ForeignKey(
+        Metric,
+        on_delete=models.CASCADE,
+        related_name="experiment_metrics",
+    )
+    expected_direction = models.CharField(
+        max_length=20,
+        choices=ExpectedDirection.choices,
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(
+                fields=["experiment", "metric"],
+                name="metric_attached_once_per_experiment",
+            ),
+        ]

api/experimentation/permissions.py

@@ -40,3 +40,19 @@ def has_permission(self, request: Request, view: APIView) -> bool:
 
         user: FFAdminUser = request.user  # type: ignore[assignment]
         return user.is_environment_admin(environment)
+
+
+class MetricPermission(BasePermission):
+    def has_permission(self, request: Request, view: APIView) -> bool:
+        try:
+            environment = Environment.objects.get(
+                api_key=view.kwargs.get("environment_api_key")
+            )
+        except Environment.DoesNotExist:
+            return False
+
+        if not is_experiment_feature_enabled(environment.project.organisation):
+            return False
+
+        user: FFAdminUser = request.user  # type: ignore[assignment]
+        return user.is_environment_admin(environment)

api/experimentation/serializers.py

@@ -5,6 +5,8 @@
 from environments.models import Environment
 from experimentation.models import (
     Experiment,
+    ExperimentMetric,
+    Metric,
     WarehouseConnection,
     WarehouseType,
 )
@@ -76,6 +78,84 @@ def _validate_snowflake_config(config: dict[str, Any]) -> SnowflakeConfig:
         return merged
 
 
+class MetricSerializer(serializers.ModelSerializer):  # type: ignore[type-arg]
+    class Meta:
+        model = Metric
+        fields = (
+            "id",
+            "name",
+            "description",
+            "aggregation",
+            "definition",
+            "created_at",
+            "updated_at",
+        )
+        read_only_fields = (
+            "id",
+            "created_at",
+            "updated_at",
+        )
+
+    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+        definition: Any = attrs.get(
+            "definition", getattr(self.instance, "definition", None)
+        )
+        error = self._validate_definition(definition)
+        if error:
+            raise serializers.ValidationError({"definition": error})
+        return attrs
+
+    @staticmethod
+    def _validate_definition(definition: Any) -> str | None:
+        if not isinstance(definition, dict):
+            return "Definition must be an object."
+
+        event = definition.get("event")
+        if not event or not isinstance(event, str):
+            return "Definition must specify a non-empty 'event'."
+
+        return None
+
+
+class ExperimentMetricSerializer(serializers.ModelSerializer):  # type: ignore[type-arg]
+    metric = serializers.PrimaryKeyRelatedField(  # type: ignore[var-annotated]
+        queryset=Metric.objects.all(),
+    )
+    metric_name = serializers.CharField(source="metric.name", read_only=True)
+    aggregation = serializers.CharField(source="metric.aggregation", read_only=True)
+
+    class Meta:
+        model = ExperimentMetric
+        fields = (
+            "id",
+            "metric",
+            "metric_name",
+            "aggregation",
+            "expected_direction",
+            "created_at",
+        )
+        read_only_fields = ("id", "created_at")
+
+    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+        experiment: Experiment = self.context["experiment"]
+        metric: Metric = attrs.get("metric", getattr(self.instance, "metric", None))
+
+        if metric.environment_id != experiment.environment_id:
+            raise serializers.ValidationError(
+                {"metric": "Metric must belong to the experiment's environment."}
+            )
+
+        attached = experiment.experiment_metrics.all()
+        if isinstance(self.instance, ExperimentMetric):
+            attached = attached.exclude(pk=self.instance.pk)
+
+        if "metric" in attrs and attached.filter(metric=metric).exists():
+            raise serializers.ValidationError(
+                {"metric": "Metric is already attached to this experiment."}
+            )
+        return attrs
+
+
 class ExperimentSerializer(serializers.ModelSerializer):  # type: ignore[type-arg]
     class Meta:
         model = Experiment

api/experimentation/services.py

@@ -13,7 +13,7 @@
 from integrations.flagsmith.client import get_openfeature_client
 
 if typing.TYPE_CHECKING:
-    from experimentation.models import Experiment, WarehouseConnection
+    from experimentation.models import Experiment, Metric, WarehouseConnection
     from organisations.models import Organisation
     from users.models import FFAdminUser
 
@@ -83,6 +83,22 @@ def create_warehouse_audit_log(
     )
 
 
+def create_metric_audit_log(
+    metric: Metric,
+    user: FFAdminUser,
+    *,
+    action: str,
+) -> None:
+    AuditLog.objects.create(
+        environment=metric.environment,
+        project=metric.environment.project,
+        **_resolve_audit_log_author(user),
+        related_object_id=metric.id,
+        related_object_type=RelatedObjectType.METRIC.name,
+        log=f"Metric '{metric.name}' {action}",
+    )
+
+
 def create_experiment_audit_log(
     experiment: Experiment,
     user: FFAdminUser,