Descripción general de las tablas del sistema

Las tablas del sistema proporcionan información sobre:

Estados, procesos y entorno del servidor.
Los procesos internos del servidor.
Las opciones utilizadas al compilar el binario de ClickHouse.

Las tablas del sistema:

Están ubicadas en la base de datos system.
Solo están disponibles para lectura.
No se pueden eliminar ni modificar, pero sí se pueden desvincular.

La mayoría de las tablas del sistema almacenan sus datos en RAM. Un servidor ClickHouse crea estas tablas del sistema al iniciarse. A diferencia de otras tablas del sistema, las tablas de registro del sistema metric_log, query_log, query_thread_log, trace_log, part_log, crash_log, text_log y backup_log usan el motor de tabla MergeTree y almacenan sus datos en un sistema de archivos de forma predeterminada. Si elimina una tabla del sistema de archivos, el servidor ClickHouse volverá a crear una vacía la próxima vez que se escriban datos. Si el esquema de una tabla del sistema cambia en una nueva versión, ClickHouse cambia el nombre de la tabla actual y crea una nueva. Las tablas de registro del sistema se pueden personalizar creando un archivo de configuración con el mismo nombre que la tabla en /etc/clickhouse-server/config.d/, o configurando los elementos correspondientes en /etc/clickhouse-server/config.xml. Los elementos que se pueden personalizar son:

database: base de datos a la que pertenece la tabla de registro del sistema. Esta opción ahora está obsoleta. Todas las tablas de registro del sistema están en la base de datos system.
table: tabla en la que insertar datos.
partition_by: especifica la expresión PARTITION BY.
ttl: especifica la expresión TTL de la tabla.
flush_interval_milliseconds: intervalo de volcado de datos a disco.
engine: proporciona la expresión completa del motor (empezando por ENGINE = ) con parámetros. Esta opción entra en conflicto con partition_by y ttl. Si se configuran juntas, el servidor generará una excepción y finalizará.

Un ejemplo:

<clickhouse>
    <query_log>
        <database>system</database>
        <table>query_log</table>
        <partition_by>toYYYYMM(event_date)</partition_by>
        <ttl>event_date + INTERVAL 30 DAY DELETE</ttl>
        <!--
        <engine>ENGINE = MergeTree PARTITION BY toYYYYMM(event_date) ORDER BY (event_date, event_time) SETTINGS index_granularity = 1024</engine>
        -->
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </query_log>
</clickhouse>

De forma predeterminada, el crecimiento de la tabla es ilimitado. Para controlar el tamaño de una tabla, puede usar la configuración de TTL para eliminar registros de log antiguos. También puede usar la función de particionado de las tablas con motor MergeTree.

Fuentes de métricas del sistema

Para recopilar métricas del sistema, el servidor de ClickHouse utiliza:

la capability CAP_NET_ADMIN.
procfs (solo en Linux).

procfs Si el servidor de ClickHouse no tiene la capability CAP_NET_ADMIN, intenta usar ProcfsMetricsProvider como alternativa. ProcfsMetricsProvider permite recopilar métricas del sistema por consulta (de CPU y E/S). Si procfs es compatible y está habilitado en el sistema, el servidor de ClickHouse recopila estas métricas:

OSCPUVirtualTimeMicroseconds
OSCPUWaitMicroseconds
OSIOWaitMicroseconds
OSReadChars
OSWriteChars
OSReadBytes
OSWriteBytes

OSIOWaitMicroseconds está deshabilitada de forma predeterminada en los kernels de Linux a partir de la versión 5.14.x. Puede habilitarla con sudo sysctl kernel.task_delayacct=1 o creando un archivo .conf en /etc/sysctl.d/ con kernel.task_delayacct = 1

Tablas del sistema en ClickHouse Cloud

En ClickHouse Cloud, las tablas del sistema proporcionan información esencial sobre el estado y el rendimiento del servicio, igual que en las implementaciones autogestionadas. Algunas tablas del sistema operan a nivel de todo el clúster, especialmente las que obtienen sus datos de los nodos Keeper, que gestionan los metadatos distribuidos. Estas tablas reflejan el estado global del clúster y deberían ser coherentes al consultarlas desde nodos individuales. Por ejemplo, parts debería ser coherente independientemente del nodo desde el que se consulte:

SELECT hostname(), count()
FROM system.parts
WHERE `table` = 'pypi'

┌─hostname()────────────────────┬─count()─┐
│ c-ecru-qn-34-server-vccsrty-0 │      26 │
└───────────────────────────────┴─────────┘

1 row in set. Elapsed: 0.005 sec.

SELECT
 hostname(),
    count()
FROM system.parts
WHERE `table` = 'pypi'

┌─hostname()────────────────────┬─count()─┐
│ c-ecru-qn-34-server-w59bfco-0 │      26 │
└───────────────────────────────┴─────────┘

1 row in set. Elapsed: 0.004 sec.

Por el contrario, otras tablas del sistema son específicas de cada nodo; por ejemplo, se almacenan en memoria o conservan sus datos mediante el table engine MergeTree. Esto es habitual en datos como logs y métricas. Esta persistencia garantiza que los datos históricos sigan estando disponibles para su análisis. Sin embargo, estas tablas específicas de cada nodo son, por naturaleza, únicas en cada nodo. En general, pueden aplicarse las siguientes reglas para determinar si una tabla del sistema es específica de un nodo:

Tablas del sistema con el sufijo _log.
Tablas del sistema que exponen métricas; por ejemplo, metrics, asynchronous_metrics, events.
Tablas del sistema que exponen procesos en curso; por ejemplo, processes, merges.

Además, pueden crearse nuevas versiones de las tablas del sistema como resultado de actualizaciones o cambios en su esquema. Estas versiones se nombran con un sufijo numérico. Por ejemplo, considere las tablas system.query_log, que contienen una fila por cada consulta ejecutada por el nodo:

SHOW TABLES FROM system LIKE 'query_log%'

┌─name─────────┐
│ query_log    │
│ query_log_1  │
│ query_log_10 │
│ query_log_2  │
│ query_log_3  │
│ query_log_4  │
│ query_log_5  │
│ query_log_6  │
│ query_log_7  │
│ query_log_8  │
│ query_log_9  │
└──────────────┘

11 rows in set. Elapsed: 0.004 sec.

Consultar varias versiones

Podemos consultar estas tablas mediante la función merge. Por ejemplo, la siguiente consulta identifica la consulta más reciente enviada al nodo de destino en cada tabla query_log:

SELECT
    _table,
    max(event_time) AS most_recent
FROM merge('system', '^query_log')
GROUP BY _table
ORDER BY most_recent DESC

┌─_table───────┬─────────most_recent─┐
│ query_log    │ 2025-04-13 10:59:29 │
│ query_log_1  │ 2025-04-09 12:34:46 │
│ query_log_2  │ 2025-04-09 12:33:45 │
│ query_log_3  │ 2025-04-07 17:10:34 │
│ query_log_5  │ 2025-03-24 09:39:39 │
│ query_log_4  │ 2025-03-24 09:38:58 │
│ query_log_6  │ 2025-03-19 16:07:41 │
│ query_log_7  │ 2025-03-18 17:01:07 │
│ query_log_8  │ 2025-03-18 14:36:07 │
│ query_log_10 │ 2025-03-18 14:01:33 │
│ query_log_9  │ 2025-03-18 14:01:32 │
└──────────────┴─────────────────────┘

11 rows in set. Elapsed: 0.373 sec. Processed 6.44 million rows, 25.77 MB (17.29 million rows/s., 69.17 MB/s.)
Peak memory usage: 28.45 MiB.

No confíes en el sufijo numérico para el ordenAunque el sufijo numérico de las tablas puede sugerir el orden de los datos, nunca debes basarte en él. Por este motivo, usa siempre la función de tabla merge combinada con un filtro de fecha cuando consultes rangos de fechas específicos.

Es importante destacar que estas tablas siguen siendo locales a cada nodo.

Consultas en todos los nodos

Para obtener una vista completa de todo el clúster, los usuarios pueden aprovechar la función clusterAllReplicas en combinación con la función merge. La función clusterAllReplicas permite consultar tablas del sistema en todas las réplicas del clúster “default”, consolidando los datos específicos de cada nodo en un único resultado. En combinación con la función merge, puede usarse para consultar todos los datos del sistema de una tabla específica en un clúster. Este enfoque es especialmente valioso para la monitorización y la depuración de operaciones en todo el clúster, ya que permite a los usuarios analizar eficazmente el estado y el rendimiento de su implementación de ClickHouse Cloud.

ClickHouse Cloud proporciona clústeres con múltiples réplicas para redundancia y failover. Esto habilita funciones como el autoscaling dinámico y las actualizaciones sin tiempo de inactividad. En un momento dado, puede haber nodos nuevos en proceso de añadirse al clúster o de eliminarse de él. Para omitir estos nodos, añada SETTINGS skip_unavailable_shards = 1 a las consultas que usan clusterAllReplicas, como se muestra a continuación.

Por ejemplo, observe la diferencia al consultar la tabla query_log, algo que suele ser esencial para el análisis.

SELECT
    hostname() AS host,
    count()
FROM system.query_log
WHERE (event_time >= '2025-04-01 00:00:00') AND (event_time <= '2025-04-12 00:00:00')
GROUP BY host

┌─host──────────────────────────┬─count()─┐
│ c-ecru-qn-34-server-s5bnysl-0 │  650543 │
└───────────────────────────────┴─────────┘

1 row in set. Elapsed: 0.010 sec. Processed 17.87 thousand rows, 71.51 KB (1.75 million rows/s., 7.01 MB/s.)

SELECT
    hostname() AS host,
    count()
FROM clusterAllReplicas('default', system.query_log)
WHERE (event_time >= '2025-04-01 00:00:00') AND (event_time <= '2025-04-12 00:00:00')
GROUP BY host SETTINGS skip_unavailable_shards = 1

┌─host──────────────────────────┬─count()─┐
│ c-ecru-qn-34-server-s5bnysl-0 │  650543 │
│ c-ecru-qn-34-server-6em4y4t-0 │  656029 │
│ c-ecru-qn-34-server-iejrkg0-0 │  641155 │
└───────────────────────────────┴─────────┘

3 rows in set. Elapsed: 0.026 sec. Processed 1.97 million rows, 7.88 MB (75.51 million rows/s., 302.05 MB/s.)

Consultas entre nodos y versiones

Debido al versionado de las tablas del sistema, esto todavía no representa todos los datos del clúster. Al combinar lo anterior con la función merge, obtenemos un resultado preciso para nuestro intervalo de fechas:

SELECT
    hostname() AS host,
    count()
FROM clusterAllReplicas('default', merge('system', '^query_log'))
WHERE (event_time >= '2025-04-01 00:00:00') AND (event_time <= '2025-04-12 00:00:00')
GROUP BY host SETTINGS skip_unavailable_shards = 1

┌─host──────────────────────────┬─count()─┐
│ c-ecru-qn-34-server-s5bnysl-0 │ 3008000 │
│ c-ecru-qn-34-server-6em4y4t-0 │ 3659443 │
│ c-ecru-qn-34-server-iejrkg0-0 │ 1078287 │
└───────────────────────────────┴─────────┘

3 rows in set. Elapsed: 0.462 sec. Processed 7.94 million rows, 31.75 MB (17.17 million rows/s., 68.67 MB/s.)