feat: Backend for SDK metrics

[khvn26]

Thanks for submitting a PR! Please check the boxes below:

• I have added information to docs/ if required so people know about the feature!
• I have filled in the "Changes" section below?
• I have filled in the "How did you test this code" section below?
• I have used a Conventional Commit title for this Pull Request

Changes

Closes #5581.

Contributes to #2479.

This PR adds support for optional header tracking in the backend. It adds extensible, fully typed mechanism to support other optional labels for analytics in the future. The usage data and feature evaluation data routes are updated to return labeled data buckets. Additionally, numerous typing and code structure improvements are introduced to the analytics-related code base.

SDK API

All tracked SDK APIs now expect the following optional headers, translated to labels written to PostgreSQL or InfluxDB usage and evaluation data buckets:

• Flagsmith-Application-Name header: client_application_name label
• Flagsmith-Application-Version header: client_application_version label
• User-Agent header: user_agent label

Relevant caches and tasks are changed to properly compact the raw data, producing buckets with unique label sets.

Management API

The following API routes are updated to support labels:

• /api/v1/organisations/{organisation_pk}/usage-data/
• /api/v1/projects/{project_pk}/features/{id}/evaluation-data/

Previously, these routes were returning one bucket per day. Now, multiple buckets can be attributed to the same day, as long as they have different unique label sets. The label sets are returned under the label key for each bucket:

// GET /api/v1/projects/1/features/19/evaluation-data/

[
    {
        "day": "2025-07-09",
        "count": 674,
        "labels": {
            "client_application_name": null,
            "client_application_version": null,
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36"
        }
    },
    {
        "day": "2025-07-09",
        "count": 62,
        "labels": {
            "client_application_name": null,
            "client_application_version": null,
            "user_agent": "python-requests/2.32.3"
        }
    }
]

Both of them now accept new query parameters:

• client_application_name
• client_application_version
• user_agent

to allow bucket filtering by label.

The feature is hidden behind the "sdk_metrics_labels" flag.

Task processing

Due to incompatible signature change, the track_feature_evaluation is decommissioned in favour of the new track_feature_evaluations_by_environment task, which now supports labels included as part of feature evaluation data.

How did you test this code?

Unit tests have been added and updated to reflect new behaviour. Manually with local PostgreSQL storage. Additional tests will be conducted in staging against InfluxDB Cloud to measure the performance.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

3 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
docs	⬜️ Ignored (Inspect)	Visit Preview		Jul 21, 2025 4:57pm
flagsmith-frontend-preview	⬜️ Ignored (Inspect)	Visit Preview		Jul 21, 2025 4:57pm
flagsmith-frontend-staging	⬜️ Ignored (Inspect)	Visit Preview		Jul 21, 2025 4:57pm

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.81%. Comparing base (4b676b5) to head (1b608d4).
Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5623      +/-   ##
==========================================
+ Coverage   97.77%   97.81%   +0.04%     
==========================================
  Files        1255     1257       +2     
  Lines       44420    44586     +166     
==========================================
+ Hits        43430    43612     +182     
+ Misses        990      974      -16     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Not enough context to validate approval.

[khvn26]

Added "sdk_metrics_labels" flag, so this can be merged after approval.

CC @matthewelwell @emyller

[matthewelwell]

This might cause an issue in EE repo for oracle?

[khvn26]

Do we have to have settings/common.py identical to the open source one?

[matthewelwell]

It seems to me like we should standardise on one approach, and we can always filter events out that we don't care about on the other end, right?

[khvn26]

It seems to me like we should standardise on one approach, and we can always filter events out that we don't care about on the other end, right?

Switched to structlog in 34de05e.