法罗CLI
用于将源地图上传到使用cURL的法罗源地图API的命令行界面.
安装
npm install --save-dev @grafana/faro-cli
或者说
yarn add --dev @grafana/faro-cli
所需资源
- cURL 必须在您的系统中安装,并在您的路径中可用 .
使用量
上传源代码地图
CLI使用头罩下方的cURL将源图上传到法罗API.
网页( Webpack / Vite / 滚动 / Rspack) :
npx faro-cli upload \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id "your-bundle-id" \
--output-path "./dist" \
--verbose
对 CI , 设定 FARO_SOURCEMAP_API_KEY 在环境中,并省略 --api-key. 明确旗帜在两种旗帜设置时优先.
原生反应( Metro) :
npx faro-cli metro upload \
--map "path/to/your.map" \
--endpoint "$FARO_SOURCEMAP_ENDPOINT" \
--app-id "$FARO_SOURCEMAP_APP_ID" \
--stack-id "$FARO_SOURCEMAP_STACK_ID" \
--api-key "$FARO_SOURCEMAP_API_KEY" \
--bundle-id "$FARO_BUNDLE_ID" \
--verbose
两个命令只有不同 他们是如何发现地图上传的数字 :
upload(web)通过--output-path逐一扫描.map文档。 你不列举路径 也不担心嵌入式文件夹.metro upload(反应原生)一个.map路径通过--map. CLI从未从此路径本身得到——呼叫者(Gradle hook,Xcode后构建脚本,手动引用)负责指向正确的文件.--bundle-id(或FARO_BUNDLE_ID)必须匹配任何id@grafana/faro-metro-plugin被烤入运出JS的包里 所以上传的地图密钥 到了法罗的运行时间遥测。 见@grafana/faro-metro-plugin读取 用来传递哪个平台的地图.
两个命令在每次飞行前都做同样的轻量级飞行 .map 上传前: 将其解析为 JSON, 验证它是一个 v3 源地图, 并( 与下游符号相容 ) 回写 file 属性,如果缺少。 他们从来不碰 mappings, (中文(简体) ), sources,或 sourcesContent 字段。 见 连接设置优先 财务报告和审定财务报表 验证和退出代码 整个合同.
文件大小限制
法罗API对单个文件默认上传有30MB的限制. 这个限制适用于文件的未压缩大小,无论在传输过程中是否使用压缩. CLI 通过:
- 上传前正在检查文件大小
- 关于超过限制的文件的警告
- 跳过太大的文件
- 以流媒体方式处理文件, 累积文件直至达到大小限制后再上传每批文件
这种流出方式是捆绑插件使用的同一种方法,确保所有上传方法的行为一致. CLI智能地逐一处理文件,在达到大小限制时上传批次,在保持API大小限制的同时优化上传过程.
虽然 --gzip-payload 选项可以显著地减少网络传输大小,原始未压缩文件大小仍然必须在配置的大小限制下才能被API接受.
您可以使用 --max-upload-size 选项,允许您在字节中指定不同的大小限制。 然而,您必须提交Grafana Cloud的支持票,以提高后端的限制.
Gzipping 选项
CLI提供了两种不同的gzipping选项来优化上传:
-
Gzip 内容
-g, --gzip-contents(中文(简体) ):在上传前将多源映射文件压缩为tarball. 文件采用流式处理方式,累积到达到30MB极限后再创建并上传出每个柏球. 这在同时上传多个文件时有用. -
Gzip 有效载荷
-z, --gzip-payload(中文(简体) ):使用gzip内容编码压缩HTTP有效载荷本身. 这可以大大地缩小上传大小,对大源地图文件特别有用.
Gzip 有效载荷示例 :
npx faro-cli upload \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id "your-bundle-id" \
--output-path "./dist" \
--patterns "*.map" \
--gzip-payload \
--verbose
可以同时使用两种选项进行最大压缩 :
npx faro-cli upload \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id "your-bundle-id" \
--output-path "./dist" \
--patterns "*.map" \
--gzip-contents \
--gzip-payload \
--verbose
对于 metro upload,击出是 默认 (单位:千美元) .map 被装作被涂抹的焦油球。 过 --no-gzip 输入原始 .map JSON 取而代之 —— 在调试上传到管理器的代理服务器时有用 Content-Encoding。 。 。 .
使用代理服务器
如果您需要通过代理服务器传送请求, 您可以使用 --proxy 选项 :
npx faro-cli upload \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id "your-bundle-id" \
--output-path "./dist" \
--proxy "your-proxy:port" \
--proxy-user "user:pass" \
--verbose
代理 URL 将使用 --proxy 参数。 如果您的代理需要认证, 您可以使用 --proxy-user 选项(或 -U以格式提供全权证书 username:password。同样的 --proxy 财务报告和审定财务报表 --proxy-user 旗子同样使用 metro upload。 。 。 .
将套装ID注入 JavaScript 文件
对于不使用Webpack或Rollup的应用程序,或者在需要将捆绑的ID添加到已经建成的JavaScript文件时,可以使用 inject-bundle-id 命令 :
npx faro-cli inject-bundle-id \
--bundle-id "your-bundle-id" \
--app-name "your-app-name" \
--files "dist/**/*.js" \
--verbose
此命令将 :
- 定位所有符合指定 glob 模式的 JavaScript 文件
- 检查每个文件是否有捆绑的ID片段
- 将捆绑的ID片断保存到没有它的文件
- 将捆绑的ID导出到环境变量, 以便日后与其他命令一起使用
选项
--bundle-id, -b: 需要注入的捆绑ID( 空白生成随机ID)--app-name, -n: 捆绑ID片断中使用的应用程序名称--files, -f: 要匹配的文件模式( 可指定多种模式)--verbose, -v: 启用动词记录--dry-run, -d: 只打印将修改的文件而不修改
实例
生成随机捆绑的ID并注入所有JS文件:
npx faro-cli inject-bundle-id \
--app-name "my-app" \
--files "dist/**/*.js" \
--verbose
首先进行干线运行, 查看哪些文件将被修改 :
npx faro-cli inject-bundle-id \
--bundle-id "your-bundle-id" \
--app-name "my-app" \
--files "dist/**/*.js" \
--dry-run \
--verbose
只有网络. 这个命令是针对尚未整合出法罗插件的Web捆绑者所生产的已经建成的JavaScript捆绑. 反应原生( Metro) 流通过 Metro 时间注入捆绑的ID
@grafana/faro-metro-plugin序言,所以你别跑inject-bundle-id在RN捆绑.
将 Git Hash 注入 JavaScript 文件
用于无法访问的应用程序 .git 目录,或者在建设后的管道中,如果您想要将已经建成的JavaScript文件印入执行散列,请使用 inject-git-hash 命令 :
npx faro-cli inject-git-hash \
--app-name "your-app-name" \
--files "dist/**/*.js" \
--verbose
何时 --git-hash 未提供命令,命令通过 git rev-parse HEAD。如果散列无法解决,则命令以非零错误代码退出.
CI的明确散列:
npx faro-cli inject-git-hash \
--git-hash "$GITHUB_SHA" \
--app-name "your-app-name" \
--files "dist/**/*.js"
选项
--git-hash, -g:基特将散列注射. 自动检测通过git rev-parse HEAD如果未提供; 如果无法解决,则有出错.--app-name, -n: git 散列片段中使用的应用程序名( 需要)--files, -f: 要匹配的文件模式( 支持 glob 模式)--verbose, -v: 启用动词记录--dry-run, -d: 在不修改的情况下打印哪些文件
使用 Bundler 插件
使用 Faro 捆绑插件时, 您可以设置 skipUpload 选项到 true 在插件配置中,在构建过程中跳过上传源图,取而代之的是使用 CLI 后上传.
滚动示例
// rollup.config.js
import faroUploader from '@grafana/faro-rollup-plugin';
export default {
// ... other rollup config
plugins: [
// ... other plugins
faroUploader({
// this URL is different from the Faro Collector URL - find this value in the Frontend Observability plugin under "Settings" -> "Source Maps" -> "Configure source map uploads"
endpoint: 'https://faro-api-prod-us-east-0.grafana.net/faro/api/v1',
appName: 'my-app',
appId: 'your-app-id',
apiKey: 'your-api-key',
stackId: 'your-stack-id',
skipUpload: true, // Skip uploading during build
verbose: true,
}),
],
};
然后,在构建之后,您可以使用 CLI 上传源图 :
npx faro-cli upload \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id env \
--app-name "my-app" \
--output-path "./dist" \
--verbose
注意使用 --bundle-id env 财务报告和审定财务报表 --app-name "my-app" 从捆绑器插件设置的环境变量读取捆绑ID.
网页包示例
// webpack.config.js
const FaroSourceMapUploaderPlugin = require('@grafana/faro-webpack-plugin');
module.exports = {
// ... other webpack config
plugins: [
// ... other plugins
new FaroSourceMapUploaderPlugin({
endpoint: 'https://faro-api-prod-us-east-0.grafana.net/faro/api/v1',
appName: 'my-app',
appId: 'your-app-id',
apiKey: 'your-api-key',
stackId: 'your-stack-id',
skipUpload: true, // Skip uploading during build
verbose: true,
}),
],
};
Metro 示例( 本地反应)
@grafana/faro-metro-plugin 是Webpack/Rollup 本地反应插件的等效。 它支持同样的 skipUpload 选项,含义相同: true,插件不会上传.
// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const withFaroConfig = require('@grafana/faro-metro-plugin').default;
const faroOpts = {
appName: 'MyApp',
endpoint: 'https://faro-api-prod-us-east-0.grafana.net/faro/api/v1',
appId: 'your-app-id',
stackId: 'your-stack-id',
apiKey: process.env.FARO_SOURCEMAP_API_KEY,
bundleId: process.env.FARO_BUNDLE_ID,
verbose: true,
};
module.exports = mergeConfig(
getDefaultConfig(__dirname),
withFaroConfig({}, faroOpts),
);
手册引用每个平台的形状相同:
npx faro-cli metro upload \
--map "path/to/your.map" \
--endpoint "$FARO_SOURCEMAP_ENDPOINT" \
--app-id "$FARO_SOURCEMAP_APP_ID" \
--stack-id "$FARO_SOURCEMAP_STACK_ID" \
--api-key "$FARO_SOURCEMAP_API_KEY" \
--bundle-id "$FARO_BUNDLE_ID"
每个连接设置(和 --bundle-id)也接受匹配 FARO_* 如果旗子被省略了, 反倒会掉下来, 所以这个步骤已经输出了全部 FARO_* 设置可以调用 faro-cli metro upload --map … 没有别的了.
生成卷轴命令
如果喜欢直接使用卷曲,可以生成卷曲命令. 网络示例 :
npx faro-cli curl \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id "your-bundle-id" \
--file "./dist/main.js.map"
原生反应( 地铁) —— 相同 curl 子命令,仅指点 --file 地点 .map 您想要上传和通过 捆绑的ID 匹配您的运出 JS:
npx faro-cli curl \
--endpoint "$FARO_SOURCEMAP_ENDPOINT" \
--app-id "$FARO_SOURCEMAP_APP_ID" \
--api-key "$FARO_SOURCEMAP_API_KEY" \
--stack-id "$FARO_SOURCEMAP_STACK_ID" \
--bundle-id "$FARO_BUNDLE_ID" \
--file "path/to/your.map"
您也可以生成使用 gzip 压缩的卷曲命令 :
npx faro-cli curl \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id "your-bundle-id" \
--file "./dist/main.js.map" \
--gzip-payload
您也可以生成一个使用代理的卷曲命令 :
npx faro-cli curl \
--endpoint "your-faro-sourcemap-api-url" \
--app-id "your-app-id" \
--api-key "your-api-key" \
--stack-id "your-stack-id" \
--bundle-id "your-bundle-id" \
--file "./dist/main.js.map" \
--proxy "http://proxy.example.com:8080" \
--proxy-user "username:password"
这将输出一个可以手动复制和运行的卷轴命令 .
选项
上传命令
-e, --endpoint <url>: Faro API 端点 URL( 需要) - 在前端可观察性插件中查找此值 设置 - > (中文) 来源地图 - > (中文) 配置源地图上传-a, --app-id <id>: Faro 应用程序 ID( 需要)-k, --api-key <key>:法罗API密钥. 倒计时FARO_SOURCEMAP_API_KEY当省略时.-s, --stack-id <id>: Faro sack ID( 需要) - 在前端可观察性插件中查找此值 设置 - > (中文) 来源地图 - > (中文) 配置源地图上传-b, --bundle-id <id>: Bundle ID(需要,可以设置为"env"从环境变量读取)-o, --output-path <path>: 含有源地图的目录路径( 需要)-n, --app-name <name>: 应用程序名称(用于在环境变量中查找 bundId)-k, --keep-sourcemaps: 上传后保留源地图( 默认: 假)-g, --gzip-contents: 上传前将源图压缩为 tarball; 文件处理方式为流式, 累积到大小限制( 默认: 假)-z, --gzip-payload: Gzip HTTP 有效载荷用于更小的上传( 默认: 假)-v, --verbose: 启用动词记录( 默认: 假)-r, --recursive: 递归搜索源地图的子目录( 默认: 假)-i, --max-upload-size <size>: 最大上传大小为字节,默认为30MB. 法罗API对单个文件默认上传有30MB的限制. 在特殊情况下,可以通过联系Grafana Cloud支持来改变这一限制.-x, --proxy <url>: 用于 cURL 请求的代理 URL( 可选)-U, --proxy-user <user:password>: 代理认证的用户名和密码( 可选)
注入- git- hash 命令
-g, --git-hash <hash>: Git 将散列注射(自动通过git rev-parse HEAD如果未提供; 如果无法解决则有出错的退出)-n, --app-name <name>: git 散列片段中使用的应用程序名( 需要)-f, --files <patterns...>: 要匹配的文件模式( 支持 glob 模式)-v, --verbose: 启用动词记录( 默认: 假)-d, --dry-run: 打印将修改哪些文件而不做修改( 默认: 假)
曲线命令
-e, --endpoint <url>: Faro API 端点 URL( 需要) - 在前端可观察性插件中查找此值 设置 - > (中文) 来源地图 - > (中文) 配置源地图上传-a, --app-id <id>: Faro 应用程序 ID( 需要)-k, --api-key <key>: Faro API 密钥( 需要)-s, --stack-id <id>: Faro sack ID( 需要) - 在前端可观察性插件中查找此值 设置 - > (中文) 来源地图 - > (中文) 配置源地图上传-b, --bundle-id <id>: Bundle ID(需要,可以设置为"env"从环境变量读取)-f, --file <path>: 源地图文件路径( 需要)-n, --app-name <name>: 应用程序名称(用于在环境变量中查找 bundId)-t, --content-type <type>: 上传的内容类型( 默认为“ 应用程序/ json ”)-z, --gzip-payload: 生成一个命令, 以 gzips 有效载荷( 默认: 假)-x, --proxy <url>: 用于 cURL 请求的代理 URL( 可选)-U, --proxy-user <user:password>: 代理认证的用户名和密码( 可选)
地铁上传命令( E)metro upload(中文(简体) )
--map <path>(需要): 通往.map要上传的文件。 CLI确实如此 不从此路径获取或自动检测到此路径——呼叫者选择文件.-e, --endpoint <url>: 法罗源图 API Base URL. 倒计时FARO_SOURCEMAP_ENDPOINT。 。 。 .-a, --app-id <id>: 法罗应用id. 倒计时FARO_SOURCEMAP_APP_ID。 。 。 .-s, --stack-id <id>: 格拉法纳 云叠取出. 倒计时FARO_SOURCEMAP_STACK_ID。 。 。 .-k, --api-key <key>: Bearer API 键. 倒计时FARO_SOURCEMAP_API_KEY。 。 。 .-b, --bundle-id <id>与运出JS捆绑物匹配的包装ID. 倒计时FARO_BUNDLE_ID。 。 。 .--no-gzip: 将原始的.mapJSON代替了被咬了的焦油球.-v, --verbose:活塞伐木.--dry-run: 显示要上传和退出的内容 .-i, --max-upload-size <size>: 最大上传大小为字节( 默认: 30MB) .-x, --proxy <url>, (中文(简体) ),-U, --proxy-user <user:password>:与其他子命令相同.
连接设置优先
对于每个连接设置和捆绑的ID,解析是"第一个非空取胜": CLI 旗帜 > 匹配 Env var。 。 。 .
| 设置 | CLI 旗帜 | 信封倒置 |
|---|---|---|
| 终点基地 | --endpoint | FARO_SOURCEMAP_ENDPOINT |
| 应用代码 | --app-id | FARO_SOURCEMAP_APP_ID |
| 堆叠编号 | --stack-id | FARO_SOURCEMAP_STACK_ID |
| API 密钥 | --api-key | FARO_SOURCEMAP_API_KEY |
| 套装标识 | --bundle-id | FARO_BUNDLE_ID |
地图路径( E)--map)为 所需经费 并且没有内伏 或自动检测.
验证和退出代码
这个 .map 在任何上传尝试之前,解析并进行结构验证。 CLI从不检查或改写 mappings, (中文(简体) ), sources,或 sourcesContent; 如果 file 属性缺失, 它从地图文件名中设置, 因此下游符号可以按键 .
| 退出代码 | 含义 |
|---|---|
0 | 上传成功(或) --dry-run 结束). |
1 | 尝试上传, API 拒绝了( 重运行 ) --verbose) (中文(简体) ). |
2 | 飞行前失败: 缺少所需的设置, 缺少/ 无法解析的地图, 非 v3 地图, 或地图超过大小限制 . |
3 | 地图被解析为 v3 但它的 sources 阵列为空 。 无论产生什么结果,文件都发布了一个结构有效但无用的地图;调查CLI的上游. 将 CI 线连接到此代码 . |
许可证
阿帕奇 - 2.0