遙測

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 push API（/loki/api/v1/push）推送，並包含 app、env 和 level 標籤。

環境變數	描述	必需	預設值	範例
`TUIST_LOKI_URL`	兼容 Loki 嘅 push 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 實例暴露咗 push API，你亦可以直接將 TUIST_LOKI_URL 指向該 Loki 實例。

Prometheus 指標#

你可以使用 Prometheus 同埋類似 Grafana 嘅可視化工具，匯入 Tuist 伺服器收集到嘅指標，從而建立符合你需求嘅自訂儀表板。Prometheus 指標透過端口 9091 上嘅 /metrics 端點提供。Prometheus 嘅 scrape_interval 應設定為少於 10_000 秒（我哋建議設定為 30 秒，以平衡可觀察性同指標匯入成本）。

Tuist 可以使用內置於所提供 JavaScript 中嘅 Grafana Faro Web SDK，從營銷網站、文檔同儀表板報告瀏覽器性能。佢會捕捉核心網頁指標（包括 Largest Contentful Paint）、未捕獲嘅錯誤同頁面瀏覽量，並將佢哋發布到你運行嘅 Faro receiver — 例如 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，由瀏覽器自動捕捉
Page views：在加載同 Phoenix LiveView 導航時記錄
Views：每個負載都帶有產生佢嘅部分 — marketing、docs、dashboard 或 api-docs
Errors：未捕獲嘅異常同未處理嘅 Promise 拒絕

私隱考慮#

冇附加用戶身份：負載中唔包含用戶 ID、電子郵件或賬戶
會話唔會在訪問之間持久化，所以冇任何數據寫入瀏覽器存儲
控制台捕捉已關閉，所以應用程式日誌輸出永遠唔會從瀏覽器發送出去

Elixir 指標#

默認情況下，我哋包括 Elixir 運行時、BEAM、Elixir 同我哋使用嘅一些函式庫嘅指標。以下係你可以預期見到嘅一些指標：

我哋建議查看嗰啲頁面，以了解可用嘅指標同如何使用佢哋。

Runs 指標#

一組與 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`。