> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentación de la herramienta de perfilado de consultas por muestreo en ClickHouse

# Perfilador de consultas por muestreo

ClickHouse ejecuta un perfilador por muestreo que permite analizar la ejecución de consultas.
Con el perfilador, puede identificar las rutinas del código fuente que se usan con más frecuencia durante la ejecución de consultas.
Puede rastrear el tiempo de CPU y el tiempo de reloj consumidos, incluido el tiempo inactivo.

El perfilador de consultas se habilita automáticamente en ClickHouse Cloud.
La siguiente consulta de ejemplo encuentra las trazas de pila más frecuentes de una consulta perfilada, con los nombres de función resueltos y las ubicaciones en el código fuente.

De forma predeterminada, el perfilador simboliza las trazas de pila durante la recopilación y almacena los resultados en las columnas `symbols` y `lines` de [`system.trace_log`](/es/reference/system-tables/trace_log), por lo que los siguientes ejemplos leen directamente esas columnas y no requieren funciones de introspección. La simbolización se controla mediante la configuración `symbolize` en la sección de configuración del servidor `trace_log` (habilitada de forma predeterminada) y es compatible con plataformas ELF (como Linux) y macOS; en FreeBSD, las columnas `symbols` y `lines` siempre están vacías. Los nombres de función de `symbols` proceden de la tabla de símbolos del binario y están disponibles de forma predeterminada. Las ubicaciones del código fuente en `lines` se resuelven según las posibilidades: requieren información de depuración (en macOS, un paquete `.dSYM` junto al binario) y, en plataformas ELF, solo se resuelven los marcos dentro del binario principal de ClickHouse, por lo que las entradas de marcos que no pueden resolverse (por ejemplo, en bibliotecas compartidas) se dejan vacías. Si la simbolización está deshabilitada, use las funciones de introspección `addressToSymbol`, `demangle` y `addressToLine` para resolver en su lugar las direcciones sin procesar de la columna `trace`. Estas funciones están disponibles en las mismas plataformas que la simbolización (plataformas ELF como Linux y macOS); en FreeBSD tampoco se compilan, por lo que las direcciones de `trace` deben resolverse fuera del servidor. Consulte también la documentación de las [funciones de introspección](/es/reference/functions/regular-functions/introspection).

<Tip>
  Reemplace el valor de `query_id` por el ID de la consulta que quiere perfilar.
</Tip>

<Tabs>
  <Tab title="ClickHouse Cloud">
    En ClickHouse Cloud, puede obtener el ID de la consulta haciendo clic en **"..."** en el extremo derecho de la barra situada sobre la tabla de resultados de la consulta (junto al selector de tabla/gráfico). Esto abre un menú contextual en el que puede hacer clic en **"Copy query ID"**.

    Use `clusterAllReplicas(default, system.trace_log)` para seleccionar datos de todos los nodos del clúster:

    ```sql theme={null}
    SELECT
        count(),
        arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\n') AS sym
    FROM clusterAllReplicas(default, system.trace_log)
    WHERE query_id = '<query_id>' AND trace_type = 'CPU' AND event_date = today()
    GROUP BY trace
    ORDER BY count() DESC
    LIMIT 10
    ```
  </Tab>

  <Tab title="Autogestionado">
    ```sql theme={null}
    SELECT
        count(),
        arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\n') AS sym
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'CPU' AND event_date = today()
    GROUP BY trace
    ORDER BY count() DESC
    LIMIT 10
    ```
  </Tab>
</Tabs>

<div id="self-managed-query-profiler">
  ## Uso del perfilador de consultas en implementaciones autogestionadas
</div>

En las implementaciones autogestionadas, para usar el perfilador de consultas, siga los pasos que se indican a continuación:

<Steps>
  <Step title="Instale ClickHouse con información de depuración" id="debug-info">
    Instale el paquete `clickhouse-common-static-dbg`:

    1. Siga las instrucciones del paso ["Configurar el repositorio de Debian"](/es/get-started/setup/self-managed/debian-ubuntu#setup-the-debian-repository)
    2. Ejecute `sudo apt-get install clickhouse-server clickhouse-client clickhouse-common-static-dbg` para instalar los archivos binarios compilados de ClickHouse con información de depuración
    3. Ejecute `sudo service clickhouse-server start` para iniciar el servidor
    4. Ejecute `clickhouse-client`. El servidor detectará automáticamente los símbolos de depuración de clickhouse-common-static-dbg; no necesita hacer nada especial para habilitarlos
  </Step>

  <Step title="Compruebe la configuración del servidor" id="server-config">
    Asegúrese de que la sección [`trace_log`](/es/reference/settings/server-settings/settings/other#trace_log) de su [archivo de configuración del servidor](/es/concepts/features/configuration/server-config/configuration-files) esté configurada. Está habilitada de forma predeterminada:

    ```xml theme={null}
    <!-- Trace log. Stores stack traces collected by query profilers.
         See query_profiler_real_time_period_ns and query_profiler_cpu_time_period_ns settings. -->
    <trace_log>
        <database>system</database>
        <table>trace_log</table>

        <partition_by>toYYYYMM(event_date)</partition_by>
        <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>
        <!-- Indication whether logs should be dumped to the disk in case of a crash -->
        <flush_on_crash>false</flush_on_crash>
        <symbolize>true</symbolize>
    </trace_log>
    ```

    Esta sección configura la tabla del sistema [trace\_log](/es/reference/system-tables/trace_log), que contiene los resultados del funcionamiento del perfilador.
    La opción `symbolize` (habilitada de forma predeterminada) hace que ClickHouse resuelva cada marco de pila durante la recopilación y almacene los nombres de función desmanglados y las ubicaciones en el código fuente en las columnas `symbols` y `lines`.
    Los nombres de función de `symbols` proceden de la tabla de símbolos y están disponibles de forma predeterminada, mientras que las ubicaciones en el código fuente de `lines` requieren información de depuración (un paquete `.dSYM` en macOS) y, en plataformas ELF, solo se resuelven para los marcos del binario principal de ClickHouse; los marcos sin resolver tienen entradas vacías en `lines`.

    Tenga en cuenta que las direcciones sin procesar de la columna `trace` son menos estables entre reinicios y actualizaciones que las columnas presimbolizadas.
    En plataformas ELF, excepto FreeBSD, los marcos del binario principal de ClickHouse se almacenan como desplazamientos físicos dentro del archivo, por lo que pueden seguir resolviéndose tras los reinicios siempre que el binario no cambie; en macOS y FreeBSD, se almacenan como direcciones virtuales en tiempo de ejecución que pueden dejar de ser válidas después de un reinicio.
    Los marcos fuera del binario principal (por ejemplo, en bibliotecas compartidas) siempre se almacenan como direcciones virtuales en tiempo de ejecución que pueden dejar de ser válidas después de un reinicio, y cualquier dirección sin procesar deja de poder resolverse después de una actualización del binario porque cambia la disposición del código.
    ClickHouse no limpia la tabla al reiniciarse, por lo que pueden permanecer direcciones sin procesar obsoletas.
    Por otro lado, las columnas presimbolizadas `symbols` y `lines` siguen siendo válidas tras reinicios y actualizaciones, por lo que debe preferirlas al analizar datos históricos.
  </Step>

  <Step title="Configure los temporizadores del perfilador" id="configure-profile-timers">
    Configure las opciones [`query_profiler_cpu_time_period_ns`](/es/reference/settings/session-settings/query-profiler#query_profiler_cpu_time_period_ns) o [`query_profiler_real_time_period_ns`](/es/reference/settings/session-settings/query-profiler#query_profiler_real_time_period_ns).
    Ambas opciones pueden usarse simultáneamente.

    Estas opciones le permiten configurar los temporizadores del perfilador.
    Como se trata de opciones de sesión, puede obtener una frecuencia de muestreo distinta para todo el servidor, usuarios individuales o perfiles de usuario, para su sesión interactiva y para cada consulta individual.

    La frecuencia de muestreo predeterminada es de una muestra por segundo, y tanto los temporizadores de CPU como los de tiempo real están habilitados.
    Esta frecuencia le permite recopilar información suficiente sobre su clúster de ClickHouse sin afectar al rendimiento del servidor.
    Si necesita perfilar cada consulta individual, use una frecuencia de muestreo más alta.
  </Step>

  <Step title={<>Analice la tabla del sistema <code>trace_log</code></>} id="analyze-trace-log-system-table">
    Para obtener un perfil de alguna consulta, necesita agregar datos de la tabla `trace_log`.
    Puede agregar los datos por funciones individuales o por trazas de pila completas.

    Cuando la simbolización está habilitada (de forma predeterminada), los nombres de función desmangleados y las ubicaciones de origen ya están disponibles en las columnas `symbols` y `lines`, por lo que no se requiere configuración adicional. La simbolización no es compatible con FreeBSD, donde estas columnas siempre están vacías. Las entradas de `lines` pueden estar vacías para los marcos que no tienen información de depuración o quedan fuera del binario principal de ClickHouse (consulte [anteriormente](#server-config)).

    Si la simbolización está deshabilitada o desea resolver sobre la marcha las direcciones sin procesar de la columna `trace` (por ejemplo, para expandir marcos en línea), habilite las funciones de introspección con la opción [`allow_introspection_functions`](/es/reference/settings/session-settings/allow#allow_introspection_functions):

    ```sql theme={null}
    SET allow_introspection_functions=1
    ```

    <Note>
      Por razones de seguridad, las funciones de introspección están deshabilitadas de forma predeterminada
    </Note>

    Use las [funciones de introspección](/es/reference/functions/regular-functions/introspection) `addressToLine`, `addressToLineWithInlines`, `addressToSymbol` y `demangle` para obtener los nombres de las funciones y sus posiciones en el código de ClickHouse. Al igual que la simbolización, estas funciones están disponibles en plataformas ELF (como Linux) y macOS, pero no en FreeBSD.

    <Tip>
      Si necesita visualizar la información de `trace_log`, pruebe [flamegraph](/es/integrations/connectors/tools/gui#clickhouse-flamegraph) y [speedscope](https://www.speedscope.app).
    </Tip>
  </Step>
</Steps>

<div id="flamegraph">
  ## Crear flame graphs con la función `flameGraph`
</div>

ClickHouse proporciona la función de agregación [`flameGraph`](/es/reference/functions/aggregate-functions/flame_graph), que genera un flame graph directamente a partir de las trazas de pila almacenadas en `trace_log`.
La salida es un array de cadenas en un formato compatible con [flamegraph.pl](https://github.com/brendangregg/FlameGraph).

**Sintaxis:**

```sql theme={null}
flameGraph(traces, [size = 1], [ptr = 0])
```

**Argumentos:**

* `traces` — una traza de pila. [`Array(UInt64)`](/es/reference/data-types/array).
* `size` — el tamaño de una asignación para el profiling de memoria. [`Int64`](/es/reference/data-types/int-uint).
* `ptr` — una dirección de asignación. [`UInt64`](/es/reference/data-types/int-uint).

Cuando `ptr` no es cero, `flameGraph` empareja las asignaciones (`size > 0`) y las liberaciones de memoria (`size < 0`) que tienen el mismo tamaño y puntero.
Solo se muestran las asignaciones que no se liberaron.
Las liberaciones de memoria sin correspondencia se ignoran.

<div id="cpu-flame-graph">
  ### flame graph de CPU
</div>

<Note>
  Las consultas siguientes requieren que tengas instalado [flamegraph.pl](https://github.com/brendangregg/FlameGraph).

  Para ello, ejecuta:

  ```bash theme={null}
  git clone https://github.com/brendangregg/FlameGraph
  # Luego úsalo así:
  # ~/FlameGraph/flamegraph.pl
  ```

  Sustituye `flamegraph.pl` en las siguientes consultas por la ruta en la que se encuentra `flamegraph.pl` en tu equipo
</Note>

```sql theme={null}
SET query_profiler_cpu_time_period_ns = 10000000;
```

Ejecuta tu consulta y luego genera el flame graph:

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(arrayReverse(trace)))
        FROM system.trace_log
        WHERE trace_type = 'CPU' AND query_id = '<query_id>'" \
    | flamegraph.pl > flame_cpu.svg
```

<div id="memory-flame-graph-all">
  ### flame graph de memoria — todas las asignaciones
</div>

```sql theme={null}
SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;
```

Ejecute la consulta y, a continuación, genere el flame graph:

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size))
        FROM system.trace_log
        WHERE trace_type = 'MemorySample' AND query_id = '<query_id>'" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem.svg
```

<div id="memory-flame-graph-unfreed">
  ### flame graph de memoria — asignaciones no liberadas
</div>

Esta variante relaciona las asignaciones con las desasignaciones por puntero y muestra únicamente la memoria que no se liberó durante la consulta.

```sql theme={null}
SET memory_profiler_sample_probability = 1, max_untracked_memory = 1,
    use_uncompressed_cache = 1,
    merge_tree_max_rows_to_use_cache = 100000000000,
    merge_tree_max_bytes_to_use_cache = 1000000000000;
```

Ejecute la siguiente consulta para generar el flame graph:

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size, ptr))
        FROM system.trace_log
        WHERE trace_type = 'MemorySample' AND query_id = '<query_id>'" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_unfreed.svg
```

<div id="memory-flame-graph-time-point">
  ### Flame graph de memoria — asignaciones activas en un momento dado
</div>

Este enfoque permite identificar el pico de uso de memoria y visualizar qué se había asignado en ese momento.

```sql theme={null}
SET memory_profiler_sample_probability = 1, max_untracked_memory = 1;
```

<div id="find-memory-usage-over-time">
  #### Ver el uso de memoria a lo largo del tiempo
</div>

```sql theme={null}
SELECT
    event_time,
    formatReadableSize(max(s)) AS m
FROM (
    SELECT
        event_time,
        sum(size) OVER (ORDER BY event_time) AS s
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'MemorySample'
)
GROUP BY event_time
ORDER BY event_time;
```

<div id="find-time-point-maximum-memory-usage">
  #### Encontrar el momento de mayor uso de memoria
</div>

```sql theme={null}
SELECT
    argMax(event_time, s),
    max(s)
FROM (
    SELECT
        event_time,
        sum(size) OVER (ORDER BY event_time) AS s
    FROM system.trace_log
    WHERE query_id = '<query_id>' AND trace_type = 'MemorySample'
);
```

<div id="build-flame-graph">
  #### Crear un flame graph de las asignaciones activas en ese instante
</div>

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, size, ptr))
        FROM (
            SELECT * FROM system.trace_log
            WHERE trace_type = 'MemorySample'
              AND query_id = '<query_id>'
              AND event_time <= '<time_point>'
            ORDER BY event_time
        )" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_time_point_pos.svg
```

<div id="build-flame-graph-deallocations">
  #### Crea un flame graph de las liberaciones de memoria posteriores a ese momento (para entender qué se liberó después)
</div>

```bash theme={null}
clickhouse client --allow_introspection_functions=1 \
    -q "SELECT arrayJoin(flameGraph(trace, -size, ptr))
        FROM (
            SELECT * FROM system.trace_log
            WHERE trace_type = 'MemorySample'
              AND query_id = '<query_id>'
              AND event_time > '<time_point>'
            ORDER BY event_time DESC
        )" \
    | flamegraph.pl --countname=bytes --color=mem > flame_mem_time_point_neg.svg
```

<div id="example">
  ## Ejemplo
</div>

El siguiente fragmento de código:

* Filtra los datos de `trace_log` por un identificador de consulta y la fecha actual.
* Lee las columnas `symbols` y `lines` presimbolizadas para generar un informe sobre:
  * Los nombres de los símbolos y las funciones de código fuente correspondientes.
  * Las ubicaciones en el código fuente de estas funciones.
* Agrupa por la traza de pila sin procesar (la columna `trace`) y usa las columnas simbolizadas solo para mostrar, de modo que la simbolización aproximada nunca agrupe trazas de pila distintas.

```sql theme={null}
SELECT
    count(),
    arrayStringConcat(arrayMap((symbol, line) -> concat(symbol, '\n    ', line), any(symbols), any(lines)), '\n') AS sym
FROM system.trace_log
WHERE (query_id = '<query_id>') AND (event_date = today())
GROUP BY trace
ORDER BY count() DESC
LIMIT 10
```