浏览器测量跨越一个受控边界
浏览器永远不会收到摄取密钥或选择目标表。您的服务器在转发分析事件之前验证小负载。
- 1
测量
在同意后收集列入许可名单的 Web Vital 或有限的前端结果。
- 2
验证
强制执行原产地、大小、费率、字段、路线和数字范围规则。
- 3
前进
使用服务器端密钥和一份受控事件合约。
- 4
审查
查询样本并发布趋势以及每个聚合旁边的数量。
开始之前
先决条件和界限
- 可以保持 Telemetry API 密钥私有的同源服务器端点
- 事件名称、字段、指标名称、路由模板和数字范围的白名单
- 记录浏览器测量的同意、采样、保留和删除行为
交货设置
安装并初始化服务器端
在仅服务器代码中导入 telemetry-sh 并使用 process.env.TELEMETRY_API_KEY 对其进行一次初始化。 将摄取凭据保留在浏览器包、客户端可见的环境变量、源代码控制、日志和异常消息之外。
npm安装
npm install telemetry-sh- 1准备一个具有有限网络行为的可重用服务器端交付客户端。
- 2在成功、失败、重试或超时边界处添加结果事件。
- 3在启用警报之前发送受控装置并检查存储的行。
片段
从一个结构化事件开始
在工作流程完成、失败或重试的位置添加此形状。然后从真实的字段构建仪表板。
Browser JavaScript and Web Vitals Telemetry事件
// Browser: post only allowlisted measurements to your own origin.
function reportMetric(metric) {
navigator.sendBeacon("/api/browser-telemetry", JSON.stringify({
event_name: "browser_performance_observed",
metric_name: metric.name,
metric_value: metric.value,
metric_id: metric.id,
route_template: routeTemplateFor(location.pathname),
release: window.__APP_RELEASE__,
navigation_type: metric.navigationType,
}));
}
// Server: validate origin, size, rate, names, fields, and numeric ranges first.
await telemetry.log("browser_performance_observed", validatedMetric);活动合约
metric_name、metric_value、metric_id、route_template 和释放
navigation_type、device_category、采样、consent_state 和环境
没有原始 URL、查询字符串、DOM 文本、表单值、cookie、引用标识符或客户端提供的表名称
实施检查点
检查站 1
将少量列入白名单的有效负载发送到您自己的来源；在转发之前验证来源、内容类型、正文大小、速率、事件名称、字段和范围。
检查站 2
使用路由模板而不是 location.href，并在浏览器发送任何测量结果之前应用同意或选择退出规则。
检查站 3
sendBeacon 和 keepalive fetch 是尽力而为的。将样本计数保留在百分位旁边，并且永远不要将浏览器交付视为精确的分类帐。
验证
证明事件已到达
在演练已知的成功和失败案例后运行此命令。如果您的最终事件契约与代码片段不同，请替换后备表名称。
Browser JavaScript and Web Vitals Telemetry 验证查询
SELECT *
FROM browser_performance_observed
ORDER BY timestamp_utc DESC
LIMIT 20;实施参考
在启用新的生产路径之前，请检查事件合同、数据安全指南和上游主要文档。
生产边界
保持结果事件小且可恢复
该模式提供了
- 除了上游工作流程之外，还有一个有界的、SQL 就绪的结果。
- 用于仪表板、警报和跨事件关联的稳定字段。
- 用于验证成功、失败、重试和超时行为的夹具驱动路径。
该模式不提供
- OTLP 导出器、自动收集管道或详细跟踪和诊断日志的替代品。
- 仅因为有效负载包含事件 ID，所以仅传送一次。
- 收集原始提供商有效负载、用户内容、凭证或受监管数据的权限。
事件架构起点
此工作流程的事件契约
在将查询或代码片段适应生产之前，请检查行粒度、发出边界、所需类型、隐私类、示例有效负载和验证清单。
相关产品功能
继续此工作流程 告警
将经过审查的可靠性查询提升到拥有的阈值和响应工作流程中。
相关 SQL 查询示例
用 SQL 回答下一个问题
针对此工作流程中的结构化字段运行查询，检查示例结果，并将有用的答案转换为仪表板或警报。
按路线和版本比较核心网络生命力
哪个路线和版本的前端性能最弱？
打开查询示例按路由和发布对 JavaScript 错误进行排名
哪个路由和前端版本会产生最广泛的 JavaScript 错误影响？
打开查询示例按路线测量 SPA 导航延迟
哪些目的地路线的客户端导航速度最慢？
打开查询示例按路由计算浏览器长任务率
哪些路线和版本在浏览器长任务中花费最多时间？
打开查询示例按主机查找慢速前端资源
哪些资源主机和类型正在减慢或失败页面加载？
打开查询示例按实施系列浏览
比较相关集成模式
与此集成配对的模板
更多集成