跳转到内容
Tuist

遥测

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

分布式链路追踪（OpenTelemetry）

Section titled “分布式链路追踪（OpenTelemetry）”

Tuist 支持 OpenTelemetry 分布式链路追踪。启用后，服务器会为以下操作生成追踪：HTTP 请求（Phoenix 和 Bandit）、数据库查询（Ecto）、外发 HTTP 调用（Finch）以及 Broadway 消息处理。这些追踪数据可帮助你了解请求延迟、定位慢查询，并追踪请求在服务间的流转。

配置

Section titled “配置”

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

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

未设置此变量时，链路追踪处于禁用状态，不会产生额外开销。

已接入的库

Section titled “已接入的库”

启用链路追踪时，以下库会自动接入：

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

与 Grafana Alloy 配合使用的示例

Section titled “与 Grafana Alloy 配合使用的示例”

如果你使用 Grafana Alloy 作为收集器，可配置它接收 OTLP 追踪并转发到你的追踪后端（如 Grafana Cloud Tempo）：

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）

Section titled “日志转发（Loki）”

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

配置

Section titled “配置”
环境变量描述必填默认值示例
TUIST_LOKI_URLLoki 兼容推送 API 端点的基 URL否http://localhost:3100

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

与 Grafana Alloy 配合使用的示例

Section titled “与 Grafana Alloy 配合使用的示例”

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

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。

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

Prometheus 指标

Section titled “Prometheus 指标”

你可以使用 Prometheus 配合 Grafana 等可视化工具来采集 Tuist 服务器收集的指标，并创建自定义仪表盘。Prometheus 指标通过 /metrics 端点在 9091 端口提供服务。Prometheus 的 scrape_interval 应设置为小于 10_000 秒（建议保持默认的 15 秒）。

PostHog 分析

Section titled “PostHog 分析”

Tuist 集成了 PostHog 用于用户行为分析和事件追踪。这使你能够了解用户如何与 Tuist 服务器交互，追踪功能使用情况，并获取用户在营销网站、仪表盘和 API 文档中的行为洞察。

配置

Section titled “配置”

PostHog 集成为可选功能，可通过设置相应的环境变量来启用。配置后，Tuist 会自动追踪用户事件、页面浏览和用户旅程。

环境变量描述必填默认值示例
TUIST_POSTHOG_API_KEY你的 PostHog 项目 API 密钥否phc_fpR9c0Hs5H5VXUsupU1I0WlEq366FaZH6HJR3lRIWVR
TUIST_POSTHOG_URLPostHog API 端点 URL否https://eu.i.posthog.com

功能

Section titled “功能”

启用 PostHog 后，Tuist 会自动追踪以下内容：

  • 用户识别：通过唯一 ID 和电子邮件地址识别用户
  • 用户别名：使用账户名称为用户设置别名，便于识别
  • 分组分析：按用户选定的项目和组织进行分组，实现分段分析
  • 页面分区：事件包含超级属性，标识生成事件的应用程序分区：
    • marketing - 营销页面和公开内容的事件
    • dashboard - 主应用程序仪表盘和已认证区域的事件
    • api-docs - API 文档页面的事件
  • 页面浏览：使用 Phoenix LiveView 自动追踪页面导航
  • 自定义事件：用于功能使用和用户交互的应用特定事件

隐私注意事项

Section titled “隐私注意事项”
  • 对于已认证用户，PostHog 使用用户的唯一 ID 作为独立标识符，并包含其电子邮件地址
  • 对于匿名用户，PostHog 使用仅内存持久化方式，避免在本地存储数据
  • 所有分析均尊重用户隐私，遵循数据保护最佳实践
  • PostHog 数据按照 PostHog 隐私政策和你的配置进行处理

Elixir 指标

Section titled “Elixir 指标”

默认情况下，我们包含 Elixir 运行时、BEAM、Elixir 及部分使用库的相关指标。以下是一些可以预期的指标：

建议查阅这些页面以了解可用的指标及其使用方法。

Runs 指标

Section titled “Runs 指标”

与 Tuist Runs 相关的一系列指标。

tuist_runs_total（计数器）

Section titled “tuist_runs_total（计数器）”

Tuist Runs 的总数。

标签

Section titled “标签”
标签描述
name所运行的 tuist 命令名称，如 build、test 等。
is_ci布尔值，表示执行者是 CI 还是开发者的机器。
status0 表示成功，1 表示失败。

tuist_runs_duration_milliseconds（直方图）

Section titled “tuist_runs_duration_milliseconds（直方图）”

每次 tuist run 的总持续时间（毫秒）。

标签

Section titled “标签”
标签描述
name所运行的 tuist 命令名称，如 build、test 等。
is_ci布尔值，表示执行者是 CI 还是开发者的机器。
status0 表示成功，1 表示失败。

缓存指标

Section titled “缓存指标”

与 Tuist 缓存相关的一系列指标。

tuist_cache_events_total（计数器）

Section titled “tuist_cache_events_total（计数器）”

二进制缓存事件的总数。

标签

Section titled “标签”
标签描述
event_type可为 local_hit、remote_hit 或 miss。

tuist_cache_uploads_total（计数器）

Section titled “tuist_cache_uploads_total（计数器）”

向二进制缓存的上传次数。

tuist_cache_uploaded_bytes（总和）

Section titled “tuist_cache_uploaded_bytes（总和）”

向二进制缓存上传的字节数。

tuist_cache_downloads_total（计数器）

Section titled “tuist_cache_downloads_total（计数器）”

从二进制缓存的下载次数。

tuist_cache_downloaded_bytes（总和）

Section titled “tuist_cache_downloaded_bytes（总和）”

从二进制缓存下载的字节数。

预览指标

Section titled “预览指标”

与预览功能相关的一系列指标。

tuist_previews_uploads_total（总和）

Section titled “tuist_previews_uploads_total（总和）”

上传的预览总数。

tuist_previews_downloads_total（总和）

Section titled “tuist_previews_downloads_total（总和）”

下载的预览总数。

存储指标

Section titled “存储指标”

与远程存储（如 S3）中制品的存储相关的一系列指标。

tuist_storage_get_object_size_size_bytes（直方图）

Section titled “tuist_storage_get_object_size_size_bytes（直方图）”

从远程存储获取的对象大小（字节）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_get_object_size_duration_miliseconds（直方图）

Section titled “tuist_storage_get_object_size_duration_miliseconds（直方图）”

从远程存储获取对象大小的持续时间（毫秒）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_get_object_size_count（计数器）

Section titled “tuist_storage_get_object_size_count（计数器）”

从远程存储获取对象大小的次数。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_delete_all_objects_duration_milliseconds（直方图）

Section titled “tuist_storage_delete_all_objects_duration_milliseconds（直方图）”

从远程存储删除所有对象的持续时间（毫秒）。

标签

Section titled “标签”
标签描述
project_slug其对象正在被删除的项目的 slug。

tuist_storage_delete_all_objects_count（计数器）

Section titled “tuist_storage_delete_all_objects_count（计数器）”

从远程存储删除所有项目对象的次数。

标签

Section titled “标签”
标签描述
project_slug其对象正在被删除的项目的 slug。

tuist_storage_multipart_start_upload_duration_milliseconds（直方图）

Section titled “tuist_storage_multipart_start_upload_duration_milliseconds（直方图）”

开始上传到远程存储的持续时间（毫秒）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_multipart_start_upload_duration_count（计数器）

Section titled “tuist_storage_multipart_start_upload_duration_count（计数器）”

开始上传到远程存储的次数。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_get_object_as_string_duration_milliseconds（直方图）

Section titled “tuist_storage_get_object_as_string_duration_milliseconds（直方图）”

从远程存储以字符串形式获取对象的持续时间（毫秒）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_get_object_as_string_count（计数）

Section titled “tuist_storage_get_object_as_string_count（计数）”

从远程存储以字符串形式获取对象的次数。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_check_object_existence_duration_milliseconds（直方图）

Section titled “tuist_storage_check_object_existence_duration_milliseconds（直方图）”

检查对象在远程存储中是否存在的时间（毫秒）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_check_object_existence_count（计数）

Section titled “tuist_storage_check_object_existence_count（计数）”

在远程存储中检查对象存在性的次数。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_generate_download_presigned_url_duration_milliseconds（直方图）

Section titled “tuist_storage_generate_download_presigned_url_duration_milliseconds（直方图）”

为远程存储中的对象生成下载预签名 URL 的持续时间（毫秒）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_generate_download_presigned_url_count（计数）

Section titled “tuist_storage_generate_download_presigned_url_count（计数）”

为对象生成下载预签名 URL 的次数。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。

tuist_storage_multipart_generate_upload_part_presigned_url_duration_milliseconds（直方图）

Section titled “tuist_storage_multipart_generate_upload_part_presigned_url_duration_milliseconds（直方图）”

为远程存储中的对象生成部分上传预签名 URL 的持续时间（毫秒）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。
part_number正在上传的对象的部分编号。
upload_id分片上传的上传 ID。

tuist_storage_multipart_generate_upload_part_presigned_url_count（计数）

Section titled “tuist_storage_multipart_generate_upload_part_presigned_url_count（计数）”

为对象生成部分上传预签名 URL 的次数。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。
part_number正在上传的对象的部分编号。
upload_id分片上传的上传 ID。

tuist_storage_multipart_complete_upload_duration_milliseconds（直方图）

Section titled “tuist_storage_multipart_complete_upload_duration_milliseconds（直方图）”

完成上传到远程存储的持续时间（毫秒）。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。
upload_id分片上传的上传 ID。

tuist_storage_multipart_complete_upload_count（计数）

Section titled “tuist_storage_multipart_complete_upload_count（计数）”

完成上传到远程存储的次数。

标签

Section titled “标签”
标签描述
object_key对象在远程存储中的查找键。
upload_id分片上传的上传 ID。

认证指标

Section titled “认证指标”

与认证相关的一系列指标。

tuist_authentication_token_refresh_error_total（计数器）

Section titled “tuist_authentication_token_refresh_error_total（计数器）”

令牌刷新错误总数。

标签

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

项目指标

Section titled “项目指标”

与项目相关的一系列指标。

tuist_projects_total（最新值）

Section titled “tuist_projects_total（最新值）”

项目总数。

账户指标

Section titled “账户指标”

与账户（用户和组织）相关的一系列指标。

tuist_accounts_organizations_total（最新值）

Section titled “tuist_accounts_organizations_total（最新值）”

组织总数。

tuist_accounts_users_total（最新值）

Section titled “tuist_accounts_users_total（最新值）”

用户总数。

数据库指标

Section titled “数据库指标”

与数据库连接相关的一系列指标。

tuist_repo_pool_checkout_queue_length（最新值）

Section titled “tuist_repo_pool_checkout_queue_length（最新值）”

等待分配数据库连接的数据库查询数量。

tuist_repo_pool_ready_conn_count（最新值）

Section titled “tuist_repo_pool_ready_conn_count（最新值）”

准备分配给数据库查询的数据库连接数量。

tuist_repo_pool_db_connection_connected（计数器）

Section titled “tuist_repo_pool_db_connection_connected（计数器）”

已建立的数据库连接数。

tuist_repo_pool_db_connection_disconnected（计数器）

Section titled “tuist_repo_pool_db_connection_disconnected（计数器）”

已断开连接的数据库连接数。

HTTP 指标

Section titled “HTTP 指标”

与 Tuist 通过 HTTP 与其他服务交互相关的一系列指标。

tuist_http_request_count（计数器）

Section titled “tuist_http_request_count（计数器）”

外发 HTTP 请求数。

tuist_http_request_duration_nanosecond_sum（总和）

Section titled “tuist_http_request_duration_nanosecond_sum（总和）”

外发请求持续时间的总和（包括等待分配连接所花费的时间）。

tuist_http_request_duration_nanosecond_bucket（分布）

Section titled “tuist_http_request_duration_nanosecond_bucket（分布）”

外发请求持续时间的分布（包括等待分配连接所花费的时间）。

tuist_http_queue_count（计数器）

Section titled “tuist_http_queue_count（计数器）”

从连接池中取出的请求数。

tuist_http_queue_duration_nanoseconds_sum（总和）

Section titled “tuist_http_queue_duration_nanoseconds_sum（总和）”

从连接池获取连接所需的时间。

tuist_http_queue_idle_time_nanoseconds_sum（总和）

Section titled “tuist_http_queue_idle_time_nanoseconds_sum（总和）”

连接在等待被取走时空闲的时间。

tuist_http_queue_duration_nanoseconds_bucket（分布）

Section titled “tuist_http_queue_duration_nanoseconds_bucket（分布）”

从连接池获取连接所需的时间。

tuist_http_queue_idle_time_nanoseconds_bucket（分布）

Section titled “tuist_http_queue_idle_time_nanoseconds_bucket（分布）”

连接在等待被取走时空闲的时间。

tuist_http_connection_count（计数器）

Section titled “tuist_http_connection_count（计数器）”

已建立的连接数。

tuist_http_connection_duration_nanoseconds_sum（总和）

Section titled “tuist_http_connection_duration_nanoseconds_sum（总和）”

建立与主机的连接所需的时间。

tuist_http_connection_duration_nanoseconds_bucket（分布）

Section titled “tuist_http_connection_duration_nanoseconds_bucket（分布）”

建立与主机的连接所需时间的分布。

tuist_http_send_count（计数器）

Section titled “tuist_http_send_count（计数器）”

一旦分配到连接池中的连接后，已发送的请求数。

tuist_http_send_duration_nanoseconds_sum（总和）

Section titled “tuist_http_send_duration_nanoseconds_sum（总和）”

请求在分配到连接池中的连接后完成所需的时间。

tuist_http_send_duration_nanoseconds_bucket（分布）

Section titled “tuist_http_send_duration_nanoseconds_bucket（分布）”

请求在分配到连接池中的连接后完成所需时间的分布。

tuist_http_receive_count（计数器）

Section titled “tuist_http_receive_count（计数器）”

已接收的请求响应数。

tuist_http_receive_duration_nanoseconds_sum（总和）

Section titled “tuist_http_receive_duration_nanoseconds_sum（总和）”

接收响应所花费的时间。

tuist_http_receive_duration_nanoseconds_bucket（分布）

Section titled “tuist_http_receive_duration_nanoseconds_bucket（分布）”

接收响应所花费时间的分布。

tuist_http_queue_available_connections（最新值）

Section titled “tuist_http_queue_available_connections（最新值）”

队列中可用连接数。

tuist_http_queue_in_use_connections（最新值）

Section titled “tuist_http_queue_in_use_connections（最新值）”

正在使用的队列连接数。