遙測

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 直接指向該執行個體。

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 接收器。

收集的資料#

網頁指標：LCP、CLS、INP、FCP 與 TTFB，由瀏覽器自動擷取
頁面瀏覽：在載入與 Phoenix LiveView 導航時記錄
視圖：每個負載都帶有產生該負載的區段 — marketing、docs、dashboard 或 api-docs
錯誤：未捕捉的例外狀況與未處理的 Promise 拒絕

隱私考量#

不附加使用者身分：負載中不包含使用者 ID、電子郵件或帳號
工作階段不會在不同造訪間持久化，因此不會寫入任何資料到瀏覽器儲存空間
主控台擷取已關閉，因此應用程式日誌輸出絕不會從瀏覽器送出

Elixir 指標#

預設情況下，我們會納入 Elixir 執行階段、BEAM、Elixir 以及部分所用程式庫的指標。以下是你可見的部分指標：

我們建議查閱這些頁面，以了解可用指標及其使用方法。

執行次數指標#

一組與 Tuist 執行次數相關的指標。

`tuist_runs_total`（計數器）#

Tuist 執行次數的總數。

標籤	說明
`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`。