From b366326e7b210ad3e38e30887a8f2545dabb3af9 Mon Sep 17 00:00:00 2001 From: German Garces Date: Wed, 18 Nov 2026 16:35:47 +0100 Subject: [PATCH 1/5] refactor: Move telemetry reports to the telemetry app --- api/app_analytics/analytics_db_service.py | 14 +- api/organisations/tasks.py | 6 - api/organisations/usage_reporting/mappers.py | 81 ----- api/organisations/usage_reporting/services.py | 75 ----- api/telemetry/control_plane/client.py | 45 +++ .../dataclasses.py | 0 api/telemetry/services.py | 106 +++++++ api/telemetry/tasks.py | 10 + .../organisations/usage_reporting/__init__.py | 0 .../usage_reporting/test_mappers.py | 113 ------- .../usage_reporting/test_services.py | 237 -------------- .../usage_reporting/test_tasks.py | 16 - .../unit/telemetry/control_plane}/__init__.py | 0 .../telemetry/control_plane/test_client.py | 35 +++ api/tests/unit/telemetry/test_services.py | 297 ++++++++++++++++++ api/tests/unit/telemetry/test_tasks.py | 16 + 16 files changed, 521 insertions(+), 530 deletions(-) delete mode 100644 api/organisations/usage_reporting/mappers.py delete mode 100644 api/organisations/usage_reporting/services.py create mode 100644 api/telemetry/control_plane/client.py rename api/{organisations/usage_reporting => telemetry}/dataclasses.py (100%) create mode 100644 api/telemetry/services.py create mode 100644 api/telemetry/tasks.py delete mode 100644 api/tests/unit/organisations/usage_reporting/__init__.py delete mode 100644 api/tests/unit/organisations/usage_reporting/test_mappers.py delete mode 100644 api/tests/unit/organisations/usage_reporting/test_services.py delete mode 100644 api/tests/unit/organisations/usage_reporting/test_tasks.py rename api/{organisations/usage_reporting => tests/unit/telemetry/control_plane}/__init__.py (100%) create mode 100644 api/tests/unit/telemetry/control_plane/test_client.py create mode 100644 api/tests/unit/telemetry/test_services.py create mode 100644 api/tests/unit/telemetry/test_tasks.py diff --git a/api/app_analytics/analytics_db_service.py b/api/app_analytics/analytics_db_service.py index f007e17770de..f31ee6a0122b 100644 --- a/api/app_analytics/analytics_db_service.py +++ b/api/app_analytics/analytics_db_service.py @@ -188,15 +188,25 @@ def get_usage_data_from_local_db_for_window( date_start: datetime, date_stop: datetime, project_id: int | None = None, + group_by: UsageGroupByType | None = None, ) -> list[UsageData]: + project_ids_by_environment_id = _get_project_ids_by_environment_id_for_org( + organisation + ) qs = _get_api_usage_bucket_qs( - _get_project_ids_by_environment_id_for_org(organisation), + project_ids_by_environment_id, project_id=project_id, ).filter( created_at__gte=date_start, created_at__lt=date_stop, ) - return _aggregate_buckets(qs) + if not group_by: + return _aggregate_buckets(qs) + + return map_annotated_api_usage_buckets_to_usage_data( + _group_bucket(row, project_ids_by_environment_id, group_by) + for row in _annotate_buckets(qs, "environment_id") + ) def get_usage_data_for_window( diff --git a/api/organisations/tasks.py b/api/organisations/tasks.py index 503584f59f28..caa3481426fa 100644 --- a/api/organisations/tasks.py +++ b/api/organisations/tasks.py @@ -36,7 +36,6 @@ FREE_PLAN_ID, MAX_API_CALLS_IN_FREE_PLAN, ) -from organisations.usage_reporting.services import push_usage_snapshots from users.models import FFAdminUser from .constants import ( @@ -97,11 +96,6 @@ def update_organisation_subscription_information_cache_recurring() -> None: update_organisation_subscription_information_cache() -@register_recurring_task(run_every=timedelta(hours=1)) -def push_usage_to_control_plane() -> None: - push_usage_snapshots() - - @register_task_handler() def update_organisation_subscription_information_api_usage_cache() -> None: subscription_info_cache.update_caches(SubscriptionCacheEntity.API_USAGE) diff --git a/api/organisations/usage_reporting/mappers.py b/api/organisations/usage_reporting/mappers.py deleted file mode 100644 index cb12d567f6b0..000000000000 --- a/api/organisations/usage_reporting/mappers.py +++ /dev/null @@ -1,81 +0,0 @@ -import base64 -from datetime import timedelta - -from common.core.utils import get_version -from django.utils import timezone - -from app_analytics.analytics_db_service import get_usage_data_for_window -from app_analytics.dataclasses import UsageData -from organisations.models import Organisation -from organisations.usage_reporting.dataclasses import ( - ApiCallBreakdown, - ProjectUsage, - UsageSnapshot, -) - -# The Control Plane rejects payloads with more than this many project_usage rows. -MAX_PROJECT_USAGE_ROWS = 5_000 - - -def map_signature_to_control_plane_auth_token(signature_b64: str) -> str: - raw_signature = base64.b64decode(signature_b64) - return base64.urlsafe_b64encode(raw_signature).decode("ascii").rstrip("=") - - -def map_usage_data_to_total_api_calls(usage_data: list[UsageData]) -> int: - return sum( - data.flags + data.identities + data.traits + data.environment_document - for data in usage_data - ) - - -def map_usage_data_to_api_call_breakdown( - usage_data: list[UsageData], -) -> ApiCallBreakdown: - return ApiCallBreakdown( - flags=sum(data.flags for data in usage_data), - identities=sum(data.identities for data in usage_data), - traits=sum(data.traits for data in usage_data), - environment_documents=sum(data.environment_document for data in usage_data), - ) - - -def map_project_usage_data_to_project_usage( - usage_data_by_project_id: dict[int, list[UsageData]], -) -> list[ProjectUsage]: - rows = [ - ProjectUsage( - project_id=project_id, - api_call_count=map_usage_data_to_total_api_calls(usage_data), - ) - for project_id, usage_data in usage_data_by_project_id.items() - ] - # Highest usage first - rows.sort(key=lambda row: row.api_call_count, reverse=True) - return rows[:MAX_PROJECT_USAGE_ROWS] - - -def map_organisation_to_usage_snapshot(organisation: Organisation) -> UsageSnapshot: - hour_end = timezone.now().replace(minute=0, second=0, microsecond=0) - hour_start = hour_end - timedelta(hours=1) - seat_count = organisation.num_seats - instance_version = get_version() - usage_data = get_usage_data_for_window(organisation, hour_start, hour_end) - usage_data_by_project_id = { - project.id: get_usage_data_for_window( - organisation, hour_start, hour_end, project_id=project.id - ) - for project in organisation.projects.all() - } - - # No data access past this point! - - return UsageSnapshot( - timestamp=hour_start, - seat_count=seat_count, - api_call_total=map_usage_data_to_total_api_calls(usage_data), - api_call_breakdown=map_usage_data_to_api_call_breakdown(usage_data), - project_count=len(usage_data_by_project_id), - instance_version=instance_version, - project_usage=map_project_usage_data_to_project_usage(usage_data_by_project_id), - ) diff --git a/api/organisations/usage_reporting/services.py b/api/organisations/usage_reporting/services.py deleted file mode 100644 index 7f5d41369d68..000000000000 --- a/api/organisations/usage_reporting/services.py +++ /dev/null @@ -1,75 +0,0 @@ -import dataclasses -import json - -import requests -import structlog -from django.conf import settings -from django.core.serializers.json import DjangoJSONEncoder - -from organisations.models import Organisation -from organisations.usage_reporting.dataclasses import UsageSnapshot -from organisations.usage_reporting.mappers import ( - map_organisation_to_usage_snapshot, - map_signature_to_control_plane_auth_token, -) - -logger = structlog.get_logger("usage_reporting") - -USAGE_ENDPOINT_PATH = "/v1/public/usage" -REQUEST_TIMEOUT_SECONDS = 30 - - -def get_licensed_organisations() -> list[Organisation]: - if not settings.LICENSING_INSTALLED: - return [] - return list( - Organisation.objects.filter(licence__isnull=False).select_related("licence") - ) - - -def push_snapshot( - *, - base_url: str, - snapshot: UsageSnapshot, - signature_b64: str, -) -> None: - url = f"{base_url.rstrip('/')}{USAGE_ENDPOINT_PATH}" - headers = { - "Authorization": ( - f"Bearer {map_signature_to_control_plane_auth_token(signature_b64)}" - ), - "Content-Type": "application/json", - } - body = json.dumps(dataclasses.asdict(snapshot), cls=DjangoJSONEncoder) - - response = requests.post( - url, - data=body, - headers=headers, - timeout=REQUEST_TIMEOUT_SECONDS, - ) - - if response.ok: - logger.info("snapshot.pushed", status_code=response.status_code) - else: - logger.warning("snapshot.push_failed", status_code=response.status_code) - - -def push_usage_snapshots() -> None: - if not (base_url := settings.CONTROL_PLANE_URL): - logger.debug("run.skipped", reason="control_plane_url_unset") - return - if not (organisations := get_licensed_organisations()): - logger.debug("run.skipped", reason="no_licensed_organisations") - return - - for organisation in organisations: - with structlog.contextvars.bound_contextvars(organisation__id=organisation.id): - try: - push_snapshot( - base_url=base_url, - snapshot=map_organisation_to_usage_snapshot(organisation), - signature_b64=organisation.licence.signature, - ) - except Exception: - logger.exception("snapshot.errored") diff --git a/api/telemetry/control_plane/client.py b/api/telemetry/control_plane/client.py new file mode 100644 index 000000000000..2773c6df59fe --- /dev/null +++ b/api/telemetry/control_plane/client.py @@ -0,0 +1,45 @@ +import base64 +import dataclasses +import json + +import requests +import structlog +from django.core.serializers.json import DjangoJSONEncoder + +from telemetry.dataclasses import UsageSnapshot + +logger = structlog.get_logger(__name__) + +USAGE_ENDPOINT_PATH = "/v1/public/usage" +REQUEST_TIMEOUT_SECONDS = 30 + + +def post_usage_snapshot( + *, + base_url: str, + snapshot: UsageSnapshot, + signature_b64: str, +) -> None: + url = f"{base_url.rstrip('/')}{USAGE_ENDPOINT_PATH}" + headers = { + "Authorization": (f"Bearer {_map_signature_to_bearer_token(signature_b64)}"), + "Content-Type": "application/json", + } + body = json.dumps(dataclasses.asdict(snapshot), cls=DjangoJSONEncoder) + + response = requests.post( + url, + data=body, + headers=headers, + timeout=REQUEST_TIMEOUT_SECONDS, + ) + + if response.ok: + logger.info("snapshot.pushed", status_code=response.status_code) + else: + logger.warning("snapshot.push_failed", status_code=response.status_code) + + +def _map_signature_to_bearer_token(signature_b64: str) -> str: + raw_signature = base64.b64decode(signature_b64) + return base64.urlsafe_b64encode(raw_signature).decode("ascii").rstrip("=") diff --git a/api/organisations/usage_reporting/dataclasses.py b/api/telemetry/dataclasses.py similarity index 100% rename from api/organisations/usage_reporting/dataclasses.py rename to api/telemetry/dataclasses.py diff --git a/api/telemetry/services.py b/api/telemetry/services.py new file mode 100644 index 000000000000..5c34a387b2bc --- /dev/null +++ b/api/telemetry/services.py @@ -0,0 +1,106 @@ +from datetime import timedelta + +import structlog +from common.core.utils import get_version +from django.conf import settings +from django.utils import timezone + +from app_analytics.analytics_db_service import get_usage_data_for_window +from app_analytics.dataclasses import UsageData +from organisations.models import Organisation +from telemetry.control_plane.client import post_usage_snapshot +from telemetry.dataclasses import ApiCallBreakdown, ProjectUsage, UsageSnapshot + +logger = structlog.get_logger(__name__) + +MAX_PROJECT_USAGE_ROWS = 5_000 + + +def push_usage_snapshots() -> None: + if not (settings.ENABLE_TELEMETRY): + logger.debug("run.skipped", reason="telemetry_disabled") + return + if not (base_url := settings.CONTROL_PLANE_URL): + logger.debug("run.skipped", reason="control_plane_url_unset") + return + if not (organisations := _get_licensed_organisations()): + logger.debug("run.skipped", reason="no_licensed_organisations") + return + + for organisation in organisations: + with structlog.contextvars.bound_contextvars(organisation__id=organisation.id): + try: + post_usage_snapshot( + base_url=base_url, + snapshot=_get_usage_snapshot(organisation), + signature_b64=organisation.licence.signature, + ) + except Exception: + logger.exception("snapshot.errored") + + +def _get_licensed_organisations() -> list[Organisation]: + if settings.LICENSING_INSTALLED: # pragma: no cover + return list( + Organisation.objects.filter(licence__isnull=False).select_related("licence") + ) + return [] + + +def _sum_api_calls(usage_data: list[UsageData]) -> int: + return sum( + data.flags + data.identities + data.traits + data.environment_document + for data in usage_data + ) + + +def _map_to_top_project_usage( + usage_data_by_project_id: dict[int, list[UsageData]], +) -> list[ProjectUsage]: + rows = [ + ProjectUsage( + project_id=project_id, + api_call_count=_sum_api_calls(usage_data), + ) + for project_id, usage_data in usage_data_by_project_id.items() + ] + # Highest usage first + rows.sort(key=lambda row: row.api_call_count, reverse=True) + return rows[:MAX_PROJECT_USAGE_ROWS] + + +def _map_to_api_call_breakdown( + usage_data: list[UsageData], +) -> ApiCallBreakdown: + return ApiCallBreakdown( + flags=sum(data.flags for data in usage_data), + identities=sum(data.identities for data in usage_data), + traits=sum(data.traits for data in usage_data), + environment_documents=sum(data.environment_document for data in usage_data), + ) + + +def _get_usage_snapshot(organisation: Organisation) -> UsageSnapshot: + hour_end = timezone.now().replace(minute=0, second=0, microsecond=0) + hour_start = hour_end - timedelta(hours=24) + seat_count = organisation.num_seats + instance_version = get_version() + usage_data = get_usage_data_for_window(organisation, hour_start, hour_end) + usage_data_by_project_id = { + project.id: get_usage_data_for_window( + organisation, hour_start, hour_end, project_id=project.id + ) + for project in organisation.projects.all() + } + + # No data access past this point! + + return UsageSnapshot( + timestamp=hour_start, + seat_count=seat_count, + api_call_total=_sum_api_calls(usage_data), + api_call_breakdown=_map_to_api_call_breakdown(usage_data), + project_count=len(usage_data_by_project_id), + instance_version=instance_version, + project_usage=_map_to_top_project_usage(usage_data_by_project_id), + ) diff --git a/api/telemetry/tasks.py b/api/telemetry/tasks.py new file mode 100644 index 000000000000..63841b937796 --- /dev/null +++ b/api/telemetry/tasks.py @@ -0,0 +1,10 @@ +from datetime import timedelta + +from task_processor.decorators import register_recurring_task + +from telemetry.services import push_usage_snapshots + + +@register_recurring_task(run_every=timedelta(hours=24)) +def push_usage() -> None: + push_usage_snapshots() diff --git a/api/tests/unit/organisations/usage_reporting/__init__.py b/api/tests/unit/organisations/usage_reporting/__init__.py deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/api/tests/unit/organisations/usage_reporting/test_mappers.py b/api/tests/unit/organisations/usage_reporting/test_mappers.py deleted file mode 100644 index 8a3cb1c2ffcd..000000000000 --- a/api/tests/unit/organisations/usage_reporting/test_mappers.py +++ /dev/null @@ -1,113 +0,0 @@ -from datetime import datetime, timezone - -import pytest -from pytest_mock import MockerFixture - -from app_analytics.dataclasses import UsageData -from organisations.models import Organisation -from organisations.usage_reporting import mappers -from organisations.usage_reporting.dataclasses import ( - ApiCallBreakdown, - ProjectUsage, - UsageSnapshot, -) -from organisations.usage_reporting.mappers import ( - map_organisation_to_usage_snapshot, -) -from projects.models import Project - - -@pytest.mark.freeze_time("2026-06-18T09:30:00+00:00") -def test_map_organisation_to_usage_snapshot__with_usage__returns_populated_snapshot( - organisation: Organisation, - project: Project, - mocker: MockerFixture, -) -> None: - # Given - mocker.patch.object(mappers, "get_version", return_value="2.142.3") - mocker.patch.object( - mappers, - "get_usage_data_for_window", - return_value=[ - UsageData( - day=None, # type: ignore[arg-type] - flags=1, - identities=2, - traits=3, - environment_document=4, - ) - ], - ) - - # When - snapshot = map_organisation_to_usage_snapshot(organisation) - - # Then - assert snapshot == UsageSnapshot( - timestamp=datetime(2026, 6, 18, 8, 0, 0, tzinfo=timezone.utc), - seat_count=organisation.num_seats, - api_call_total=10, - api_call_breakdown=ApiCallBreakdown( - flags=1, identities=2, traits=3, environment_documents=4 - ), - project_count=1, - instance_version="2.142.3", - project_usage=[ProjectUsage(project_id=project.id, api_call_count=10)], - ) - - -@pytest.mark.freeze_time("2026-06-18T09:30:00+00:00") -def test_map_organisation_to_usage_snapshot__no_analytics__returns_zeroed_snapshot( - organisation: Organisation, - project: Project, - mocker: MockerFixture, -) -> None: - # Given - mocker.patch.object(mappers, "get_version", return_value="2.142.3") - mocker.patch.object(mappers, "get_usage_data_for_window", return_value=[]) - - # When - snapshot = map_organisation_to_usage_snapshot(organisation) - - # Then - assert snapshot == UsageSnapshot( - timestamp=datetime(2026, 6, 18, 8, 0, 0, tzinfo=timezone.utc), - seat_count=organisation.num_seats, - api_call_total=0, - api_call_breakdown=ApiCallBreakdown( - flags=0, identities=0, traits=0, environment_documents=0 - ), - project_count=1, - instance_version="2.142.3", - project_usage=[ProjectUsage(project_id=project.id, api_call_count=0)], - ) - - -def test_map_organisation_to_usage_snapshot__excess_projects__keeps_highest_usage( - organisation: Organisation, - project: Project, - project_two: Project, - mocker: MockerFixture, -) -> None: - # Given - project_two has more usage than project - usage_by_project = { - project.id: [UsageData(day=None, flags=5)], # type: ignore[arg-type] - project_two.id: [UsageData(day=None, flags=100)], # type: ignore[arg-type] - } - mocker.patch.object(mappers, "get_version", return_value="2.142.3") - mocker.patch.object( - mappers, - "get_usage_data_for_window", - side_effect=lambda org, start, stop, project_id=None: usage_by_project.get( - project_id, [] - ), - ) - mocker.patch.object(mappers, "MAX_PROJECT_USAGE_ROWS", 1) - - # When - snapshot = map_organisation_to_usage_snapshot(organisation) - - # Then - only the highest-usage project survives the cap - assert snapshot.project_usage == [ - ProjectUsage(project_id=project_two.id, api_call_count=100) - ] diff --git a/api/tests/unit/organisations/usage_reporting/test_services.py b/api/tests/unit/organisations/usage_reporting/test_services.py deleted file mode 100644 index f27cbd1e003b..000000000000 --- a/api/tests/unit/organisations/usage_reporting/test_services.py +++ /dev/null @@ -1,237 +0,0 @@ -import json -from datetime import datetime, timezone - -import pytest -from django.conf import settings as django_settings -from pytest_django.fixtures import SettingsWrapper -from pytest_mock import MockerFixture -from pytest_structlog import StructuredLogCapture - -from organisations.models import Organisation -from organisations.usage_reporting.dataclasses import ( - ApiCallBreakdown, - ProjectUsage, - UsageSnapshot, -) -from organisations.usage_reporting.services import ( - get_licensed_organisations, - push_snapshot, - push_usage_snapshots, -) - - -@pytest.fixture -def snapshot() -> UsageSnapshot: - return UsageSnapshot( - timestamp=datetime(2026, 6, 18, 8, 0, 0, tzinfo=timezone.utc), - seat_count=3, - api_call_total=10, - api_call_breakdown=ApiCallBreakdown( - flags=1, identities=2, traits=3, environment_documents=4 - ), - project_count=1, - instance_version="2.142.3", - project_usage=[ProjectUsage(project_id=1, api_call_count=10)], - ) - - -def test_get_licensed_organisations__licensing_not_installed__returns_empty( - settings: SettingsWrapper, -) -> None: - # Given - settings.LICENSING_INSTALLED = False - - # When / Then - assert get_licensed_organisations() == [] - - -@pytest.mark.skipif( - not django_settings.LICENSING_INSTALLED, - reason="the licence relation requires the optional licensing package", -) -def test_get_licensed_organisations__organisation_without_licence__excluded( - settings: SettingsWrapper, - organisation: Organisation, -) -> None: - # Given - settings.LICENSING_INSTALLED = True - - # When / Then - the unlicensed organisation is filtered out - assert get_licensed_organisations() == [] - - -@pytest.mark.parametrize( - "status_code, event, level", - [ - (201, "snapshot.pushed", "info"), - (200, "snapshot.pushed", "info"), - (400, "snapshot.push_failed", "warning"), - (401, "snapshot.push_failed", "warning"), - (403, "snapshot.push_failed", "warning"), - (429, "snapshot.push_failed", "warning"), - (500, "snapshot.push_failed", "warning"), - (503, "snapshot.push_failed", "warning"), - (418, "snapshot.push_failed", "warning"), - ], -) -def test_push_snapshot__status_code__logs_expected_event( - mocker: MockerFixture, - log: StructuredLogCapture, - snapshot: UsageSnapshot, - status_code: int, - event: str, - level: str, -) -> None: - # Given - mocked_post = mocker.patch("organisations.usage_reporting.services.requests.post") - mocked_post.return_value.status_code = status_code - mocked_post.return_value.ok = status_code < 400 - - # When - push_snapshot( - base_url="https://cp.example.com/", - snapshot=snapshot, - signature_b64="c2ln", - ) - - # Then - assert log.has(event, level=level, status_code=status_code) - - -def test_push_snapshot__valid_snapshot__sends_bearer_authed_post( - mocker: MockerFixture, - snapshot: UsageSnapshot, -) -> None: - # Given - mocked_post = mocker.patch("organisations.usage_reporting.services.requests.post") - mocked_post.return_value.status_code = 201 - signature_b64 = "++++ABE=" - - # When - push_snapshot( - base_url="https://cp.example.com/", - snapshot=snapshot, - signature_b64=signature_b64, - ) - - # Then - mocked_post.assert_called_once() - (url,), kwargs = mocked_post.call_args - assert url == "https://cp.example.com/v1/public/usage" - # The signature's raw bytes, unpadded base64url-encoded for the wire. - assert kwargs["headers"]["Authorization"] == "Bearer ----ABE" - assert kwargs["headers"]["Content-Type"] == "application/json" - assert json.loads(kwargs["data"]) == { - "timestamp": "2026-06-18T08:00:00Z", - "seat_count": 3, - "api_call_total": 10, - "api_call_breakdown": { - "flags": 1, - "identities": 2, - "traits": 3, - "environment_documents": 4, - }, - "project_count": 1, - "instance_version": "2.142.3", - "project_usage": [{"project_id": 1, "api_call_count": 10}], - } - - -def test_push_usage_snapshots__control_plane_url_unset__no_op( - settings: SettingsWrapper, - mocker: MockerFixture, -) -> None: - # Given - settings.CONTROL_PLANE_URL = None - mocked_get_orgs = mocker.patch( - "organisations.usage_reporting.services.get_licensed_organisations" - ) - mocked_push = mocker.patch("organisations.usage_reporting.services.push_snapshot") - - # When - push_usage_snapshots() - - # Then - mocked_get_orgs.assert_not_called() - mocked_push.assert_not_called() - - -def test_push_usage_snapshots__no_licensed_organisations__no_op( - settings: SettingsWrapper, - mocker: MockerFixture, -) -> None: - # Given - settings.CONTROL_PLANE_URL = "https://cp.example.com" - mocker.patch( - "organisations.usage_reporting.services.get_licensed_organisations", - return_value=[], - ) - mocked_push = mocker.patch("organisations.usage_reporting.services.push_snapshot") - - # When - push_usage_snapshots() - - # Then - mocked_push.assert_not_called() - - -def test_push_usage_snapshots__licensed_organisations__pushes_each( - settings: SettingsWrapper, - mocker: MockerFixture, - snapshot: UsageSnapshot, -) -> None: - # Given - settings.CONTROL_PLANE_URL = "https://cp.example.com" - org_one = mocker.Mock(id=1, licence=mocker.Mock(signature="sig-1")) - org_two = mocker.Mock(id=2, licence=mocker.Mock(signature="sig-2")) - mocker.patch( - "organisations.usage_reporting.services.get_licensed_organisations", - return_value=[org_one, org_two], - ) - mocker.patch( - "organisations.usage_reporting.services.map_organisation_to_usage_snapshot", - return_value=snapshot, - ) - mocked_push = mocker.patch("organisations.usage_reporting.services.push_snapshot") - - # When - push_usage_snapshots() - - # Then - assert mocked_push.call_count == 2 - mocked_push.assert_any_call( - base_url="https://cp.example.com", snapshot=snapshot, signature_b64="sig-1" - ) - mocked_push.assert_any_call( - base_url="https://cp.example.com", snapshot=snapshot, signature_b64="sig-2" - ) - - -def test_push_usage_snapshots__one_organisation_raises__continues( - settings: SettingsWrapper, - mocker: MockerFixture, - log: StructuredLogCapture, - snapshot: UsageSnapshot, -) -> None: - # Given - settings.CONTROL_PLANE_URL = "https://cp.example.com" - org_one = mocker.Mock(id=1, licence=mocker.Mock(signature="sig-1")) - org_two = mocker.Mock(id=2, licence=mocker.Mock(signature="sig-2")) - mocker.patch( - "organisations.usage_reporting.services.get_licensed_organisations", - return_value=[org_one, org_two], - ) - mocker.patch( - "organisations.usage_reporting.services.map_organisation_to_usage_snapshot", - side_effect=[ValueError("boom"), snapshot], - ) - mocked_push = mocker.patch("organisations.usage_reporting.services.push_snapshot") - - # When - push_usage_snapshots() - - # Then - first organisation failed (logged) but second still pushed - assert log.has("snapshot.errored", level="error") - mocked_push.assert_called_once_with( - base_url="https://cp.example.com", snapshot=snapshot, signature_b64="sig-2" - ) diff --git a/api/tests/unit/organisations/usage_reporting/test_tasks.py b/api/tests/unit/organisations/usage_reporting/test_tasks.py deleted file mode 100644 index 6c80ab9b5bf8..000000000000 --- a/api/tests/unit/organisations/usage_reporting/test_tasks.py +++ /dev/null @@ -1,16 +0,0 @@ -from pytest_mock import MockerFixture - -from organisations.tasks import push_usage_to_control_plane - - -def test_push_usage_to_control_plane__called__delegates_to_service( - mocker: MockerFixture, -) -> None: - # Given - mock_push = mocker.patch("organisations.tasks.push_usage_snapshots") - - # When - push_usage_to_control_plane() - - # Then - assert mock_push.call_args_list == [mocker.call()] diff --git a/api/organisations/usage_reporting/__init__.py b/api/tests/unit/telemetry/control_plane/__init__.py similarity index 100% rename from api/organisations/usage_reporting/__init__.py rename to api/tests/unit/telemetry/control_plane/__init__.py diff --git a/api/tests/unit/telemetry/control_plane/test_client.py b/api/tests/unit/telemetry/control_plane/test_client.py new file mode 100644 index 000000000000..cb0cf3eee4dd --- /dev/null +++ b/api/tests/unit/telemetry/control_plane/test_client.py @@ -0,0 +1,35 @@ +from datetime import datetime, timezone + +from requests_mock import Mocker as RequestsMocker + +from telemetry.control_plane.client import post_usage_snapshot +from telemetry.dataclasses import ApiCallBreakdown, UsageSnapshot + + +def test_post_usage_snapshot__base64_signature__sends_url_safe_unpadded_bearer_token( + requests_mock: RequestsMocker, +) -> None: + # Given + requests_mock.post("https://cp.example.com/v1/public/usage", status_code=200) + snapshot = UsageSnapshot( + timestamp=datetime(2026, 1, 14, tzinfo=timezone.utc), + seat_count=1, + api_call_total=0, + api_call_breakdown=ApiCallBreakdown( + flags=0, identities=0, traits=0, environment_documents=0 + ), + project_count=0, + instance_version="1.2.3", + project_usage=[], + ) + + # When + post_usage_snapshot( + base_url="https://cp.example.com", + snapshot=snapshot, + signature_b64="+/8=", + ) + + # Then + assert requests_mock.last_request + assert requests_mock.last_request.headers["Authorization"] == "Bearer -_8" diff --git a/api/tests/unit/telemetry/test_services.py b/api/tests/unit/telemetry/test_services.py new file mode 100644 index 000000000000..489b1764aa35 --- /dev/null +++ b/api/tests/unit/telemetry/test_services.py @@ -0,0 +1,297 @@ +from datetime import datetime +from unittest.mock import Mock + +from freezegun import freeze_time +from pytest_django.fixtures import SettingsWrapper +from pytest_mock import MockerFixture +from pytest_structlog import StructuredLogCapture +from requests_mock import Mocker as RequestsMocker + +from app_analytics.dataclasses import UsageData +from telemetry.services import push_usage_snapshots + +USAGE_URL = "https://cp.example.com/v1/public/usage" + + +def fake_usage_data(total: bool = False) -> UsageData: + return UsageData( + day=datetime.now(), + flags=10, + traits=10, + identities=10, + environment_document=10, + ) + + +def _make_organisation( + mocker: MockerFixture, organisation_id: int, project_ids: list[int] +) -> Mock: + organisation: Mock = mocker.Mock( + id=organisation_id, num_seats=10, licence=mocker.Mock(signature="sig-1") + ) + organisation.projects.all.return_value = [ + mocker.Mock(id=project_id) for project_id in project_ids + ] + return organisation + + +def _enable_telemetry(settings: SettingsWrapper) -> None: + settings.ENABLE_TELEMETRY = True + settings.CONTROL_PLANE_URL = "https://cp.example.com" + + +def test_push_usage_snapshots__no_telemetry__no_op( + settings: SettingsWrapper, + mocker: MockerFixture, + log: StructuredLogCapture, +) -> None: + # Given + settings.ENABLE_TELEMETRY = False + mocked_post = mocker.patch("telemetry.services.post_usage_snapshot") + + # When + push_usage_snapshots() + + # Then + mocked_post.assert_not_called() + assert log.events == [ + {"event": "run.skipped", "level": "debug", "reason": "telemetry_disabled"} + ] + + +def test_push_usage_snapshots__url_unset__no_op( + settings: SettingsWrapper, + mocker: MockerFixture, + log: StructuredLogCapture, +) -> None: + # Given + settings.ENABLE_TELEMETRY = True + settings.CONTROL_PLANE_URL = None + mocked_post = mocker.patch("telemetry.services.post_usage_snapshot") + + # When + push_usage_snapshots() + + # Then + mocked_post.assert_not_called() + assert log.events == [ + {"event": "run.skipped", "level": "debug", "reason": "control_plane_url_unset"} + ] + + +def test_push_usage_snapshots__no_licensed_organisations__no_op( + settings: SettingsWrapper, + mocker: MockerFixture, + log: StructuredLogCapture, +) -> None: + # Given + _enable_telemetry(settings) + mocked_post = mocker.patch("telemetry.services.post_usage_snapshot") + mocker.patch("telemetry.services._get_licensed_organisations", return_value=[]) + + # When + push_usage_snapshots() + + # Then + mocked_post.assert_not_called() + assert log.events == [ + { + "event": "run.skipped", + "level": "debug", + "reason": "no_licensed_organisations", + } + ] + + +@freeze_time("2026-01-14T09:30:00Z") +def test_push_usage_snapshots__licensed_organisation__pushes_snapshot( + settings: SettingsWrapper, + mocker: MockerFixture, + requests_mock: RequestsMocker, + log: StructuredLogCapture, +) -> None: + # Given + _enable_telemetry(settings) + org = mocker.Mock(id=1, num_seats=10, licence=mocker.Mock(signature="sig-1")) + project = mocker.Mock(id=1) + org.projects.all.return_value = [project] + mocker.patch("telemetry.services.get_version", return_value="2.200.0") + mocker.patch( + "telemetry.services._get_licensed_organisations", + return_value=[org], + ) + mocker.patch( + "telemetry.services.get_usage_data_for_window", + return_value=[fake_usage_data()], + ) + USAGE_ENDPOINT_PATH = "/v1/public/usage" + url = f"{settings.CONTROL_PLANE_URL.rstrip('/')}{USAGE_ENDPOINT_PATH}" + requests_mock.post(url, status_code=200) + + # When + push_usage_snapshots() + + # Then + assert log.events == [ + { + "status_code": 200, + "event": "snapshot.pushed", + "organisation__id": 1, + "level": "info", + } + ] + assert requests_mock.last_request + assert requests_mock.last_request.json() == { + "timestamp": "2026-01-13T09:00:00Z", + "seat_count": 10, + "api_call_total": 40, + "api_call_breakdown": { + "flags": 10, + "identities": 10, + "traits": 10, + "environment_documents": 10, + }, + "project_count": 1, + "instance_version": "2.200.0", + "project_usage": [{"project_id": 1, "api_call_count": 40}], + } + + +def test_push_usage_snapshots__control_plane_rejects__logs_push_failed( + settings: SettingsWrapper, + mocker: MockerFixture, + requests_mock: RequestsMocker, + log: StructuredLogCapture, +) -> None: + # Given + _enable_telemetry(settings) + mocker.patch( + "telemetry.services._get_licensed_organisations", + return_value=[_make_organisation(mocker, 1, [1])], + ) + mocker.patch( + "telemetry.services.get_usage_data_for_window", + return_value=[fake_usage_data()], + ) + requests_mock.post(USAGE_URL, status_code=500) + + # When + push_usage_snapshots() + + # Then + assert log.events == [ + { + "status_code": 500, + "event": "snapshot.push_failed", + "organisation__id": 1, + "level": "warning", + } + ] + + +def test_push_usage_snapshots__one_organisation_errors__logs_error_and_pushes_others( + settings: SettingsWrapper, + mocker: MockerFixture, + requests_mock: RequestsMocker, + log: StructuredLogCapture, +) -> None: + # Given + _enable_telemetry(settings) + mocker.patch( + "telemetry.services._get_licensed_organisations", + return_value=[ + _make_organisation(mocker, 1, [1]), + _make_organisation(mocker, 2, [2]), + ], + ) + + def get_usage_data_for_window( + organisation: Mock, *args: object, **kwargs: object + ) -> list[UsageData]: + if organisation.id == 1: + raise RuntimeError("Analytics database unavailable") + return [fake_usage_data()] + + mocker.patch( + "telemetry.services.get_usage_data_for_window", + side_effect=get_usage_data_for_window, + ) + requests_mock.post(USAGE_URL, status_code=200) + + # When + push_usage_snapshots() + + # Then + assert requests_mock.call_count == 1 + assert log.events == [ + { + "event": "snapshot.errored", + "organisation__id": 1, + "level": "error", + "exc_info": True, + }, + { + "status_code": 200, + "event": "snapshot.pushed", + "organisation__id": 2, + "level": "info", + }, + ] + + +def test_push_usage_snapshots__more_projects_than_row_cap__sends_highest_usage_only( + settings: SettingsWrapper, + mocker: MockerFixture, + requests_mock: RequestsMocker, +) -> None: + # Given + _enable_telemetry(settings) + mocker.patch("telemetry.services.MAX_PROJECT_USAGE_ROWS", 1) + mocker.patch( + "telemetry.services._get_licensed_organisations", + return_value=[_make_organisation(mocker, 1, [1, 2])], + ) + flags_by_project_id = {None: 10, 1: 3, 2: 7} + + def get_usage_data_for_window( + *args: object, project_id: int | None = None + ) -> list[UsageData]: + return [UsageData(day=datetime.now(), flags=flags_by_project_id[project_id])] + + mocker.patch( + "telemetry.services.get_usage_data_for_window", + side_effect=get_usage_data_for_window, + ) + requests_mock.post(USAGE_URL, status_code=200) + + # When + push_usage_snapshots() + + # Then + assert requests_mock.last_request + body = requests_mock.last_request.json() + assert body["project_count"] == 2 + assert body["project_usage"] == [{"project_id": 2, "api_call_count": 7}] + + +def test_push_usage_snapshots__licensing_not_installed__skips_run( + settings: SettingsWrapper, + requests_mock: RequestsMocker, + log: StructuredLogCapture, +) -> None: + # Given + _enable_telemetry(settings) + settings.LICENSING_INSTALLED = False + + # When + push_usage_snapshots() + + # Then + assert not requests_mock.called + assert log.events == [ + { + "event": "run.skipped", + "level": "debug", + "reason": "no_licensed_organisations", + } + ] diff --git a/api/tests/unit/telemetry/test_tasks.py b/api/tests/unit/telemetry/test_tasks.py new file mode 100644 index 000000000000..3f231b3f6a97 --- /dev/null +++ b/api/tests/unit/telemetry/test_tasks.py @@ -0,0 +1,16 @@ +from pytest_mock import MockerFixture + +from telemetry.tasks import push_usage + + +def test_push_usage__called__pushes_usage_snapshots( + mocker: MockerFixture, +) -> None: + # Given + mock_push_usage_snapshots = mocker.patch("telemetry.tasks.push_usage_snapshots") + + # When + push_usage() + + # Then + mock_push_usage_snapshots.assert_called_once_with() From c7c4fedb88d98adb2f89c5077123ff22e488c6e6 Mon Sep 17 00:00:00 2001 From: "flagsmith-engineering[bot]" Date: Thu, 19 Nov 2026 11:55:13 +0000 Subject: [PATCH 2/5] chore: Update documentation artefacts --- .../observability/_events-catalogue.md | 85 ++++++++++--------- 1 file changed, 43 insertions(+), 42 deletions(-) diff --git a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md index 3a2cd944daea..1c6e534cd328 100644 --- a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md +++ b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md @@ -42,7 +42,7 @@ Attributes: ### `api_usage.overage.charge_failed` Logged at `exception` from: - - `api/organisations/tasks.py:331` + - `api/organisations/tasks.py:325` Attributes: - `api_overage` @@ -51,7 +51,7 @@ Attributes: ### `api_usage.overage.charged` Logged at `info` from: - - `api/organisations/tasks.py:338` + - `api/organisations/tasks.py:332` Attributes: - `api_overage` @@ -61,7 +61,7 @@ Attributes: ### `api_usage.overage.missing_allowance` Logged at `error` from: - - `api/organisations/tasks.py:229` + - `api/organisations/tasks.py:223` Attributes: - `organisation.id` @@ -69,7 +69,7 @@ Attributes: ### `api_usage.overage.missing_subscription_id` Logged at `error` from: - - `api/organisations/tasks.py:310` + - `api/organisations/tasks.py:304` Attributes: - `organisation.id` @@ -77,8 +77,8 @@ Attributes: ### `api_usage.overage.skipped` Logged at `info` from: - - `api/organisations/tasks.py:256` - - `api/organisations/tasks.py:280` + - `api/organisations/tasks.py:250` + - `api/organisations/tasks.py:274` Attributes: - `allowed_30d_api_calls` @@ -90,7 +90,7 @@ Attributes: ### `api_usage.overage.unknown_plan` Logged at `error` from: - - `api/organisations/tasks.py:324` + - `api/organisations/tasks.py:318` Attributes: - `organisation.id` @@ -99,7 +99,7 @@ Attributes: ### `api_usage.restriction.applied` Logged at `info` from: - - `api/organisations/tasks.py:466` + - `api/organisations/tasks.py:460` Attributes: - `allowed_30d_api_calls` @@ -111,7 +111,7 @@ Attributes: ### `api_usage.restriction.failed` Logged at `exception` from: - - `api/organisations/tasks.py:400` + - `api/organisations/tasks.py:394` Attributes: - `organisation.id` @@ -119,7 +119,7 @@ Attributes: ### `api_usage.restriction.skipped` Logged at `info` from: - - `api/organisations/tasks.py:447` + - `api/organisations/tasks.py:441` Attributes: - `allowed_30d_api_calls` @@ -940,6 +940,39 @@ Attributes: - `feature_name` - `sentry_action` +### `telemetry.control_plane.client.snapshot.push_failed` + +Logged at `warning` from: + - `api/telemetry/control_plane/client.py:40` + +Attributes: + - `status_code` + +### `telemetry.control_plane.client.snapshot.pushed` + +Logged at `info` from: + - `api/telemetry/control_plane/client.py:38` + +Attributes: + - `status_code` + +### `telemetry.services.run.skipped` + +Logged at `debug` from: + - `api/telemetry/services.py:21` + - `api/telemetry/services.py:24` + - `api/telemetry/services.py:27` + +Attributes: + - `reason` + +### `telemetry.services.snapshot.errored` + +Logged at `exception` from: + - `api/telemetry/services.py:39` + +Attributes: + ### `trust_relationships.created` Logged at `info` from: @@ -994,38 +1027,6 @@ Attributes: - `trust_relationship.id` - `trust_relationship.issuer` -### `usage_reporting.run.skipped` - -Logged at `debug` from: - - `api/organisations/usage_reporting/services.py:60` - - `api/organisations/usage_reporting/services.py:63` - -Attributes: - - `reason` - -### `usage_reporting.snapshot.errored` - -Logged at `exception` from: - - `api/organisations/usage_reporting/services.py:75` - -Attributes: - -### `usage_reporting.snapshot.push_failed` - -Logged at `warning` from: - - `api/organisations/usage_reporting/services.py:55` - -Attributes: - - `status_code` - -### `usage_reporting.snapshot.pushed` - -Logged at `info` from: - - `api/organisations/usage_reporting/services.py:53` - -Attributes: - - `status_code` - ### `warehouse.connection.connected` Logged at `info` from: From 68317c1cde7eace12f5c1609281e5d7714213808 Mon Sep 17 00:00:00 2001 From: "flagsmith-engineering[bot]" Date: Thu, 19 Nov 2026 15:22:28 +0000 Subject: [PATCH 3/5] chore: Update documentation artefacts --- .../observability/_events-catalogue.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md index 1c6e534cd328..c0b037af17e7 100644 --- a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md +++ b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md @@ -130,8 +130,8 @@ Attributes: Logged at `warning` from: - `api/app_analytics/analytics_db_service.py:83` - - `api/app_analytics/analytics_db_service.py:230` - - `api/app_analytics/analytics_db_service.py:321` + - `api/app_analytics/analytics_db_service.py:240` + - `api/app_analytics/analytics_db_service.py:331` Attributes: - `details` From 7929a36f35d41359cfc37c85dbe6b16728c9f2ad Mon Sep 17 00:00:00 2001 From: German Garces Date: Thu, 19 Nov 2026 16:25:48 +0100 Subject: [PATCH 4/5] refactor(Telemetry): Drop analytics grouping from this PR --- api/app_analytics/analytics_db_service.py | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/api/app_analytics/analytics_db_service.py b/api/app_analytics/analytics_db_service.py index f31ee6a0122b..f007e17770de 100644 --- a/api/app_analytics/analytics_db_service.py +++ b/api/app_analytics/analytics_db_service.py @@ -188,25 +188,15 @@ def get_usage_data_from_local_db_for_window( date_start: datetime, date_stop: datetime, project_id: int | None = None, - group_by: UsageGroupByType | None = None, ) -> list[UsageData]: - project_ids_by_environment_id = _get_project_ids_by_environment_id_for_org( - organisation - ) qs = _get_api_usage_bucket_qs( - project_ids_by_environment_id, + _get_project_ids_by_environment_id_for_org(organisation), project_id=project_id, ).filter( created_at__gte=date_start, created_at__lt=date_stop, ) - if not group_by: - return _aggregate_buckets(qs) - - return map_annotated_api_usage_buckets_to_usage_data( - _group_bucket(row, project_ids_by_environment_id, group_by) - for row in _annotate_buckets(qs, "environment_id") - ) + return _aggregate_buckets(qs) def get_usage_data_for_window( From 688059a57dc69f5938062f88967e705ad2009e0a Mon Sep 17 00:00:00 2001 From: "flagsmith-engineering[bot]" Date: Thu, 19 Nov 2026 15:27:51 +0000 Subject: [PATCH 5/5] chore: Update documentation artefacts --- .../observability/_events-catalogue.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md index c0b037af17e7..1c6e534cd328 100644 --- a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md +++ b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md @@ -130,8 +130,8 @@ Attributes: Logged at `warning` from: - `api/app_analytics/analytics_db_service.py:83` - - `api/app_analytics/analytics_db_service.py:240` - - `api/app_analytics/analytics_db_service.py:331` + - `api/app_analytics/analytics_db_service.py:230` + - `api/app_analytics/analytics_db_service.py:321` Attributes: - `details`