遥测

Tuist 提供三种互补的可观测性信号：指标（Prometheus）、追踪（OpenTelemetry）和日志（兼容 Loki）。这三者均为可选，可以独立启用。

分布式追踪（OpenTelemetry）#

Tuist 支持使用 OpenTelemetry 进行分布式追踪。启用后，服务器会为 HTTP 请求（Phoenix 和 Bandit）、数据库查询（Ecto）、出站 HTTP 调用（Finch）以及 Broadway 消息处理发出追踪数据。这些追踪数据可帮助你了解请求延迟、识别慢查询，并跨服务跟踪请求。

配置#

设置以下环境变量以启用追踪导出：

环境变量	描述	必填	默认值	示例
`TUIST_OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry Collector 的 gRPC 端点（例如 Grafana Alloy、Jaeger 或任何兼容 OTLP 的收集器）	否		`http://localhost:4317`

未设置此变量时，追踪功能处于禁用状态，不会增加任何开销。

已插桩的库#

启用追踪后，以下库会自动进行插桩：

Bandit -- HTTP 服务器连接跨度
Phoenix -- 请求生命周期跨度（控制器操作、LiveView）
Ecto -- 带有查询元数据的数据库查询跨度
Finch -- 出站 HTTP 客户端请求跨度
Broadway -- 消息处理管道跨度

使用 Grafana Alloy 的示例设置#

如果你使用 Grafana Alloy 作为收集器，请将其配置为接收 OTLP 追踪数据并将其转发到你的追踪后端（例如 Grafana Cloud Tempo）：

plaintext

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4317"
  }
  output {
    traces = [otelcol.exporter.otlp.your_backend.input]
  }
}

然后设置 TUIST_OTEL_EXPORTER_OTLP_ENDPOINT 指向 Alloy 实例，例如 http://alloy:4317。

日志转发（Loki）#

Tuist 可以将应用日志转发到兼容 Loki 的端点。这使你可以将日志与指标和追踪集中在一起，形成完整的可观测性视图。日志通过 Loki HTTP 推送 API（/loki/api/v1/push）推送，并包含 app、env 和 level 标签。

配置#

环境变量	描述	必填	默认值	示例
`TUIST_LOKI_URL`	兼容 Loki 的推送 API 端点的基础 URL	否		`http://localhost:3100`

未设置此变量时，日志转发功能处于禁用状态。

使用 Grafana Alloy 的示例设置#

Grafana Alloy 可以使用其 loki.source.api 组件充当本地日志中继：

plaintext

loki.source.api "default" {
  http {
    listen_address = "0.0.0.0"
    listen_port    = 3100
  }
  forward_to             = [loki.write.your_backend.receiver]
  use_incoming_timestamp = true
}

loki.write "your_backend" {
  endpoint {
    url = "https://your-loki-instance/loki/api/v1/push"
    basic_auth {
      username = "your-username"
      password = "your-password"
    }
  }
}

然后设置 TUIST_LOKI_URL=http://alloy:3100。

如果 Loki 实例暴露了推送 API，你也可以将 TUIST_LOKI_URL 直接指向该实例。

Prometheus 指标#

你可以使用 Prometheus 和诸如 Grafana 的可视化工具来摄取 Tuist 服务器收集的指标，从而创建符合你需求的自定义仪表板。Prometheus 指标通过端口 9091 上的 /metrics 端点提供。Prometheus 的 scrape_interval 应设置为小于 10_000 秒（我们建议设置为 30 秒，以在可观测性与指标摄取成本之间取得平衡）。

真实用户监控#

Tuist 可以使用捆绑在所提供的 JavaScript 中的 Grafana Faro Web SDK，报告来自营销网站、文档和仪表板的浏览器性能。它会捕获核心网页指标（包括最大内容绘制）、未捕获的错误和页面浏览量，并将这些数据发布到你运行的 Faro 接收器——例如 Grafana Alloy 中的 faro.receiver 组件，该组件会将数据转发到 Loki 和 Tempo。

配置#

环境变量	描述	必填	默认值	示例
`TUIST_FARO_COLLECTOR_URL`	浏览器发布 Faro 负载的 URL	否		`/-/faro`

Note

仅当设置 TUIST_FARO_COLLECTOR_URL 时，真实用户监控才会启用。如果没有它，不会收集任何浏览器遥测数据，也不会加载任何第三方脚本。

使用同源路径（如 /-/faro）可以避免跨域请求，并保持浏览器的内容安全策略不变。通过你的入口网关将其指向你的 Faro 接收器。

收集的内容#

Web Vitals：LCP、CLS、INP、FCP 和 TTFB，由浏览器自动捕获
页面浏览量：在加载和 Phoenix LiveView 导航时记录
视图：每个负载都携带生成它的部分——marketing、docs、dashboard 或 api-docs
错误：未捕获的异常和未处理的 Promise 拒绝

隐私考量#

不附加用户身份：负载中不包含用户 ID、电子邮件或账户信息
会话不会在访问之间持久化，因此不会向浏览器存储写入任何内容
控制台捕获处于关闭状态，因此应用日志输出绝不会从浏览器发送

Elixir 指标#

默认情况下，我们包含 Elixir 运行时、BEAM、Elixir 以及我们使用的一些库的指标。以下是你可以看到的一些指标：

我们建议查看这些页面，了解有哪些可用指标以及如何使用它们。

运行指标#

一组与 Tuist Runs 相关的指标。

`tuist_runs_total`（计数器）#

Tuist Runs 的总数。

标签	描述
`name`	运行的 `tuist` 命令的名称，例如 `build`、`test` 等。
`is_ci`	一个布尔值，指示执行者是 CI 还是开发人员的机器。
`status`	`success` 成功时 `0`，`failure` 失败时 `1`。

标签	描述
`object_key`	对象在远程存储中的查找键。
`part_number`	正在上传的对象的分段编号。
`upload_id`	分段上传的上传 ID。

标签	描述
`cli_version`	遇到错误的 Tuist CLI 版本。
`reason`	令牌刷新错误的原因，例如 `invalid_token_type` 或 `invalid_token`。

标签	描述
`repo`	发出该指标的仓库，例如 `postgres`、`clickhouse_read` 或 `clickhouse_write`。
`database`	底层数据库类型，例如 `postgres` 或 `clickhouse`。