后端前端【免费下载链接】flagsmithFlagsmith is an open-source feature flag platform with remote config, experimentation, and self-hosted or cloud deployment options.项目地址https://gitcode.com/gh_mirrors/fl/flagsmith点击查看免费下载本篇指南以 Flagsmith 开源仓库中的 API Usage 文档 为骨架完整讲解 Flagsmith 如何追踪 SDK 发起的 API 调用、在组织/项目/环境各层级查看用量数据并深入到app_analytics应用的中间件、数据模型、聚合任务与查询接口帮助你理解谁在什么时候调用了多少次 API同时为容量规划、成本核算与 Flag 清理提供数据依据。Flagsmith 会在其数据存储中记录 SDK 发出的每一次 API 调用并在组织设置页面的Usage标签页中呈现这些数据。本文将先梳理被追踪的四种请求类型与查看入口再结合仓库源码拆解追踪链路中间件识别 → 缓存聚合 → 异步入库 → 桶聚合 → 报表查询最后介绍与 Flag Analytics 的关系及自托管部署时的存储配置。一、Flagsmith 追踪哪些 API 请求根据原文档Flagsmith 只追踪以下四类由 SDK 发起的请求其余管理类请求Management API、Flag Analytics 上报请求等不计入此用量统计序号被追踪的请求类型对应 API 路径由源码Resource枚举验证典型发起方1Get Flags/api/v1/flags远程评估Remote Evaluation模式下获取环境全部 Flag2Get Identity Flags/api/v1/identities远程评估模式下获取某个 Identity 的 Flag3Set Identity Traits/api/v1/traits上报/更新用户属性Traits4Get Environment Document/api/v1/environment-document本地评估Local EvaluationSDK 定期拉取的环境文档这四类资源在源码中有精确的一一对应定义。在 api/app_analytics/models.py 中Resource是一个IntegerChoices枚举并为每个资源提供了resource_nameflags、identities、traits、environment-document与column_name用于报表字段命名class Resource(models.IntegerChoices): FLAGS 1 IDENTITIES 2 TRAITS 3 ENVIRONMENT_DOCUMENT 4单元测试 以参数化方式直接验证了这四个路径与资源名的对应关系/api/v1/flags → flags、/api/v1/traits → traits、/api/v1/identities → identities、/api/v1/environment-document → environment-document。关于 Environment Document 的补充说明SDK 文档 指出本地评估模式下 SDK 初始化时会请求一次包含环境全部配置的 JSON 文档之后默认每 60 秒刷新一次因此一个运行中的服务实例每分钟产生一次 Environment Document 请求这正是本地评估模式下唯一的 API 调用来源。二、在哪里查看 API 用量按原文档指引查看入口如下登录 Flagsmith 控制台进入Organisation settings组织设置页面点击Usage标签可在该页面进一步下钻drill down到具体的 Project项目与 Environment环境查看每个层级的调用量。上方截图即展示了某个项目在特定环境Staging下的统计界面按Flags、Identities、Traits分别计数并给出Total API Calls总量同时以堆叠柱状图展示按日例如 2023-03-07 至 2023-04-05的趋势分布。报表字段的真实含义用量报表的每条记录由 app_analytics/dataclasses.py 中的UsageData定义最终通过 UsageDataSerializer 序列化输出class UsageDataSerializer(serializers.Serializer): flags serializers.IntegerField() # Get Flags 次数 identities serializers.IntegerField() # Get Identity Flags 次数 traits serializers.IntegerField() # Set Identity Traits 次数 environment_document serializers.IntegerField() # Environment Document 拉取次数 day serializers.CharField() # 统计日期 labels LabelsSerializer(allow_nullTrue, requiredFalse)可以看到报表中的四个计数列与上节四种请求类型一一对应——flags、identities、traits和environment_document分别来源于Resource枚举的column_name属性。三、底层实现API 调用是如何被追踪的原文档只说明了会追踪下面结合源码还原完整链路。整个实现位于 api/app_analytics/ 应用内。3.1 中间件识别请求核心是APIUsageMiddlewareapi/app_analytics/middleware.pyclass APIUsageMiddleware: def __call__(self, request: HttpRequest) - HttpResponse: if environment_key : request.headers.get(X-Environment-Key): track_usage_by_resource_host_and_environment( resourceget_resource_from_uri(request.path), hostrequest.get_host(), environment_keyenvironment_key, labelsmap_request_to_labels(request), ) response self.get_response(request) return response几个关键细节以X-Environment-Key请求头作为判定条件只有携带该头即 SDK 请求的调用才被统计这也是管理端请求不会被计入的原因资源识别get_resource_from_uri()track.py解析request.path要求路径形如/api/v1/resource/...并取第三个分段映射到Resource枚举不是 API 路径或未知资源则跳过中间件仅在开关打开时挂载设置项ENABLE_API_USAGE_TRACKING默认True控制是否在 DjangoMIDDLEWARE中追加该中间件见 api/app/settings/common.py。此外还有一个可选的GoogleAnalyticsMiddlewaremiddleware.py在配置了GOOGLE_ANALYTICS_KEY时挂载向 Google Analytics 上报 pageview 与资源事件属于可选的历史实现不影响 InfluxDB/Postgres 用量统计。3.2 先缓存聚合再异步入库为避免每个请求都触发一次数据库写入统计采用了内存缓存 定时刷盘的模式api/app_analytics/services.pydef track_usage_by_resource_host_and_environment(resource, host, environment_key, labels): if resource and resource.is_tracked: if settings.USE_CACHE_FOR_USAGE_DATA: api_usage_cache.track_request(...) # 先写入进程内缓存 else: track_request.run_in_thread(...) # 直接异步入库APIUsageCacheapi/app_analytics/cache.py以(resource, host, environment_key, labels)为键累加计数每隔API_USAGE_CACHE_SECONDS秒默认 60见 common.py将累计值一次性刷新为后台任务track_request。track_request任务tasks.py再根据后端类型写入USE_POSTGRES_FOR_ANALYTICSTrue时创建APIUsageRaw记录否则若配置了INFLUXDB_TOKEN调用track_request_influxdb()将数据点写入 InfluxDB。track_request_influxdbtrack.py写入的标签非常丰富包含resource、organisation/organisation_id、project/project_id、environment/environment_id、host以及可选的客户端标签——这正是用量数据能够按项目、环境、主机下钻的根源。四、用量数据的存储与聚合4.1 两种分析后端原文档没有展开存储细节但自托管部署时这是核心配置项。分析数据可落在两种后端之一common.py环境变量默认值说明USE_POSTGRES_FOR_ANALYTICSFalse为True时使用 PostgreSQL 表存储用量与评估数据无需额外时序数据库INFLUXDB_TOKEN非空时使用 InfluxDB 作为分析后端INFLUXDB_BUCKETInfluxDB 存储桶名INFLUXDB_URL/INFLUXDB_ORGInfluxDB 连接地址与组织在 analytics_db_service.py 的get_usage_data()中二者优先级明确USE_POSTGRES_FOR_ANALYTICS优先其次INFLUXDB_TOKEN两者都未配置时仅记录一条NO_ANALYTICS_DATABASE_CONFIGURED_WARNING警告并返回空数据警告文案定义于 constants.py。4.2 数据模型与生命周期Postgres 后端依赖四张模型表models.pyAPIUsageRaw原始 API 调用记录environment_id、host、resource、count、labelsJSON 字段APIUsageBucket按时间桶聚合后的用量数据FeatureEvaluationRaw原始 Flag 评估记录含identity_identifier、enabled_when_evaluated用于多变量拆分测试FeatureEvaluationBucket聚合后的评估数据。AbstractBucket提供了桶不允许重叠的校验逻辑APIUsageBucket/FeatureEvaluationBucket在BEFORE_CREATE钩子中检查是否存在同环境、同时段、同标签的已有桶防止聚合任务重复执行造成数据重复models.py。数据生命周期由两个周期任务管理tasks.pypopulate_bucket每 60 分钟运行一次按ANALYTICS_READ_BUCKET_SIZE15 分钟见 constants.py把原始数据聚合进桶表clean_up_old_analytics_data每天运行一次原始数据保留RAW_ANALYTICS_DATA_RETENTION_DAYS默认 30 天桶数据保留BUCKETED_ANALYTICS_DATA_RETENTION_DAYS默认 90 天后删除common.py。InfluxDB 后端则利用时序库特性原始数据写入INFLUXDB_BUCKET并通过 select_downsampled_bucket 自动选择降采样桶——查询窗口超过 10 天用1h粒度10 天内用15m粒度保证查询性能。五、用量数据查询接口与参数5.1 管理 API 端点用量数据不仅能在界面查看还开放了管理 API路由见 api/organisations/urls.py视图见 views.pyGET /api/v1/organisations/organisation_pk/usage-data/按日返回各资源的调用次数GET /api/v1/organisations/organisation_pk/usage-data/total-count/返回总量计数。两个端点均要求已认证用户且通过UsageDataPermission权限校验并带有InfluxQueryThrottle限流。5.2 查询参数UsageDataQuerySerializerserializers.py定义了以下过滤参数参数类型说明project_idint可选只看指定项目environment_idint可选只看指定环境period枚举可选current_billing_period/previous_billing_period/90_day_periodclient_application_name、client_application_version、user_agentstr可选按标签过滤见下文第六节其中period的时间窗口计算由订阅信息缓存驱动analytics_db_service.py账单周期基于OrganisationSubscriptionInformationCache.current_billing_term_starts_at推算90_day_period则固定为当前时间往前 90 天。未配置订阅周期而请求账单周期时返回404 NotFound对应测试 test_analytics_db_service.py。5.3 报表聚合逻辑Postgres 后端下get_usage_data_from_local_db()只读取 15 分钟粒度的桶表按(日期, 资源, 标签)分组求和analytics_db_service.py再由 mappers.py 将多行桶数据折叠成每天一行、每资源一列的UsageData。由于同一日期可能存在多种标签组合map_usage_data_to_daily_totals 还会将所有标签组合累加成每日总量供整组织视图使用。相关聚合正确性由 test_analytics_db_service.py 的多桶聚合测试覆盖。六、标签Labels区分调用来源的进阶能力原文档未提及但从源码可见用量统计支持按来源打标签这使报表可以按客户端应用名、版本、SDK/User-Agent 过滤是理解哪些客户端在消耗 API的关键能力。6.1 标签类型与请求头映射constants.py 定义了可选请求头到标签的映射请求头标签名说明Flagsmith-Application-Nameclient_application_name客户端应用名Flagsmith-Application-Versionclient_application_version客户端应用版本Flagsmith-SDK-User-Agentsdk_user_agentSDK 标识浏览器场景替代User-AgentUser-Agentuser_agent浏览器自带 UA最终存储的标签固定为三种types.pyclient_application_name、client_application_version、user_agent。6.2 标签收集受开关控制标签并非无条件收集。mappers.py 中的map_request_to_labels()首先通过 OpenFeature 客户端查询名为sdk_metrics_labels的功能开关只有该开关开启时才解析请求头并产出标签否则返回空字典。这也解释了 test_middleware.py 中不带可选头 → 标签为空带应用名/版本头 → 标签正确解析的两种断言场景。6.3 User-Agent 的数值化存储为压缩时序数据已知 SDK 的 UA 会被映射为数值 IDSDK_USER_AGENT_KNOWN_VERSIONSconstants.py收录了 13 个官方 SDK 及其已知版本号如flagsmith-python-sdk/5.0.0、flagsmith-nodejs-sdk/9.0.3等未知版本统一归一化为unknownSDK_USER_AGENT_INFLUX_IDS 为每个 SDK 分配起始 IDPython 系 90000、Node 系 70000 等写入 Influx 时map_labels_to_influx_record_values()将 UA 转成数字读取时再反向还原mappers.py。仓库还提供了 add-known-sdk-version.py 脚本用于向该表新增已发布的 SDK 版本。七、Flag UsageFlag 级别的评估统计原文档指出除了 API 调用量Flagsmith 还通过 Flag Analytics 追踪Flag 评估次数Flag Evaluations两者互为补充——API Usage 回答调用了多少次接口Flag Analytics 回答每个 Flag 被评估了多少次。7.1 数据如何产生在 SDK 端每次调用如flagsmith.hasFeature(myCoolFeature)都会在本地累计该 Flag 的评估计数SDK 每隔一段时间JS SDK 当前为 10 秒向 Flagsmith API 上报一次无评估则不上报见 flag-analytics.mdFlag Analytics默认关闭需要在 SDK 初始化时显式开启各 SDK 文档均有对应初始化选项上报的数据在界面可见大约需要30 分钟到 1 小时桶聚合延迟所致。7.2 服务端接收与入库API 端由SDKAnalyticsFlagsV1/SDKAnalyticsFlagsV2视图接收app_analytics/views.py路径形如/api/v1/analytics/flags。序列化器serializers.py在validate阶段会校验上报的feature_name必须属于该环境的真实 Feature防止脏数据随后V1 接口把{feature_name: count}扁平字典写入FeatureEvaluationCache同样按 60 秒间隔刷新cache.pyV2 接口按evaluations数组直接投递后台任务Postgres 后端批量创建FeatureEvaluationRawInflux 后端写入feature_evaluation测量tasks.py。评估数据同样经populate_feature_evaluation_bucket聚合成 15 分钟桶再由get_feature_evaluation_data()analytics_db_service.py按 Flag、环境与时间窗查询——这正是 Flag 详情页 Usage 标签页图表的数据来源。八、与计费的关系与部署提示SaaS / Flagsmith 托管环境的计费关系被追踪的四类请求对应计费文档 Billing and API Usage 中的可计费请求Management API 请求、Flag Analytics 上报、实时 Flag 更新WebSocket连接均不计费。自托管无请求上限文档明确说明 Self-hosted 安装没有 API 请求数限制但若需在自托管环境查看用量报表必须正确配置USE_POSTGRES_FOR_ANALYTICSTrue或 InfluxDB 相关环境变量否则分析查询只会返回空结果并输出警告日志。数据保留窗口原始数据默认仅保留 30 天、聚合数据保留 90 天两者均可在RAW_ANALYTICS_DATA_RETENTION_DAYS/BUCKETED_ANALYTICS_DATA_RETENTION_DAYS中调整用量页面默认展示 90 天窗口。调优选项USE_CACHE_FOR_USAGE_DATA默认True与API_USAGE_CACHE_SECONDS默认 60控制内存聚合粒度高 QPS 场景可适当调大后者以减少写放大。九、常见用途与排查建议综合原文档与源码API Usage 数据在以下几类场景中价值最大成本与容量规划结合 Billing and API Usage 中的估算公式如客户端月会话数 × (2 次 Flag 更新 3 次 Flag 请求)服务端实例数 × 43200 次/月用实际报表数据校准容量评估模式选型对比environment_document与flags/identities的比例可判断本地评估是否已真正降低远程调用量Flag 清理Flag Analytics 中评估次数长期为 0 的 Flag 可安全考虑移除flag-analytics.md异常排查结合标签客户端应用名/版本下钻可定位某个客户端版本的异常高频调用例如代码缺陷导致的重复评估。相关资源索引本文主题文档api-usage.mdFlag 级评估统计flag-analytics.md计费与用量估算billing-api-usage.md环境文档与本地评估SDK 集成文档核心实现app_analytics 应用中间件 middleware.py、模型 models.py、聚合任务 tasks.py、查询服务 analytics_db_service.py分析后端配置common.py单元测试test_middleware.py、test_analytics_db_service.py赞分享后端前端【免费下载链接】flagsmithFlagsmith is an open-source feature flag platform with remote config, experimentation, and self-hosted or cloud deployment options.项目地址https://gitcode.com/gh_mirrors/fl/flagsmith点击查看免费下载相关推荐FluentRead 模型用量Model Usage深度指南本机 Token 统计、缓存构成与请求追踪FluentRead 模型用量Model Usage深度指南本机 Token 统计、缓存构成与请求追踪 模型用量是 FluentRead 内置的一项本地可前端AI 应用本地部署openai-agents-python 用量Usage追踪完全指南从 Token 统计、按请求明细到原始载荷保留openai agents python 用量Usage追踪完全指南从 Token 统计、按请求明细到原始载荷保留 导读 本文聚焦 openai agen人工智能AI AgentAgent 框架多智能体工具调用MCP ClientsDevPod追踪系统终极指南深入理解请求链路追踪机制 DevPod追踪系统终极指南深入理解请求链路追踪机制 DevPod 作为开源开发者环境管理工具其 请求链路追踪机制 是确保系统稳定性和性能的关键。本文开发工具CLI桌面应用上一篇HSAK多队列IO优化如何实现128核并发处理的高吞吐量下一篇终极指南A-Tune-BPF-Collection让Linux内核参数调优变得如此简单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考