Grafana 集成
Tuist 数据源让你能在 Grafana 中使用构建、测试和缓存指标,包括耗时、失败次数以及缓存报告的节省时间。围绕团队关注的项目和指标构建仪表板,或将 Tuist 指标与公司现有仪表板中的其他数据源结合。利用 Grafana 的告警规则和通知渠道,在构建变慢或失败增加时提醒团队。
可用指标#
表格列出了可读标签及其查询标识符。构建健康度查询使用 metric 字段中的标识符;构建和测试耗时查询在 series 字段中选择 average、p50、p90 或 p99。
构建次数与可靠性#
| 指标 | 标识符 | 衡量内容 |
|---|---|---|
| 构建次数 | builds |
记录的构建数量。 |
| 成功构建 | successful_builds |
成功完成的构建。 |
| 失败构建 | failed_builds |
失败的构建。 |
| 取消构建 | cancelled_builds |
记录为已取消的构建。参见构建系统差异。 |
| 构建成功率 | success_rate |
成功 ÷(成功 + 失败),以百分比表示。 |
| 失败或缓慢构建 | builds_needing_attention |
失败或缓慢的构建,每次构建仅计一次。 |
构建与测试耗时#
| 指标 | 标识符 | 衡量内容 |
|---|---|---|
| 平均耗时 | average |
所选运行的平均耗时。 |
| 中位数耗时 | p50 |
运行耗时的第 50 百分位数。 |
| 第 90 百分位数耗时 | p90 |
90% 的运行耗时低于或等于该值。 |
| 第 99 百分位数耗时 | p99 |
99% 的运行耗时低于或等于该值。 |
| 缓慢构建阈值 | slow_build_threshold |
第 90 百分位数耗时,或你设置的固定毫秒限制。 |
测试耗时指标使用 Tuist 中记录的测试运行。缓慢构建阈值仅适用于构建:当构建耗时超过该阈值时,视为缓慢构建。取消的构建单独计数,不计入构建成功率。
缓存节省#
| 指标 | 标识符 | 衡量内容 |
|---|---|---|
| 累计任务时间节省(Gradle) | cache_work_avoided |
缓存命中避免的任务执行时间的估算总和。 |
| 报告累计任务时间的构建 | cache_work_avoided_samples |
具有完整估算的构建。 |
| 报告的缓存节省时间 | cache_time_saved |
报告的已用时间节省总和。 |
| 报告缓存节省时间的构建 | cache_time_saved_samples |
具有有效节省值的构建。 |
Gradle 插件会自动报告本地和远程任务缓存命中所避免的估算工作量。对于每个缓存任务,它会从 Gradle 存储的原始执行时间中减去任务的恢复耗时,最小值为零。构建估算是将这些值相加得出的。并行任务可能会重叠,因此这是累计任务时间,而非节省的已用构建时间。最新任务和跳过的任务不包括在内。
没有任务缓存命中的构建报告为零。如果任何缓存任务缺少其原始计时、遥测数据不完整或自定义元数据映射没有空间,插件将省略该估算。旧版本的插件和其他构建系统不报告此数据。将报告计数与总构建数进行比较以检查覆盖率。
报告的已用时间节省来自 tuist.cache_time_saved_ms 元数据。此指标与自动估算保持独立。
当没有构建报告时,缓存节省没有价值。Once 目前不记录此测量值。通过此数据源无法获取缓存命中率和未命中率。
表格#
这些标识符是查询的 queryType 字段的值。
| 表格 | 查询类型 | 内容 |
|---|---|---|
| 按工作负载的健康状况 | buildWorkloads |
构建次数、成功率、中位数和第 90 百分位数耗时。 |
| 失败类别 | buildFailureReasons |
所有失败及其按失败类别的计数。 |
| 最近的失败构建 | buildRecentFailures |
最新的 100 次失败,附带指向 Tuist 的链接。 |
最近的失败包括开始时间、耗时、用户、分支和请求的任务。失败类别为 verification、infrastructure_tooling 和 unknown。
工作负载摘要和分支/工作负载值列表最多返回 1000 个值。构建健康度变量查询使用过去 90 天的数据;旧版 Gradle 变量查询保留其现有的历史窗口。Bazel 显示由工具报告的构建用户。其他集成显示与报告凭据关联的账户。历史 Bazel 和 Once 运行,以及使用项目凭据报告的 Once 运行,在未记录用户时显示为“未知”。
在“构建运行”上使用“失败类别”过滤器来查找匹配的失败。该类别出现在构建详细信息中,并带有解释其含义的信息提示;默认概览和“构建运行”表格保留其现有列。成功、取消和未完成的构建没有失败类别。Gradle 的“缓存分析”卡片和构建详细信息显示“累计任务时间节省”;工具提示解释了估算值以及并行任务的影响。缓存小部件使用相同的过滤器,将所选范围与紧接的前一个等长时期进行比较。比较是中性的:较大的总数可能反映更多的构建。缺少之前的估算值时不显示比较;记录的零基线显示绝对增加量而非百分比。
标准仪表板#
导入构建健康度仪表板,然后选择你的数据源和项目。它包括构建次数、成功率、中位数和第 90 百分位数耗时、缓慢构建阈值、中性的失败或缓慢构建计数、分组的缓存节省和报告覆盖率,以及三个失败和工作负载表格。根据需要为其他可用指标添加面板。自动缓慢阈值是所选时期自身的第 90 百分位数;高于该阈值的构建不一定表示回归。为耗时目标告警设置固定阈值。缓存面板优先显示 Gradle 的自动累计任务时间估算及其覆盖率,其次是明确报告的已用时间节省及其各自的覆盖率。
构建系统#
构建健康度查询和标准仪表板支持 Bazel、Cargo、Once、Gradle 和 Xcode。Tuist 从你的项目中选择构建系统。混合项目目前不受构建健康度查询或标准仪表板支持。
| 构建系统 | 工作负载 | 取消报告 | 缓存节省 |
|---|---|---|---|
| Bazel | 命令 | 退出代码 8,除了 run |
需要自定义元数据 |
| Cargo | 命令 | 未区分;计数为零 | 已用时间节省需要自定义元数据;避免的编译器工作不计入已用时间节省 |
| Once | 命令类型 | 记录的取消原因 | 未记录 |
| Gradle | 任务组 | 报告的取消 | 自动避免工作估算;已用时间节省需要自定义元数据 |
| Xcode | 方案 | 未区分;计数为零 | 需要自定义元数据 |
处理中的记录和未完成的运行被排除。Bazel 包括构建、测试、运行和覆盖率命令。Once 包括已完成的构建、测试和通用运行。Cargo 包括诸如 build、check 和 test-build 等构建命令;旧版测试执行报告不包含在构建健康度中。Cargo 最近的失败在可用时使用记录的启动时间,否则回退到插入时间;缺失的持续时间保持不可用而非零。
Gradle 按优先级顺序将任务分组为插桩测试、单元测试、lint/检查、组装/打包或其他。每个构建属于一个工作负载。自定义元数据可以覆盖 Xcode、Bazel、Cargo 和 Gradle 的工作负载。
失败类别#
| 类别 | 含义 | 记录的证据 |
|---|---|---|
verification |
代码编译、链接、测试或检查失败。 | Gradle 验证或编译异常及已知失败的任务类型;Xcode 编译器和链接器问题;Bazel 结构化的非零编译器/测试操作结果;Cargo 记录的失败 rustc 编译;Once 测试失败或明确声明为编译、链接、测试、lint 或检查的失败操作。 |
infrastructure_tooling |
由于工具、依赖项或环境故障,构建无法正常进行。 | Gradle 配置、依赖解析、输入/输出或内存故障;Bazel 结构化基础设施故障和文档化的退出代码;Once 基础设施操作错误。 |
unknown |
报告没有包含足够的证据来对失败进行分类。 | 任意命令、缺少诊断信息以及没有结构化证据的旧报告。 |
Gradle 配置阶段失败(包括构建脚本中的错误)被归类为基础设施/工具,因为任务执行无法继续。
没有明确类别元数据或记录的失败 rustc 编译的 Cargo 失败仍保持为 unknown;仅失败的 check 或 test-build 命令不足以确立验证失败。Cargo 任务重用计数器和估算的避免编译器工作从不提供已用缓存节省或 Gradle 的累计任务时间指标。
显式的 tuist.failure_category 元数据会覆盖自动分类。否则,当构建中同时出现基础设施和验证证据时,基础设施证据优先。失败的任意脚本不被假定为编译器或测试失败。历史报告可以使用 Tuist 已存储的证据,但新的报告字段不会回填缺失的信息。自动报告元数据使用现有 20 条目自定义元数据限制内的可用空间。
buildFailureReasons 响应保留其 all 行以保持兼容性。标准仪表板将该总数从“失败类别”图表中过滤掉,并单独显示总失败数。旧版 gradleFailureReasons 查询保留其原始的三个类别行。
查询选项#
数值查询使用这些 queryType 值:
| 查询 | 查询类型 |
|---|---|
| 构建健康度 | buildHealth |
| Xcode 构建耗时 | buildDuration |
| 测试耗时 | testDuration |
resultMode 字段控制结果的返回方式:
| 结果 | 值 | 行为 |
|---|---|---|
| 时间序列 | series |
每个区间一个值。 |
| 整个周期 | total |
根据范围内所有运行计算出的一个值。 |
筛选标签映射到以下查询字段:
| 筛选条件 | 查询字段 | 适用于 |
|---|---|---|
| 环境 | environment |
所有查询 |
| 分支 | gitBranch |
构建健康度查询和表格 |
| 工作负载 | workload |
构建健康度查询和表格 |
| 状态 | status |
构建健康度查询、表格和 Xcode 耗时 |
| Scheme | scheme |
Xcode 构建和测试耗时 |
| 配置 | configuration |
Xcode 构建耗时 |
| 构建类型 | category |
Xcode 构建耗时 |
环境值为 any、ci(自动化构建)和 local。状态值为 success、failure,对于构建健康度查询还包括 cancelled;省略该值以包含所有状态。构建类型值为 clean 和 incremental;省略该值以同时包含两者。
空的构建健康度区间计数为零,且没有平均耗时、耗时百分位数或成功率值。慢构建阈值仍使用所选的完整范围。单独的测试耗时查询对空时间序列区间返回零。整个周期的百分位数是根据运行计算的,而不是根据区间百分位数计算的。构建健康度百分位数使用精确聚合;单独的 Xcode 和测试耗时查询使用近似百分位数。
构建健康度时间序列将部分第一个桶放置在所选范围的起始位置,以保持其可见性。旧版 Gradle 查询保留其原始的桶时间戳。
所有查询接受的日期范围最长为 366 天。它们的边界和时间戳有所不同:
| 查询 | 使用的时间戳 | 范围边界 |
|---|---|---|
| 构建健康度:Xcode、Bazel、Cargo、Gradle | 记录插入时间 | 包含起始,排除结束 |
| 构建健康度:Once | 运行开始时间 | 包含起始,排除结束 |
| Xcode 构建耗时 | 记录插入时间 | 排除起始和结束 |
| 测试耗时 | 记录的运行时间 | 包含起始和结束 |
仪表盘变量#
为项目和受支持的筛选条件使用仪表盘变量。分支和工作负载变量使用以下查询:
| 变量 | 查询 |
|---|---|
| 分支 | buildBranches account/project |
| 工作负载 | buildWorkloads account/project |
筛选条件接受一个精确值。对于分支和工作负载变量,将“全部”选项的自定义值设置为 __tuist_all__。其他筛选条件使用其内置的“任意”选项或空值。不支持多选和正则表达式。
报告自定义元数据#
Xcode、Bazel、Cargo 和 Gradle 构建接受以下可选元数据值:
| 键 | 接受的值 |
|---|---|
tuist.workload |
替换默认分组的工作负载名称。 |
tuist.failure_category |
verification 或 infrastructure_tooling。 |
tuist.cache_work_avoided_ms |
仅限 Gradle。自动报告的避免工作量估算值,单位为整数毫秒,最长可达 365 天。 |
tuist.cache_time_saved_ms |
0 到 31,536,000,000(365 天)之间的整数毫秒数。 |
通过构建集成的自定义元数据配置提供这些值:
{
"custom_metadata": {
"values": {
"tuist.workload": "Release verification",
"tuist.failure_category": "verification",
"tuist.cache_time_saved_ms": "12000"
}
}
}
仅当你有该构建的耗时测量值或有文档记录的估算值时,才报告缓存节省量。当任务并发运行时,仅凭缓存命中和累计任务持续时间无法确定已节省的耗时。缺失的缓存节省量仍为未知。缺失的失败类别元数据会回退到记录的证据,如 构建系统 中所述。数据保留策略不变。
告警和 Slack#
创建带有数值指标的 Grafana 管理告警规则。例如:
| 指标 | 标识符 | 示例条件 |
|---|---|---|
| 构建成功率 | success_rate |
低于 99% |
| 失败的构建 | failed_builds |
高于零 |
| 第 90 百分位耗时 | p90 |
高于团队的耗时限制 |
使用 整个周期 获取评估窗口内的单个值,或将时间序列缩减为单个值。对于“整个周期”模式下的耗时查询,请选择一个序列。
- 使用固定的项目和筛选值。在后台告警评估期间,仪表盘变量不可用。
- 对告警使用数值查询。要监控某个工作负载,请将构建健康度查询筛选到该工作负载。
- 为没有构建或报告缓存节省量的区间设置规则的无数据行为。
配置 Slack 联系人 并通过 Grafana 的通知策略将规则路由到该联系人。Grafana 发送通知并存储 Slack 凭据。
升级现有仪表盘#
现有的耗时面板保留其查询、筛选条件、序列名称和单位。已保存的 Gradle 健康面板和变量也继续有效。
单独导入标准仪表盘以使用共享的构建健康度查询。现有仪表盘不会自动迁移。共享查询需要提供构建健康度端点的 Tuist 服务器;现有的耗时查询仍可与旧版服务器配合使用。
要求#
- Grafana 10.4 或更高版本。
- 具有读取你要绘制图表的项目和指标权限的 Tuist 令牌。请参阅下方的 身份验证。
身份验证#
使用 账户令牌 进行仪表盘和后台告警评估。授予 project:builds:read 以获取构建指标,授予 project:tests:read 以获取测试耗时,并将访问权限限制为你要绘制图表的项目。仅需授予你所用指标对应的范围。按照 令牌创建说明 生成一个令牌。
该集成还接受用于其自身项目的现有项目令牌,以及具有用户读取权限的 用户访问令牌。用户访问令牌的有效期较短。Grafana 存储你提供的令牌,但不会刷新它或重用你的本地 Tuist 登录状态;请在令牌过期时更换。账户令牌让你能够独立于用户的登录会话来控制项目访问、权限和过期时间。
配置#
添加数据源并设置:
| 字段 | 保存的设置 | 备注 |
|---|---|---|
| 服务器 URL | jsonData.url |
默认为 https://tuist.dev。 |
| 令牌 | secureJsonData.apiToken |
Tuist bearer 令牌,加密存储。 |
选择 保存并测试 以检查连接。Grafana 会列出可访问的项目,然后针对第一个项目检查构建和测试的读取权限。
安装#
从 Grafana 目录安装#
发布后,像其他任何数据源一样从 Connections → Add new connection → Tuist 安装,或使用 grafana-cli plugins install tuist-metrics-datasource 安装。
在发布之前(自托管 Grafana)#
该插件在获得目录批准之前处于未签名状态。在自托管实例上,你可以:
- 允许未签名加载 — 将
tuist-metrics-datasource添加到allow_loading_unsigned_plugins(或GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=tuist-metrics-datasource),然后将构建好的插件放入你的插件目录。 - 为你的实例私有签名 —
npm run sign -- --rootUrls https://grafana.example.com(URL 必须与实例的root_url匹配),然后分发 zip 文件。
Grafana Cloud 要求使用目录中的插件,不支持未签名或手动上传的插件。