Telemetría
Tuist ofrece tres señales de observabilidad complementarias: métricas (Prometheus), trazas (OpenTelemetry) y registros (compatibles con Loki). Las tres son opcionales y pueden habilitarse de forma independiente.
Trazado distribuido (OpenTelemetry)#
Tuist admite OpenTelemetry para el trazado distribuido. Cuando está habilitado, el servidor emite trazas para solicitudes HTTP (Phoenix y Bandit), consultas a la base de datos (Ecto), llamadas HTTP salientes (Finch) y procesamiento de mensajes de Broadway. Estas trazas te permiten comprender la latencia de las solicitudes, identificar consultas lentas y seguir las solicitudes entre servicios.
Configuración#
Establece la siguiente variable de entorno para habilitar la exportación de trazas:
| Variable de entorno | Descripción | Requerida | Predeterminado | Ejemplo |
|---|---|---|---|---|
TUIST_OTEL_EXPORTER_OTLP_ENDPOINT |
El extremo gRPC de un recopilador de OpenTelemetry (por ejemplo, Grafana Alloy, Jaeger o cualquier recopilador compatible con OTLP) | No | http://localhost:4317 |
Cuando esta variable no está establecida, el trazado está deshabilitado y no añade sobrecarga.
Bibliotecas instrumentadas#
Las siguientes bibliotecas se instrumentan automáticamente cuando el trazado está habilitado:
- Bandit: intervalos de conexión del servidor HTTP
- Phoenix: intervalos del ciclo de vida de las solicitudes (acciones del controlador, LiveView)
- Ecto: intervalos de consultas a la base de datos con metadatos de consulta
- Finch: intervalos de solicitudes HTTP salientes del cliente
- Broadway: intervalos de la canalización de procesamiento de mensajes
Ejemplo de configuración con Grafana Alloy#
Si usas Grafana Alloy como tu recopilador, configúralo para recibir trazas OTLP y reenviarlas a tu backend de trazado (por ejemplo, Grafana Cloud Tempo):
otelcol.receiver.otlp "default" {
grpc {
endpoint = "0.0.0.0:4317"
}
output {
traces = [otelcol.exporter.otlp.your_backend.input]
}
}
Luego establece TUIST_OTEL_EXPORTER_OTLP_ENDPOINT para que apunte a la instancia de Alloy, por ejemplo http://alloy:4317.
Reenvío de registros (Loki)#
Tuist puede reenviar los registros de la aplicación a un extremo compatible con Loki. Esto te permite centralizar los registros junto con tus métricas y trazas para tener una visión completa de la observabilidad. Los registros se envían mediante la API HTTP push de Loki (/loki/api/v1/push) e incluyen etiquetas para app, env y level.
Configuración#
| Variable de entorno | Descripción | Requerida | Predeterminado | Ejemplo |
|---|---|---|---|---|
TUIST_LOKI_URL |
La URL base de un extremo de API push compatible con Loki | No | http://localhost:3100 |
Cuando esta variable no está establecida, el reenvío de registros está deshabilitado.
Ejemplo de configuración con Grafana Alloy#
Grafana Alloy puede actuar como un relé local de registros usando su componente 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"
}
}
}
Luego establece TUIST_LOKI_URL=http://alloy:3100.
También puedes apuntar TUIST_LOKI_URL directamente a una instancia de Loki si expone la API push.
Métricas de Prometheus#
Puedes ingerir las métricas recopiladas por el servidor de Tuist usando Prometheus y una herramienta de visualización como Grafana para crear un panel personalizado adaptado a tus necesidades. Las métricas de Prometheus se sirven a través del extremo /metrics en el puerto 9091. El scrape_interval de Prometheus debe configurarse en menos de 10_000 segundos (recomendamos 30 segundos para equilibrar la observabilidad con los costos de ingesta de métricas).
Monitoreo de usuarios reales#
Tuist puede informar sobre el rendimiento del navegador desde el sitio de marketing, la documentación y el panel usando el SDK web de Grafana Faro, que está incluido en el JavaScript servido. Captura las Core Web Vitals (incluido Largest Contentful Paint), errores no capturados y vistas de página, y los publica en un receptor de Faro que ejecutes, por ejemplo, el componente faro.receiver en Grafana Alloy, que reenvía a Loki y Tempo.
Configuración#
| Variable de entorno | Descripción | Requerida | Predeterminado | Ejemplo |
|---|---|---|---|---|
TUIST_FARO_COLLECTOR_URL |
URL a la que el navegador envía las cargas útiles de Faro | No | /-/faro |
El monitoreo de usuarios reales solo está habilitado cuando TUIST_FARO_COLLECTOR_URL está establecida. Sin ella, no se recopila telemetría del navegador ni se carga ningún script de terceros.
Una ruta del mismo origen como /-/faro evita solicitudes entre orígenes y mantiene sin cambios la Política de Seguridad de Contenido del navegador. Apúntala a tu receptor de Faro a través de tu ingress.
Qué se recopila#
- Métricas web: LCP, CLS, INP, FCP y TTFB, capturadas automáticamente por el navegador
- Vistas de página: registradas al cargar y durante la navegación de Phoenix LiveView
- Vistas: cada carga útil lleva la sección que la produjo:
marketing,docs,dashboardoapi-docs - Errores: excepciones no capturadas y rechazos de promesas no manejados
Consideraciones de privacidad#
- No se adjunta identidad de usuario: las cargas útiles no contienen ID de usuario, correo electrónico ni cuenta
- Las sesiones no se persisten entre visitas, por lo que no se escribe nada en el almacenamiento del navegador
- La captura de la consola está desactivada, por lo que la salida del registro de la aplicación nunca se envía desde el navegador
Métricas de Elixir#
Por defecto incluimos métricas del runtime de Elixir, BEAM, Elixir y algunas de las bibliotecas que usamos. Las siguientes son algunas de las métricas que puedes esperar ver:
Recomendamos revisar esas páginas para saber qué métricas están disponibles y cómo usarlas.
Métricas de ejecuciones#
Un conjunto de métricas relacionadas con las ejecuciones de Tuist.
tuist_runs_total (contador)#
El número total de ejecuciones de Tuist.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
name |
El nombre del comando tuist que se ejecutó, como build, test, etc. |
is_ci |
Un booleano que indica si el ejecutor era un entorno de CI o la máquina de un desarrollador. |
status |
0 en caso de success, 1 en caso de failure. |
tuist_runs_duration_milliseconds (histograma)#
La duración total de cada ejecución de tuist en milisegundos.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
name |
El nombre del comando tuist que se ejecutó, como build, test, etc. |
is_ci |
Un booleano que indica si el ejecutor era un entorno de CI o la máquina de un desarrollador. |
status |
0 en caso de success, 1 en caso de failure. |
Métricas de caché#
Un conjunto de métricas relacionadas con la caché de Tuist.
tuist_cache_events_total (contador)#
El número total de eventos de la caché binaria.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
event_type |
Puede ser local_hit, remote_hit o miss. |
tuist_cache_uploads_total (contador)#
El número de subidas a la caché binaria.
tuist_cache_uploaded_bytes (suma)#
El número de bytes subidos a la caché binaria.
tuist_cache_downloads_total (contador)#
El número de descargas de la caché binaria.
tuist_cache_downloaded_bytes (suma)#
El número de bytes descargados de la caché binaria.
Métricas de previsualizaciones#
Un conjunto de métricas relacionadas con la función de previsualizaciones.
tuist_previews_uploads_total (suma)#
El número total de previsualizaciones subidas.
tuist_previews_downloads_total (suma)#
El número total de previsualizaciones descargadas.
Métricas de almacenamiento#
Un conjunto de métricas relacionadas con el almacenamiento de artefactos en un almacenamiento remoto (por ejemplo, S3).
Estas métricas son útiles para comprender el rendimiento de las operaciones de almacenamiento e identificar posibles cuellos de botella.
tuist_storage_get_object_size_size_bytes (histograma)#
El tamaño (en bytes) de un objeto obtenido del almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_get_object_size_duration_miliseconds (histograma)#
La duración (en milisegundos) de obtener el tamaño de un objeto desde el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_get_object_size_count (contador)#
El número de veces que se obtuvo el tamaño de un objeto desde el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_delete_all_objects_duration_milliseconds (histograma)#
La duración (en milisegundos) de eliminar todos los objetos del almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
project_slug |
El slug del proyecto cuyos objetos se están eliminando. |
tuist_storage_delete_all_objects_count (contador)#
El número de veces que se eliminaron todos los objetos del proyecto del almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
project_slug |
El slug del proyecto cuyos objetos se están eliminando. |
tuist_storage_multipart_start_upload_duration_milliseconds (histograma)#
La duración (en milisegundos) de iniciar una subida al almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_multipart_start_upload_duration_count (contador)#
El número de veces que se inició una subida al almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_get_object_as_string_duration_milliseconds (histograma)#
La duración (en milisegundos) de obtener un objeto como cadena desde el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_get_object_as_string_count (contador)#
El número de veces que se obtuvo un objeto como cadena desde el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_check_object_existence_duration_milliseconds (histograma)#
La duración (en milisegundos) de comprobar la existencia de un objeto en el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_check_object_existence_count (contador)#
El número de veces que se comprobó la existencia de un objeto en el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_generate_download_presigned_url_duration_milliseconds (histograma)#
La duración (en milisegundos) de generar una URL prefirmada de descarga para un objeto en el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_generate_download_presigned_url_count (contador)#
El número de veces que se generó una URL prefirmada de descarga para un objeto en el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
tuist_storage_multipart_generate_upload_part_presigned_url_duration_milliseconds (histograma)#
La duración (en milisegundos) de generar una URL prefirmada de subida de parte para un objeto en el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
part_number |
El número de parte del objeto que se está subiendo. |
upload_id |
El ID de subida de la subida multiparte. |
tuist_storage_multipart_generate_upload_part_presigned_url_count (contador)#
El número de veces que se generó una URL prefirmada de subida de parte para un objeto en el almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
part_number |
El número de parte del objeto que se está subiendo. |
upload_id |
El ID de subida de la subida multiparte. |
tuist_storage_multipart_complete_upload_duration_milliseconds (histograma)#
La duración (en milisegundos) de completar una subida al almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
upload_id |
El ID de subida de la subida multiparte. |
tuist_storage_multipart_complete_upload_count (contador)#
El número total de veces que se completó una subida al almacenamiento remoto.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
object_key |
La clave de búsqueda del objeto en el almacenamiento remoto. |
upload_id |
El ID de subida de la subida multiparte. |
Métricas de autenticación#
Un conjunto de métricas relacionadas con la autenticación.
tuist_authentication_token_refresh_error_total (contador)#
El número total de errores de actualización de token.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
cli_version |
La versión de la CLI de Tuist que encontró el error. |
reason |
La razón del error de actualización del token, como invalid_token_type o invalid_token. |
Métricas de proyectos#
Un conjunto de métricas relacionadas con los proyectos.
tuist_projects_total (último_valor)#
El número total de proyectos.
Métricas de cuentas#
Un conjunto de métricas relacionadas con las cuentas (usuarios y organizaciones).
tuist_accounts_organizations_total (último_valor)#
El número total de organizaciones.
tuist_accounts_users_total (último_valor)#
El número total de usuarios.
Métricas de base de datos#
Un conjunto de métricas relacionadas con la conexión a la base de datos.
Las métricas del pool de repositorios se muestrean internamente cada 100 ms y luego se exponen a Prometheus en /metrics. Las métricas last_value que aparecen a continuación muestran el estado más reciente del pool en el momento de la recolección. Las métricas de presión que aparecen más abajo son sumas derivadas de esas muestras de 100 ms, lo que facilita detectar ventanas cortas de saturación incluso cuando se recuperan antes de la siguiente recolección.
tuist_repo_pool_checkout_queue_length (último_valor)#
El número de consultas a la base de datos que están en cola esperando ser asignadas a una conexión de base de datos.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
repo |
El repositorio que emitió la métrica, como postgres, clickhouse_read o clickhouse_write. |
database |
El tipo de base de datos subyacente, como postgres o clickhouse. |
tuist_repo_pool_ready_conn_count (último_valor)#
El número de conexiones a la base de datos que están listas para ser asignadas a una consulta de base de datos.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
repo |
El repositorio que emitió la métrica, como postgres, clickhouse_read o clickhouse_write. |
database |
El tipo de base de datos subyacente, como postgres o clickhouse. |
tuist_repo_pool_size (último_valor)#
El número configurado de conexiones en el pool.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
repo |
El repositorio que emitió la métrica, como postgres, clickhouse_read o clickhouse_write. |
database |
El tipo de base de datos subyacente, como postgres o clickhouse. |
tuist_repo_pool_checkout_queue_total_samples_sum (suma)#
El número total de sondeos del pool de repositorios realizados (se incrementa en 1 en cada sondeo). Úsalo como denominador al calcular porcentajes de ocupación o inanición: rate(busy_samples) / rate(total_samples) o rate(starved_samples) / rate(total_samples).
Etiquetas#
| Etiqueta | Descripción |
|---|---|
repo |
El repositorio que emitió la métrica, como postgres, clickhouse_read o clickhouse_write. |
database |
El tipo de base de datos subyacente, como postgres o clickhouse. |
tuist_repo_pool_checkout_queue_observed_sum (suma)#
La suma de las solicitudes de checkout en cola observadas durante los sondeos del pool de repositorios. Esto es útil para detectar ráfagas cortas de contención del pool que pueden no ser visibles solo con la última muestra de longitud de cola.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
repo |
El repositorio que emitió la métrica, como postgres, clickhouse_read o clickhouse_write. |
database |
El tipo de base de datos subyacente, como postgres o clickhouse. |
tuist_repo_pool_checkout_queue_busy_samples_sum (suma)#
El número de sondeos del pool de repositorios en los que al menos una solicitud de checkout a la base de datos estaba esperando en la cola.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
repo |
El repositorio que emitió la métrica, como postgres, clickhouse_read o clickhouse_write. |
database |
El tipo de base de datos subyacente, como postgres o clickhouse. |
tuist_repo_pool_checkout_queue_starved_samples_sum (suma)#
El número de sondeos del pool de repositorios en los que las solicitudes de checkout estaban en cola y no había conexiones listas disponibles. Un aumento sostenido aquí suele significar que el pool está saturado.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
repo |
El repositorio que emitió la métrica, como postgres, clickhouse_read o clickhouse_write. |
database |
El tipo de base de datos subyacente, como postgres o clickhouse. |
tuist_repo_pool_db_connection_connected (contador)#
El número de conexiones que se han establecido con la base de datos.
tuist_repo_pool_db_connection_disconnected (contador)#
El número de conexiones que se han desconectado de la base de datos.
Etiquetas#
| Etiqueta | Descripción |
|---|---|
tag |
La etiqueta del listener de DBConnection que identifica el repositorio emisor. |
Métricas HTTP#
Un conjunto de métricas relacionadas con las interacciones de Tuist con otros servicios a través de HTTP.
tuist_http_request_count (contador)#
El número de solicitudes HTTP salientes.
tuist_http_request_duration_nanoseconds_sum (suma)#
La suma de la duración de las solicitudes salientes (incluido el tiempo que pasaron esperando ser asignadas a una conexión).
tuist_http_request_duration_nanoseconds_bucket (distribución)#
La distribución de la duración de las solicitudes salientes (incluido el tiempo que pasaron esperando ser asignadas a una conexión).
tuist_http_queue_count (contador)#
El número de solicitudes que se han recuperado del pool.
tuist_http_queue_duration_nanoseconds_sum (suma)#
El tiempo que tarda en recuperarse una conexión del pool.
tuist_http_queue_idle_time_nanoseconds_sum (suma)#
El tiempo que una conexión ha estado inactiva esperando ser recuperada.
tuist_http_queue_duration_nanoseconds_bucket (distribución)#
El tiempo que tarda en recuperarse una conexión del pool.
tuist_http_queue_idle_time_nanoseconds_bucket (distribución)#
El tiempo que una conexión ha estado inactiva esperando ser recuperada.
tuist_http_connection_count (contador)#
El número de conexiones que se han establecido.
tuist_http_connection_duration_nanoseconds_sum (suma)#
El tiempo que tarda en establecerse una conexión con un host.
tuist_http_connection_duration_nanoseconds_bucket (distribución)#
La distribución del tiempo que tarda en establecerse una conexión con un host.
tuist_http_send_count (contador)#
El número de solicitudes que se han enviado una vez asignadas a una conexión del pool.
tuist_http_send_duration_nanoseconds_sum (suma)#
El tiempo que tardan las solicitudes en completarse una vez asignadas a una conexión del pool.
tuist_http_send_duration_nanoseconds_bucket (distribución)#
La distribución del tiempo que tardan las solicitudes en completarse una vez asignadas a una conexión del pool.
tuist_http_receive_count (contador)#
El número de respuestas que se han recibido de las solicitudes enviadas.
tuist_http_receive_duration_nanoseconds_sum (suma)#
El tiempo dedicado a recibir respuestas.
tuist_http_receive_duration_nanoseconds_bucket (distribución)#
La distribución del tiempo dedicado a recibir respuestas.
tuist_http_queue_available_connections (último valor)#
El número de conexiones disponibles en la cola.
tuist_http_queue_in_use_connections (último valor)#
El número de conexiones de la cola que están en uso.