舞会反应
在您的 React App 中添加 Prometheus 度量衡。 建在 proxy 上方和反应性能库
范围和宗旨
本套件的主要目标是为React前端提供生产运行时间可观察性, 允许对操作度量表进行监测和警示,例如但不仅限于区段装载时间、加载应用错误等等.
为此,该图书馆提供 MetricsProvider 顶部是 舞会
财务报告和审定财务报表 @ shopify/ react- prove最小
你代码的仪表,可以创建出出类拔萃的Grafana仪表板,或者提高前端应用程序的相模警报.
为了更好地理解这个图书馆的目的和建筑决定 请仔细研究一下 本条/陈述
需要注意的是,考虑到普罗米修斯拉力模型,这个库需要推出度量衡 进入一些普罗米修斯聚合网关,以提供它们。 建议用针对 舞会-会场-大门 实例,但 其他替代办法也可能奏效.
安装
$ yarn add @cabify/prom-react
使用量
基本用途
首先,你需要增加一个 MetricsProvider 进入你的应用程序。 最好把它加进根部
您的应用程序, 使其广泛提供.
// src/index.tsx
import { MetricsProvider } from '@cabify/prom-react';
const normalizePath = (path: string) => {
const match = path.match(/\/products\/(\d+)/);
if (match) {
return `/products/:id`;
}
return path;
};
const AppRoot = () => (
<MetricsProvider
appName="my-app-name"
owner="my-team"
getNormalizedPath={normalizePath}
metricsAggregatorUrl="https://some-metrics-aggregator.com/push-metrics"
>
<OtherProviders>
<App />
</OtherProviders>
</MetricsProvider>
);
render(<AppRoot />, document.getElementById('app'));
之后,在您所有的应用页面或节根组件中,需要添加一个导航标记.
请注意,您的页面组件应该添加 usePerformanceMark如果有一个单页没有
明确调用 usePerformanceMark(Stage.Complete, 'page-id'),您的度量值将显示错误的结果.
你会发现它的异常高值 prom_react_navigation_seconds (这会影响你的p99度量).
见 @ shopify/ react- prove
需要更多信息.
// src/pages/Products.tsx
import { usePerformanceMark, Stage } from '@cabify/prom-react'; // handy re-export of @shopify/react-performance utils
export const Products = () => {
// whatever way to load the page data
const [products, isLoading] = useFetchProducts();
usePerformanceMark(isLoading ? Stage.Usable : Stage.Complete, 'products');
return '...';
};
如果您还想要监视您的应用程序加载失败( 丢失捆绑文件, js 错误等) , 您将会
您需要添加以下小片段 index.html 文件( 文件必须放在那里才能执行)
即使你的捆绑无法到达/ 无法工作 :
window.__PROM_REACT_LOAD_FAILURE_TIMEOUT__ = setTimeout(function () {
var xhr = new XMLHttpRequest();
var str = '# HELP prom_react_app_loaded Application loaded counter\n';
str += '# TYPE prom_react_app_loaded counter\n';
str += 'prom_react_app_loaded{app_name="<<APP_NAME>>",status="failure"} 1\n';
xhr.open('POST', '<<METRICS_AGGREGATOR_URL>>');
xhr.setRequestHeader('Content-Type', 'text/plain');
xhr.send(str);
}, 3000);
(请记住替换) <<METRICS_AGGREGATOR_URL>> 财务报告和审定财务报表 <<APP_NAME>> 占位符以匹配您的配置)
增加这种仪器可以提供框外的这些金指标:
prom_react_app_loaded: 应用程序已载入计数器。 它会观察两个活塞/故障负载.prom_react_app_unloaded:应用程序已卸载。 用途navigator.sendBeaconAPI幕后新闻.prom_react_performance_seconds: 直方图,用于存储加载性能事件计时(dcl, (中文(简体) ),ttfb, (中文(简体) ),ttfp(见a/c.5/49/70,附件).prom_react_navigation_duration_seconds:直方图来存储各段之间的导航时间. 包括两个全页负荷(navigation_type="full_page)和通过 历史pushState或反应 -- 路由器navigation_type="in_app) (中文(简体) ). 上面还有标签 与path(你需要照顾) 主要爆炸 通过使用 获得正态Path 创建时的道具MetricsProvider(中文(简体) )prom_react_ttc_seconds: 直方图存储页面 Time Tocomplete 导航时间. 包含与navigation_duration_seconds标准.prom_react_ttu_seconds: 直方图来存储页面 TimeToUsable 导航时间. 包含与navigation_duration_seconds标准.
添加自定义度量衡
您可以添加您的自定义应用度量表, 以便在需要时使用 。 要做到这一点,只是附在 MetricsProvider。 。 。 .
以后,你可以利用这个机会 useMetrics 勾勾以添加关于这些衡量标准的意见:
// src/index.tsx
import { MetricsProvider } from '@cabify/prom-react';
// please remember to define them outside the component to avoid unneeded re-renders
const customMetrics: MetricDefinition[] = [
{
type: 'counter',
name: 'my_app_report_download_count',
description: 'Number of reports downloaded',
},
];
const MyApp = () => {
return (
<MetricsProvider appName="MyApp" customMetrics={customMetrics}>
...
</MetricsProvider>
);
};
// Any inner component
import { useMetrics } from '@cabify/prom-react';
const ReportsDownloadButton = () => {
const { observe } = useMetrics();
const downloadReport = () => {
observe('my_app_report_download_count', { custom_tag: 'custom value' }, 1);
// your app code
};
return <div onClick={downloadReport}>Download report</div>;
};
API 密码
测量器
反应组件,配置所有监测基础设施并添加上述内容 黄金度量衡. 它必须放置在您组件树的根.
道具 :
appName: string;:应用程序名称. 所有衡量标准都将包括“ app name” 标签 以这个值.owner?: string;:应用程序的拥有者. 所有衡量标准都将包含一个带有此值的标签"所有人".metricsAggregatorUrl?: string;:推出网关集合器的Url. 如果不设定,将收集但不予发送.customMetrics?: MetricDefinition[];:自定义应用度量衡. 请在曲线中定义 在组件外避免试图创建无限循环.fetchOptions?: Partial<RequestInit>: 额外获取选项(标题、证书等),用于向聚合器发送指标.getNormalizedPath?: (path: string) => string;: 鉴于所有路由变化度量包括 a “ path” 标签, 如果您有的话, 您应该添加此功能以避免基本问题 参数化路线( ex:/products/:id) (中文(简体) ). 见 食谱 例.histogramBuckets?: number[]: Bucket 列表用于直方图测量. 默认[0.01, 0.1, 1, 2, 3, 4, 5, 7, 10, 15]。 。 。 .
使用PerformanceMark,Stage等软件.
此库将全部再导出 @shopify/react-performance 避免明确添加
您的软件包依赖性。 你可以看一看这个
API 文档 详细情况.
计量
反应组件将登录到控制台所有度量观测。 它不会在屏幕上做任何事情. 你不应该在生产中加上这个.
道具 :
logger?: ObserveCallback: 如果设置, 它将替换原始日志 。 确保这个值的引用不会通过记忆日志函数或从组件外定义来避免性能问题而改变.
量子调试覆盖
反应组件以显示调试信息 。 必须放在下面 MetricsProvider。它显示一个不是那么迷人
以导航信息覆盖。 检查您的所有区域是否有适当的工具 usePerformanceMark。 。 。 .
它也可以将您的所有观察记录到控制台( uss) MetricsLogger 盖下. 你不应该在制作中显示这一点.
道具 :
onClose?: () => void: 如果设置了, 它将显示一个关闭按钮, 当按下时会调用此调用withLogger?: boolean:如果设置为真,则包括MetricsLogger这边,你可以 所有在手的调试设施只添加此组件.
注意这些调试组件非常基本,可能不符合您的需要. 然而,作为所有衡量数据
可通过 useMetrics 钩子, 您可以在内部构建自己的日志、 调试面板等
您的应用程序或外部库.
使用量表( )
进入测量仪登记簿和其他一些随时可以使用的帮助者。 它返回对象 具有下列属性:
observe(metricName, tags?, value?, skipSending?)数字 : 帮助在现有衡量标准中添加一个观察。 请注意,衡量标准应在提供者中建立。 它支持直方图和反度量衡.metricName: string: 添加观测值的度量衡名称.tags?: Record<string, string>:可选标签来加入观察. 用这种方法添加的所有观测结果 将会有app_name财务报告和审定财务报表owner标签设置得当.value?: number:增加观察值. 直方图测量和可选 用于反度量衡。 如果不设定, 这种方法将增加计数器1。 。 。 .skipSending?: boolean: 如果设置为真, 观察将不会被发送到后端 (你可以打电话)sendMetrics()手动发送观察).
isReady: boolean: 标出标记,以表示何时可以使用度量衡。 你只能依赖 如果您在首次渲染应用程序时计划将观测结果添加到自定义的度量标准中, 请使用此标记 . 这里的拇指规则是:只有在你的度量观察提出"这个度量不存在"的警告时才使用.sendMetrics: () => void: 向服务器发送参数。 注:默认情况下,这种方法称为 自动通过observe,但是如果跳过自动参数发送,可以手动调用.histogramBuckets: number[];: 用于配置在提供者中的直方图。 包含在这里 通常不需要这个.navigationData: NavigationData | null: 最后的导航数据.addObserveListener: (callback: ObserveCallback) => void;: 每当在登记册中添加一个观察时,都添加一个被调用的听众.removeObserveListener: (callback: ObserveCallback) => void;: 删除观察者registry: Registry: Bourjs regisry 实例。 你不应该直接使用这个, 但使用时observe换句话说 在一些极罕见的病例和测试中,它暴露在外.
食谱
调试
如果您想要检查您的度量衡是否被正确生成, 您可以添加 MetricsLogger 进入您的
组件树和所有度量观测将在控制台中显示.
const AppRoot = () => (
<MetricsProvider
appName="my-app-name"
owner="my-team"
getNormalizedPath={normalizePath}
metricsAggregatorUrl="https://some-metrics-aggregator.com/push-metrics"
>
<MetricsLogger />
<MyApp />
</MetricsProvider>
);
这将生成这样的日志条目 :
[prom_react] prom_react_navigation_duration_seconds 1.2456 {app_name: 'my_app', path: '/app', navigation_type: 'full_page' }
您可以自定义输出 MetricsLogger 替换原装入器:
const metricsLogger = ({ metricName, value, tags }) => {
console.debug('Custom log for prom-react!', metricName, value, tags);
};
const AppRoot = () => (
<MetricsProvider
appName="my-app-name"
owner="my-team"
getNormalizedPath={normalizePath}
metricsAggregatorUrl="https://some-metrics-aggregator.com/push-metrics"
>
<MetricsLogger logger={metricsLogger} />
<MyApp />
</MetricsProvider>
);
此外,您还可以添加一个将显示上次被触发的导航事件的部件 。 这是特别有用的检查 如果您的所有页面都有适当的仪器( 您应该浏览您的应用程序, 部件应该显示正确的路径 ) )),每节变换.
const AppRoot = () => (
<MetricsProvider
appName="my-app-name"
owner="my-team"
getNormalizedPath={normalizePath}
metricsAggregatorUrl="https://some-metrics-aggregator.com/push-metrics"
>
{process.env.NODE_ENV !== 'production' && (
<MetricsDebugOverlay withLogger onClose={closeOverlay} />
)}
<MyApp />
</MetricsProvider>
);
配置您的 Grafana 仪表板和 propetheus 提示
- 在特定时间范围内的平均活动会话:
increase(prom_react_app_loaded{app_name="$job", status="success"}[$__range]) -
on() increase(prom_react_app_unloaded{app_name="$job"}[$__range])
- 装入应用程序出错率 :
rate(prom_react_app_loaded{app_name="$job",status="failure"}[$__rate_interval]) /
rate(prom_react_app_loaded{app_name="$job"}[$__rate_interval])
- 以秒计的全页负荷长度的 Nth 个数 :
histogram_quantile($quantile,
sum(sum(rate(prom_react_navigation_duration_seconds_bucket{app_name="$job",navigation_type="full_page"}[$__rate_interval])
)
by (le, path)) without(path))
- 按路径排列的 RPS 页面 :
sum by (path)(rate(prom_react_navigation_duration_seconds_count{app_name="$job"}[$__rate_interval]) != 0)
- (普罗米修斯警报). 应用程序负载失败 :
ALERT AppLoadFailed
IF rate(prom_react_app_loaded{app_name="my-app",status="failure"}[5m]) /
rate(prom_react_app_loaded{app_name="my-app"}[5m]) > 0.1
FOR 15m
LABELS {...}
ANNOTATIONS {...}
获得正态 路径对象
如果您的路由被定义在一个类似全球对象中( 您以后使用) 例如,在反应路由器配置中:
const Urls = {
INDEX: '/app',
PRODUCTS: '/app/products',
PRODUCT_DETAIL: 'app/product/:id',
...
}
很容易创建 getNormalizedPath 函数来源:
import { pathToRegexp } from 'path-to-regexp';
const urlRegExps = Object.values(Urls).map((url) => ({
regExp: pathToRegexp(url),
url,
}));
export const getNormalizedPath = (url: string) => {
return urlRegExps.find(({ regExp }) => regExp.test(url))?.url || url;
};
在网关请求中添加授权页眉
// src/index.tsx
import { MetricsProvider } from '@cabify/prom-react';
const gatewayFetchOptions = {
headers: {
Authorization: `Basic ${btoa('login:password')}`,
},
};
const AppRoot = () => (
<MetricsProvider
appName="my-app-name"
owner="my-team"
fetchOptions={gatewayFetchOptions}
metricsAggregatorUrl="https://some-metrics-aggregator.com/push-metrics"
>
<App />
</MetricsProvider>
);
自动检查您的所有页面是否包含导航标记
如果您可以轻松地用文件名识别您的页面根组件( 例如如果它们)
总是被命名 <SectionName>Page.tsx),很容易自动添加一个简单的 shell 脚本
请检查所有设备是否齐全。 这样可以避免错误的导航度量值
(您也可以在您的 CI 管道或预承诺的脚本中添加这样的脚本, 只是为了保证一个乐器
代码不能达到生产). 作为额外的提示, 如果有匹配您的页面名称结构的文件
而非页面(或页面被另置),您可以添加被忽略的coment 爱斯林特
(预算外). // prom-react-ignore) (中文(简体) ).
echo "Checking if all pages are using 'usePerformanceMark'"
OUTPUT=$(grep --include='*Page.tsx' -Lr 'usePerformanceMark\|prom-react-ignore' .)
if [ -z "$OUTPUT" ]; then
echo "Everything ok"
else
echo "There are pages that are not using 'usePerformanceMark'"
echo "$OUTPUT"
echo "Please start using 'usePerformanceMark' on them or add // prom-react-ignore to ignore that file"
exit 1
fi
捐款
- 运行测试和起伏:
yarn test - 构建工程 :
yarn build
发布新版本
- 更新 变化 具有新特性, 断开更改等
- 检查你英寸
main分支和一切是最新的. - 运行
yarn publish:<major|minor|patch>或者说yarn publish:canary为金丝雀版本. - 运行
git push && git push --tags - 请检查access-date=中的日期值 (帮助) 上次推后触发的所有测试动作均为QQ.
- 转到 创建新发行,选择先前所推动的标签并写入标题.
- 请检查date=中的日期值 (帮助) Npm 发布动作已成功完成 .
- 检查 npm 包网页,该版本已在
latest标签.
贡献者
感谢这些伟大的人emoji 密钥:
 哈维尔·洛佩斯 💻 |
 亚历杭德罗 💻 |
 瓦伦丁·柏林 💻 |
 亚历杭德罗·加利亚多·埃斯科瓦尔 💻 |
 基督教徒 💻 |
 里卡多·博卢达 💻 |
 巴勃罗·马尔克斯 💻 |
 莱尔·里科 💻 |
 罗德里戈 💻 |
 亚历克斯·特米纳 💻 |
 费尔南德斯·阿莫尔 💻 |
本项目遵循 全部贡献者 规格。 任何捐款都欢迎!