Flagsmith Flag Analytics 实战指南：从 SDK 评估计数到仪表盘可视化

• 后端
• 前端

Flagsmith 的 Flag Analytics（Flag 分析）功能可以精确记录每个 feature flag 在 SDK 中被评估的次数与频率，帮助团队在清理下线 flag、定位重复评估等集成问题时做出数据驱动的决策。本文以仓库内 flag-analytics.md 为核心，结合 API 源码与前端实现，完整讲解该功能的开启方式、端到端数据流转、后端存储与查询机制，以及如何利用它安全地移除 flag。

什么是 Flag Analytics

Flag Analytics 允许你追踪单个 feature flag 在 Flagsmith SDK 中究竟被评估了多少次。每一次调用诸如flagsmith.hasFeature("myCoolFeature")的评估方法，都会在本地累积一条"flag 名称 + 评估次数"的记录，随后周期性地批量上报到 Flagsmith API。

这项数据在实际工程中主要有两类典型用途：

• 安全清理 flag：功能上线并稳定运行后，flag 及其评估代码通常可以从代码库和平台上移除。移除前你希望确认：代码中所有对该 flag 的引用都已删除、从 Flagsmith 中删除该 flag 本身不会引发任何意外问题。Flag Analytics 能提供"该 flag 最近是否仍被评估、评估频率如何"的客观证据。
• 排查集成问题：代码中偶尔会混入导致 flag 被重复无意义评估的逻辑错误（例如在循环或渲染函数内反复调用hasFeature）。Analytics 图表上异常陡峭的评估曲线可以帮你快速定位这类问题。

在 Dashboard 中查看 Flag Analytics

查看某个 flag 的分析数据非常简单：

1. 在 Flagsmith 中进入目标环境（Environment）；
2. 找到并点击该 flag，进入 flag 编辑页；
3. 切换到Usage标签页，Analytics 图表与Code References（代码引用）会并列展示。

前端中，Usage 标签页由 UsageTab.tsx 渲染，它按顺序组合了FeatureAnalytics组件与FeatureCodeReferencesContainer组件；Analytics 图表本体实现在 FeatureAnalytics.tsx 中，标题为 "Flag events for last 30 days"（最近 30 天的 flag 事件），按天聚合、以柱状图展示。

图表上方提供了两个实用筛选器：

• 环境选择器：通过EnvironmentTagSelect选择一个或多个环境，数据按环境分组绘制多条柱状序列；
• SDK 筛选：基于 SDK 上报的可选标签（Filter by SDK），当后端返回带标签（labelled）数据时可用，用于按 SDK 种类拆分评估量。

需要特别注意的是官方提示：Flag Analytics 数据在采集完成后，通常需要 30 分钟到 1 小时才会在 Dashboard 中可见。这并非实时展示，其背后存在缓存批量刷新与数据分桶（bucket）聚合的时延（详见下文"后端处理链路"）。FeatureAnalytics.tsx 的页面提示信息与之一致。若所选环境在窗口期内没有任何评估数据，页面会显示 "No analytics data" 的空状态。

开启 Flag Analytics（SDK 初始化）

Flag Analytics 在 Flagsmith 的各 SDK 中默认是关闭的，需要你在初始化客户端时显式启用，具体参数随 SDK 不同而异。

以 JavaScript 家族 SDK（@flagsmith/flagsmith、@flagsmith/react-native）为例，在 javascript.md 的 Initialisation options 中，对应参数为enableAnalytics: boolean，默认值为false，其含义即"为getValue和hasFeature评估开启 flag analytics 上报"：

import flagsmith from '@flagsmith/flagsmith'; // 或 '@flagsmith/react-native' flagsmith.init({ environmentID: '<YOUR_CLIENT_SIDE_ENVIRONMENT_KEY>', // api: "http://localhost:8000/api/v1/" // 自托管时指向你的 API cacheFlags: true, // 将 flags 缓存到 localStorage enableAnalytics: true, // 关键：开启 flag analytics onChange: (oldFlags, params) => { const { isFromServer } = params; // 判断更新来自服务端还是本地缓存 if (flagsmith.hasFeature('my_cool_feature')) { myCoolFeature(); } }, });

同样的配置思路适用于服务端与其他语言的 SDK——各 SDK 文档中都有对应的初始化选项，开启后 SDK 才会开始本地计数与周期性上报。若保持默认关闭，则不会产生任何 analytics 上报流量。

工作原理：从 SDK 计数到 API 上报

官方文档对工作流程给出了清晰的描述，可拆解为三个环节：

1. 本地计数：每次 flag 在 SDK 内被评估（通常是调用flagsmith.hasFeature("myCoolFeature")这类方法），SDK 便维护一张"flag 名称 → 评估次数"的本地记录表；
2. 周期上报：每隔n秒（JS SDK 目前设置为 10 秒），SDK 将窗口期内被评估过的 flag 列表及其计数组装成一条消息发送给 Flagsmith API；
3. 静默优化：如果某个时间窗口内没有任何 flag 被评估，则不发送任何消息——避免无谓的请求流量。

这三点共同保证了该功能对业务请求路径影响极小：计数在 SDK 内存中完成，上报是批量、异步、低频的。

后端接收链路：V1 与 V2 上报端点

SDK 上报的消息由app_analytics应用处理。该应用同时承担 API 使用量统计与 flag 评估统计两类职责，其视图定义在 views.py：

• V1 端点SDKAnalyticsFlags：接收扁平结构{feature_name: evaluation_count}的 JSON 对象，对应路由POST /api/v1/analytics/flags/（见 v1.py）；
• V2 端点SDKAnalyticsFlagsV2：接收结构化数组，对应路由POST /api/v2/analytics/flags/（见 v2.py）。

V2 的请求体结构由 serializers.py 中的SDKAnalyticsFlagsSerializerDetail定义，每个元素包含四个字段：

{ "evaluations": [ { "feature_name": "my_cool_feature", "identity_identifier": "user-123", "enabled_when_evaluated": true, "count": 12 } ] }

两个端点均使用EnvironmentKeyAuthentication+EnvironmentKeyPermissions进行环境密钥认证（通过X-Environment-Key请求头），并显式设置throttle_classes = []不施加额外限流，保证高并发上报不被节流。

一个重要的服务端校验：序列化器在validate阶段会查询当前环境中实际存在的 flag 名称集合（即非 segment、非 identity 的默认 FeatureState 对应的 feature 名称），只保留名称匹配的上报条目，未知 flag 名会被静默丢弃。对应的单元测试覆盖了"无效 feature 名称只统计有效项"（见 test_unit_app_analytics_views.py）；V1 序列化器还会跳过count非整数的条目（如布尔值），非 dict 请求体直接返回 400。

后端处理链路：缓存、任务与数据分桶

上报数据并非立即落库或直写时序库，而是经过一条"内存缓存 → 异步任务 → 原始表 → 分桶表"的流水线，这正是"30 分钟到 1 小时可见"延迟的来源。

1. 内存缓存批量刷新

V1 端点将数据交给 FeatureEvaluationCache（FeatureEvaluationCache类）。它维护进程内字典，以(feature_name, environment_id, labels)为 key 累加计数，并通过线程锁保证并发安全。每隔settings.FEATURE_EVALUATION_CACHE_SECONDS秒（默认 60 秒，可用同名环境变量覆盖，见 common.py）触发一次_flush()，把累积数据通过 Celery 任务track_feature_evaluations_by_environment.delay(...)异步落库。

V2 端点则直接由序列化器按存储后端选择异步任务track_feature_evaluation_v2或track_feature_evaluation_influxdb_v2（见 serializers.py）。

2. 原始数据与分桶聚合

异步任务处理器位于 tasks.py：

• track_feature_evaluations_by_environment将缓存内容批量写入FeatureEvaluationRaw原始表（Postgres 模式）或 InfluxDB；
• 每小时执行的周期任务populate_bucket会调用populate_feature_evaluation_bucket，把过去一小时内的原始数据按 15 分钟粒度聚合进FeatureEvaluationBucket分桶表（ANALYTICS_READ_BUCKET_SIZE = 15，定义于 constants.py）。分桶逻辑通过get_time_buckets计算时间窗口、update_or_create更新对应桶的total_count；
• 每日执行的clean_up_old_analytics_data依据RAW_ANALYTICS_DATA_RETENTION_DAYS与BUCKETED_ANALYTICS_DATA_RETENTION_DAYS设置清理过期数据。

数据模型见 models.py：FeatureEvaluationRaw保存feature_name、environment_id、evaluation_count、labels，并为 multivariate 拆分统计保留identity_identifier与enabled_when_evaluated字段；FeatureEvaluationBucket是其 15 分钟粒度的聚合形态，二者均带created_at索引。

3. 存储后端选择

Flag Analytics 的存储与读取由两个开关决定（见 common.py）：

对自托管用户而言，若要在 Dashboard 看到 Flag Analytics，必须至少配置上述存储后端之一，否则读取侧（见下节）只会返回空结果。

4. 可选标签（Labels）维度

从sdk_metrics_labelsfeature flag 启用后，API 会从请求头提取可选的"标签"元数据并与评估数据一同存储，用于按 SDK/应用维度拆分统计。可跟踪的请求头映射定义在 constants.py：

• Flagsmith-Application-Name→client_application_name
• Flagsmith-Application-Version→client_application_version
• Flagsmith-SDK-User-Agent/User-Agent→user_agent

标签提取实现在 mappers.py 的map_request_to_labels（受sdk_metrics_labels开关控制，关闭时返回空 dict）。前端图表中的 "Filter by SDK" 筛选器与后端查询的labels_filter参数即基于此机制。

读取侧：evaluation-data 端点与前端图表

Dashboard 的 Usage 图表并非直接读原始表，而是通过管理端 API 按日聚合读取：

后端端点：GET /api/v1/projects/{project_pk}/features/{id}/evaluation-data/，实现在 views.py 的get_evaluation_dataaction 中，携带period、environment_id、project_id、labels_filter等查询参数，调用 analytics_db_service.py 的get_feature_evaluation_data。该服务函数按存储后端分发：

• Postgres 模式下（get_feature_evaluation_data_from_local_db），对FeatureEvaluationBucket按created_at__date分组、Sum("total_count")聚合，并按需应用labels_filter；
• InfluxDB 模式下，转交给 influxdb wrapper 按 feature 名称与 environment 查询。

查询默认取最近 30 天数据，与前端固定请求period=30一致。该端点带有InfluxQueryThrottle限流，防止重型时序查询拖垮管理端。

前端消费：useFeatureAnalytics.ts 请求上述 URL（projects/${project_id}/features/${feature_id}/evaluation-data/?period=${period}&environment_id=${environment_id}），返回的数据在 FeatureAnalytics.tsx 中被加工成按天、按环境的柱状序列；当返回带标签数据且sdk_usage_chartsflag 开启时，则切换到按 SDK 标签聚合的 labelled 模式展示。

基于 Analytics 的安全下线工作流

综合官方文档建议，推荐的下线流程如下：

1. 全量发布：将 flag 的"百分百 rollout"稳定运行一段时间，让所有目标用户流量覆盖到新代码路径；
2. 移除评估代码：从代码库中删除对该 flag 的所有引用与评估调用（此时若继续调用hasFeature，SDK 会返回默认值，需配合防御式编码）；
3. 核对引用：在 Usage 标签页确认 Code References 已无残留引用；
4. 核对评估量：观察 Flag Analytics 图表，确认该 flag 在近期窗口内已无（或仅有预期内的少量）评估产生——若仍存在高频评估，说明有遗漏的调用点或缓存中的旧代码在运行，需先排查再删除；
5. 删除 flag：确认无误后在 Flagsmith 中移除该 flag。

同样地，当你在图表上看到某个 flag 出现异常陡峭的评估高峰时，应检查代码中是否存在循环、订阅回调或渲染热路径内的重复评估逻辑——这既是性能隐患，也可能造成不必要的 API 上报流量。

总结

Flagsmith Flag Analytics 是一套"SDK 本地计数 → 周期批量上报 → 服务端缓存聚合 → 分桶存储 → Dashboard 图表展示"的完整链路：

• 开启方式：SDK 初始化时显式开启（JS SDK 为enableAnalytics: true），默认关闭；
• 上报协议：POST /api/v1/analytics/flags/（扁平 dict）与POST /api/v2/analytics/flags/（结构化数组），均以环境密钥认证，服务端会过滤未知 flag 名；
• 存储依赖：自托管必须配置USE_POSTGRES_FOR_ANALYTICS=true或 InfluxDB 连接参数，否则无数据可用；
• 可见延迟：数据需经缓存刷新与 15 分钟分桶聚合，Dashboard 约在 30 分钟到 1 小时之间可见；
• 典型价值：为 flag 下线提供"不再被评估"的客观依据，并帮助定位重复评估类集成缺陷。

相关源码与文档入口：功能说明 flag-analytics.md、API 接收端 views.py、数据模型 models.py、聚合任务 tasks.py、读取服务 analytics_db_service.py、前端图表 FeatureAnalytics.tsx 及单元测试 test_unit_app_analytics_views.py。

• 后端
• 前端