Streamlit 基于用户维度的应用分析：深入解读 `server.unsafeMetricsUserAttributes` 与 `user_session_events` 指标族

Streamlit 基于用户维度的应用分析深入解读server.unsafeMetricsUserAttributes与user_session_events指标族【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit导读本文围绕 Streamlit 仓库中的产品规格文档 specs/2026-06-06-user-analytics-metrics/product-spec.md 展开讲解 Streamlit 如何在既有/_stcore/metrics指标端点之上新增按用户维度的应用使用分析能力通过一个默认关闭、显式开启的服务器配置项server.unsafeMetricsUserAttributes把st.user源自server.trustedUserHeaders身份机制中的属性作为标签发布新的user_session_events计数器指标族从而让托管平台能够统计应用的打开次数、独立访客数UV与日活跃用户数DAU。读完本文你将掌握该配置项的参数语义、底层指标生成流程、隐私边界与部署前提以及如何在托管环境中落地这套谁在何时打开了哪个应用的观测方案。一、背景与问题聚合指标回答了多少回答不了谁Streamlit 的/_stcore/metrics端点是内置的可观测性出口它持续发布三类匿名聚合会话指标定义见 lib/streamlit/runtime/stats.pysession_eventsconnect连接、reconnect重连、disconnect断开三类事件计数器session_duration_seconds会话累计时长active_sessions当前活跃会话数Gauge。以 Streamlit in SnowflakeSiS为代表的托管平台会每 60 秒抓取一次该端点并把数据导入客户事件表用于应用可观测性。但聚合计数无法回答应用所有者真正关心的业务问题过去 N 天应用被打开 / 浏览的总次数一个时间窗口内的独立访客数Unique Visitors日活跃用户DAU与一天内的时段使用分布。原因是这些指标是纯聚合计数器没有用户归属信息。尽管应用侧通过st.user由server.trustedUserHeaders从可信 HTTP 头填充已经可以拿到认证用户身份指标端点却无法把一次连接关联到具体某个用户。在 OSS Streamlit 提供受支持的钩子之前SiS 唯一的做法是猴子补丁monkey-patchStreamlit 内部实现——包装WebsocketSessionManager的生命周期方法和Runtime.__init__来注册自定义的StatsProvider。这种做法在 SiS 的实现计划中被明确标记为脆弱brittle。本规格的价值在于把该能力上溯为 Streamlit 一等公民、显式开启opt-in的机制托管平台不再需要修改内部实现。二、方案总览一个配置项兼具开关与隐私控制双重职责方案的核心是一个新的服务器配置项server.unsafeMetricsUserAttributes它是一个list[str]默认值为空列表[]当前以visibilityhidden隐藏直到 API 与文档定稿定义见 lib/streamlit/config.py列表中的每一项都是st.user的一个键通常由server.trustedUserHeaders填充其值会作为标签附加到新的user_session_events指标族上空列表默认意味着整个功能完全关闭服务器不读取、不缓存、不追踪任何按用户的指标属性不发布该指标族/_stcore/metrics的输出与未开启时逐字节一致unsafe前缀是刻意为之开启后用户可识别信息如邮箱会出现在未认证的指标端点上只能在限制端点访问的托管环境中启用。选择把它做成config.toml选项而不是st.*命令是因为指标端点与身份传播属于部署环境关切而非应用行为——这一点与server.trustedUserHeaders、browser.gatherUsageStats的设计取向一致。2.1 配置示例# .streamlit/config.toml [server] # Attributes from st.user to expose as labels on per-user analytics metrics. # When empty (default), no per-user metrics are emitted. unsafeMetricsUserAttributes [email]对应的身份来源配置SiS 等托管平台设置而非应用作者设置[server] trustedUserHeaders {Sf-Context-Current-User-Email: email} unsafeMetricsUserAttributes [email]2.2 配置项加载时的校验逻辑从源码看该配置项在加载时会经过严格的校验lib/streamlit/config.py违规项会在启动时报错而非静默失效类型校验只允许字符串条目否则抛RuntimeErrorserver.unsafeMetricsUserAttributes must contain only strings保留标签名校验type被保留为user_session_events指标族的事件类型判别标签任何用户属性都不得与其重名_RESERVED_METRICS_USER_ATTRIBUTES frozenset({type})标签名合法性校验属性名会直接成为 OpenMetrics 标签名必须匹配^[a-zA-Z_][a-zA-Z0-9_]*$否则会产出畸形指标、破坏 scraper 对整段负载的解析。三、指标行为user_session_events的新增与语义当server.unsafeMetricsUserAttributes非空时/_stcore/metrics会新增一个计数器指标族OpenMetrics 文本格式输出形如# HELP user_session_events Total count of session events by type and user. # TYPE user_session_events counter user_session_events_total{typeconnect,emailaliceexample.com} 3 user_session_events_total{typereconnect,emailaliceexample.com} 1 user_session_events_total{typedisconnect,emailaliceexample.com} 2 user_session_events_total{typeclose,emailaliceexample.com} 2 user_session_events_total{typeconnect,emailbobexample.com} 5 ...对应实现位于 lib/streamlit/runtime/websocket_session_manager.pyget_stats会先判断配置是否非空然后对内部维护的_user_event_counts字典做快照为每个用户标签集 × 事件类型生成一个CounterStat其中labels{**dict(labels), type: event_type}保证事件类型判别标签type永远优先于用户属性、不被遮蔽。3.1 四种事件类型的语义事件类型常量定义于 lib/streamlit/runtime/websocket_session_manager.py事件类型触发时机对应业务含义connect新的 websocket 连接建立一次打开 / 浏览每次全新连接计数 1reconnect恢复既有会话如页面刷新会话恢复不计入新的打开disconnectwebsocket 断开会话仍可能恢复连接中断close会话被彻底销毁会话结束disconnect与close都归属到连接时刻捕获的用户。3.2 身份捕获与缓存机制身份只在connect 时捕获功能开启的前提下并按会话缓存直到会话关闭——这样终态事件disconnect/close才能归属到正确的用户功能开启期间缓存身份会在reconnect 时刷新如果会话身份在一次重连后发生了变化后续事件归属到最近一次看到的身份配置为空时这条捕获 / 缓存路径被完全跳过零开销。底层实现拆成两个方法lib/streamlit/runtime/websocket_session_manager.py_record_user_event(session_id, event_type, user_info)在 connect/reconnect 时调用解析标签集并累加计数同时把标签集写入_session_user_labels[session_id]_record_cached_user_event(session_id, event_type)在 disconnect/close 时调用从缓存pop出身份再计数。注意pop是无条件执行的——即使功能被运行时关闭缓存条目也会被清除从而保证缓存上限受当前已连接会话集合约束不会因断连会话被存储静默驱逐而产生身份泄漏测试test_disconnect_does_not_leak_identity_cache专门验证了这一点。标签解析逻辑_user_labelslib/streamlit/runtime/websocket_session_manager.py有两个值得注意的实现细节标签元组是排序后的规范化形式(name, value)这样配置中属性顺序不同如[email, user_name]与[user_name, email]不会产生重复的指标序列——测试test_reordered_config_attributes_share_series验证了同一用户只对应一条序列缺失或None的属性值会归一化为空字符串而其他 falsy 值如False会被保留为字符串——这与规格中缺失属性标签值为空串保持指标形状稳定的约定一致。3.3 从指标推导业务口径打开次数 / 浏览量每次全新 websocket 连接都会让该用户的connect计数 1页面刷新若恢复了既有会话则记为reconnect不会虚增打开次数独立访客UV下游按时间窗口对不同的标签集组合去重计数即可推导活跃度Engagement由既有的session_duration_seconds与active_sessions指标族覆盖本 MVP 不新增按用户维度的时长指标。3.4 端点过滤按族名精确抓取user_session_events指标族可以通过既有的?families查询参数单独过滤scraper 可以只请求这一族curl http://localhost:8501/_stcore/metrics?familiesuser_session_events在 Starlette 端点实现中lib/streamlit/web/server/starlette/starlette_routes.pyROUTE_METRICS _stcore/metrics端点会解析families查询参数并只渲染请求的指标族lib/streamlit/web/server/starlette/starlette_routes.py。值得注意的细节是WebsocketSessionManager.stats_families无条件地宣告了USER_SESSION_EVENTS_FAMILYlib/streamlit/runtime/websocket_session_manager.py这样StatsManager注册时快照一次该属性始终能把?familiesuser_session_events的请求路由到本 provider真正的是否发射门控放在get_stats里因此功能关闭时端点输出保持不变。3.5 边界情况属性缺失配置的属性在某个会话的st.user中不存在时标签值为空字符串email指标形状保持稳定测试test_missing_attribute_becomes_empty_string无认证用户本地开发、无可信头所有配置标签都为空串。功能仍然工作但无归属价值——这是预期行为因为该特性面向托管 / 认证环境基数Cardinality发射的序列数量随进程可见的不同用户数线性增长。对目标托管环境可接受高基数防护见Out of Scope功能关闭零开销——不读取、不缓存用户属性不追踪计数器不发射指标族测试test_disabled_default_emits_no_user_family断言默认配置下仅返回原有的 3 个指标族。3.6 运行期语义unsafeMetricsUserAttributes在服务器启动时读取不支持在运行中的服务器上热切换与其它server.*选项一致重启生效。跨切换的按用户归属是 best-effort 且未定义的例如功能关闭期间缓存身份可能不刷新。托管平台应一次性设置。测试test_runtime_disable_stops_emission_but_pops_cache验证了运行期关闭后的行为不再记录新事件但身份缓存仍会被弹出清除。四、隐私与安全unsafe前缀的由来本特性会在 HTTP 端点上暴露 PII如邮箱因此设计上有四条硬性约束显式开启opt-in且默认关闭宿主平台显式选择暴露哪些属性——Streamlit 除非被配置否则绝不发射用户身份内部不主动采集——除非unsafeMetricsUserAttributes非空Streamlit 内部也不得收集这些属性采集是 best-effort——记录按用户指标过程中的任何失败都绝不能破坏应用执行或拒绝用户访问。最后一条在实现中体现得很彻底_record_user_event/_record_cached_user_event都把逻辑包在try/except中任何异常仅记 debug 日志。测试test_fail_open_on_malformed_user_info用了一个get()方法会抛异常的BadUserInfo对象验证会话生命周期完全不受影响、且不产生任何错误事件记录。4.1 端点的访问控制是前置条件不由本特性提供这一点必须在文档中作为硬性前提明确写出/_stcore/metrics端点在 Streamlit 层没有任何内置认证、授权或 IP 白名单——服务器端口上可达的任何人都能抓取。今天它只暴露匿名聚合计数器一旦设置了unsafeMetricsUserAttributes同一个未认证端点还会服务于配置的 PII。因此仅当宿主在网络层限制指标端点访问时SiS 采用的正是这种模式——端口内部化、仅由平台抓取、永不暴露给终端用户开启该选项才是安全的给指标路由本身添加认证是更大范围的改动另行跟踪不在本规格范围内。4.2 标签值的转义用户控制的值进入 OpenMetrics 文本格式时必须转义。stats.py中的_escape_label_valuelib/streamlit/runtime/stats.py会对反斜杠、双引号、换行分别转义——否则恶意或异常的用户属性值会产出畸形输出破坏 scraper 对整段负载的解析。_labels_to_str则按排序后的标签输出keyvalue对。五、SiS 场景落地示例与接入方式5.1 平台侧配置由托管平台设置而非应用作者[server] trustedUserHeaders {Sf-Context-Current-User-Email: email} unsafeMetricsUserAttributes [email]server.trustedUserHeaders将 HTTP 头Sf-Context-Current-User-Email的值在 websocket 连接时写入st.user[email]定义见 lib/streamlit/config.py。配置解析时若该选项以环境变量或 CLI 形式传入会按 JSON 对象解析并校验键唯一性lib/streamlit/config.py。本配置项目前标注为实验性 APINote: This is an experimental API subject to change。5.2 scraper 侧抓取# 只抓取按用户维度的指标族 curl http://localhost:8501/_stcore/metrics?familiesuser_session_events抓取方可以周期性请求该族按email标签去重统计独立访客按connect事件聚合应用打开次数进而得出 DAU 与时段分布并汇入既有的事件表与告警管线。5.3 测试验证一套完整的生命周期用例仓库测试 lib/tests/streamlit/runtime/websocket_session_manager_test.py 用connect → disconnect → reconnect → close的完整生命周期验证了四种事件类型的归属与计数test_enabled_records_full_lifecycle还覆盖了多用户独立计数、重连身份不匹配时创建新会话test_identity_mismatch_on_stored_reconnect_creates_new_session、仅请求user_session_events时只返回该族test_families_filter_returns_only_user_family、活动会话直接关闭记录close而非disconnect等关键场景。这些用例是理解身份绑定到会话语义的最佳实践参考。六、Out of Scope明确不做的事未来工作规格明确划定了本 MVP 的边界避免过度设计按用户的会话时长 / 活跃度指标聚合时长已由session_duration_seconds覆盖如有需求可后续增加按用户时长产品内分析 UISnowsight 仪表盘SiS V1属于下游不是 OSS Streamlit 的组成部分基数保护 / 采样限制不同用户序列数量交给 scraper / 宿主管线它们本就有 rollup 与保留策略若 OSS 用户在托管环境之外采纳此特性再重新评估按组件 / 按图表的遥测明确不在本 MVP 内身份匿名化 / 哈希暴露什么由宿主决定如需哈希可在trustedUserHeaders上游完成/_stcore/metrics端点认证端点目前未认证本规格不改变这一点宿主须在网络层限制访问端点级认证是更大范围的独立工作。七、规格自检清单要点规格自带的 Checklist 从工程视角确认了该方案的性质兼容性为 SiS 设计除非设置server.unsafeMetricsUserAttributes在其它环境是无操作no-op无破坏性 API 变更纯增量配置项默认关闭使端点输出不变无新依赖完全复用既有 stats/metrics 基础设施StatsProvider、StatsManager、CounterStat、OpenMetrics 序列化指标收集本特性本身就是指标特性选项开启时应采集一条 usage stat安全 / 法律影响存在——可能在指标端点暴露 PII邮箱默认关闭、显式开启、属性列表由宿主控制需要隐私 / 法律评审与文档文档需求在将隐藏选项公开前需要为server.unsafeMetricsUserAttributes与user_session_events指标族编写文档。总结server.unsafeMetricsUserAttributes用最小的增量一个隐藏配置项 一个计数器指标族把 Streamlit 的会话观测从匿名聚合升级为按用户维度且通过默认关闭、宿主显式选择暴露属性、best-effort 采集和配置时校验等机制把 PII 暴露风险约束在可控范围内。对托管平台而言它提供了替代猴子补丁的一等公民接入点对应用所有者而言它解锁了打开次数、独立访客与 DAU 等核心采用度指标。若要深入源码可从三个文件入手config.py配置定义与校验、websocket_session_manager.py生命周期事件与计数实现、starlette_routes.py端点与families过滤配合 websocket_session_manager_test.py 中的完整用例即可快速吃透全链路。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考