system.trace_log

Table système contenant les traces de pile collectées par le profileur de requêtes par échantillonnage.

Interroger dans ClickHouse Cloud

Les données de cette table système sont stockées localement sur chaque nœud de ClickHouse Cloud. Pour obtenir une vue complète de l’ensemble des données, il faut donc utiliser la fonction clusterAllReplicas. Consultez cette page pour plus de détails.

​

Description

Contient les traces de pile collectées par le profileur de requêtes par échantillonnage.

ClickHouse crée cette table lorsque la section de configuration du serveur trace_log est définie. Voir aussi les paramètres : query_profiler_real_time_period_ns, query_profiler_cpu_time_period_ns, memory_profiler_step, memory_profiler_sample_probability, trace_profile_events.

Lorsque la symbolisation est activée (par défaut), les noms de fonctions démanglés et les emplacements dans le code source sont déjà disponibles dans les colonnes symbols et lines, ce qui vous permet d’analyser directement les journaux sans utiliser de fonctions d’introspection. Le paramètre symbolize s’applique aux types de trace collectés par le profileur ; les lignes dont le type de trace est Instrumentation sont symbolisées indépendamment de ce paramètre. La symbolisation est prise en charge sur les plateformes ELF (telles que Linux) et macOS ; sur FreeBSD, les colonnes symbols et lines sont toujours vides. Les noms de fonctions dans symbols proviennent de la table des symboles du binaire et sont disponibles par défaut, tandis que les emplacements dans le code source dans lines sont fournis dans la mesure du possible : ils nécessitent des informations de débogage (un bundle .dSYM sur macOS) et, sur les plateformes ELF, ne sont résolus que pour les frames situées dans le binaire principal de ClickHouse ; les frames non résolues ont des entrées lines vides. Si la symbolisation est désactivée ou si vous souhaitez résoudre à la volée les adresses brutes de la colonne trace (par exemple, pour développer les frames intégrées), utilisez les fonctions d’introspection addressToLine, addressToLineWithInlines, addressToSymbol et demangle. Ces fonctions sont disponibles sur les mêmes plateformes que la symbolisation (les plateformes ELF telles que Linux et macOS) ; sur FreeBSD, elles ne sont pas non plus compilées, de sorte que les adresses dans trace doivent être résolues en dehors du serveur.

​

Colonnes

• hostname (LowCardinality(String)) — Nom d’hôte du serveur qui exécute la requête.
• event_date (Date) — Date du moment d’échantillonnage.
• event_time (DateTime) — Horodatage du moment d’échantillonnage.
• event_time_microseconds (DateTime64(6)) — Horodatage du moment d’échantillonnage avec une précision à la microseconde.
• timestamp_ns (UInt64) — Horodatage du moment d’échantillonnage en nanosecondes.
• revision (UInt32) — Révision de build du serveur ClickHouse. Lors de la connexion au serveur avec clickhouse-client, vous voyez une chaîne semblable à Connected to ClickHouse server version 19.18.1.. Ce champ contient la revision, mais pas la version d’un serveur.
• trace_type (Enum8(‘Real’ = 0, ‘CPU’ = 1, ‘Memory’ = 2, ‘MemorySample’ = 3, ‘MemoryPeak’ = 4, ‘ProfileEvent’ = 5, ‘JemallocSample’ = 6, ‘MemoryAllocatedWithoutCheck’ = 7, ‘Instrumentation’ = 8)) — Type de trace : Real représente la collecte de stack traces selon le temps réel. CPU représente la collecte de stack traces selon le temps CPU. Memory représente la collecte des allocations et désallocations lorsque l’allocation mémoire dépasse le watermark suivant. MemorySample représente la collecte aléatoire d’allocations et de désallocations. MemoryPeak représente la collecte des mises à jour du pic d’utilisation mémoire. ProfileEvent représente la collecte des incréments des profile events. JemallocSample représente la collecte d’échantillons jemalloc. MemoryAllocatedWithoutCheck représente la collecte d’allocations importantes (>16MiB) effectuée en ignorant toute limite mémoire (réservé aux développeurs ClickHouse). Instrumentation représente les traces collectées par l’instrumentation effectuée via XRay.
• cpu_id (UInt64) — Identifiant CPU.
• thread_id (UInt64) — Identifiant du thread.
• thread_name (LowCardinality(String)) — Nom du thread.
• query_id (String) — Identifiant de requête pouvant être utilisé pour obtenir les détails d’une requête en cours d’exécution à partir de la table système query_log.
• trace (Array(UInt64)) — Stack trace au moment de l’échantillonnage. Pour les types de trace collectés par le profiler, sur les plateformes ELF à l’exception de FreeBSD, les adresses à l’intérieur du binaire principal ClickHouse sont stockées sous forme de décalages physiques dans le fichier, et les autres adresses sont des adresses de mémoire virtuelle à l’intérieur du processus serveur ClickHouse. Les lignes de trace Instrumentation constituent une exception : elles stockent des adresses brutes de mémoire virtuelle.
• size (Int64) — Pour les types de trace Memory, MemorySample, MemoryAllocatedWithoutCheck ou MemoryPeak, il s’agit de la quantité de mémoire allouée ; pour les autres types de trace, la valeur est 0.
• ptr (UInt64) — Adresse du chunk alloué.
• memory_context (Enum8(‘Unknown’ = -1, ‘Global’ = 0, ‘User’ = 1, ‘Process’ = 2, ‘Thread’ = 3, ‘Max’ = 4)) — Contexte du Memory Tracker (uniquement pour Memory/MemoryPeak) : le contexte Unknown n’est pas défini pour ce trace_type. Global représente le contexte du serveur. User représente le contexte utilisateur/merge. Process représente le contexte du processus (c.-à-d. de la requête). Thread représente le contexte du thread (thread d’un processus particulier). Max est une valeur spéciale qui signifie que le memory tracker n’est pas bloqué (pour la colonne blocked_context).
• memory_blocked_context (Enum8(‘Unknown’ = -1, ‘Global’ = 0, ‘User’ = 1, ‘Process’ = 2, ‘Thread’ = 3, ‘Max’ = 4)) — Contexte pour lequel le traqueur de mémoire est bloqué (réservé aux développeurs ClickHouse) : le contexte Unknown n’est pas défini pour ce trace_type. Global représente le contexte du serveur. User représente le contexte utilisateur/de fusion. Process représente le contexte du processus (c.-à-d. de la requête). Thread représente le contexte du thread (thread d’un processus particulier). Max est une valeur spéciale qui signifie que le traqueur de mémoire n’est pas bloqué (pour la colonne blocked_context).
• event (LowCardinality(String)) — Pour le type de trace ProfileEvent, il s’agit du nom de l’événement de profil mis à jour ; pour les autres types de trace, c’est une chaîne vide.
• increment (Int64) — Pour le type de trace ProfileEvent, il s’agit de la valeur d’incrément de l’événement de profil ; pour les autres types de trace, c’est 0.
• symbols (Array(LowCardinality(String))) — Si la symbolisation est activée, contient les noms de symboles démanglés correspondant à la trace. La symbolisation peut être activée ou désactivée dans le paramètre symbolize sous trace_log dans le fichier de configuration du serveur ; ce paramètre s’applique aux types de trace collectés par le profiler, tandis que les lignes dont le type de trace est Instrumentation sont symbolisées indépendamment de ce paramètre. La symbolisation est prise en charge sur les plateformes ELF (telles que Linux) et macOS ; sur FreeBSD, cette colonne est toujours vide.
• lines (Array(LowCardinality(String))) — Si la symbolisation est activée, contient des chaînes avec les noms de fichiers et les numéros de ligne correspondant à la trace. Le paramètre symbolize s’applique aux types de trace collectés par le profiler, tandis que les lignes dont le type de trace est Instrumentation sont symbolisées indépendamment de ce paramètre. La symbolisation est prise en charge sur les plateformes ELF (telles que Linux) et macOS ; sur FreeBSD, cette colonne est toujours vide. Les emplacements source sont fournis dans la mesure du possible : ils nécessitent des informations de débogage (un bundle .dSYM sur macOS) et, sur les plateformes ELF, ne sont résolus que pour les frames situées dans le binaire ClickHouse principal ; les frames non résolues comportent des entrées vides.
• function_id (Nullable(Int32)) — Pour le type de trace Instrumentation, ID attribué à la fonction dans la section xray_instr_map du binaire ELF.
• function_name (Nullable(String)) — Pour le type de trace Instrumentation, nom de la fonction instrumentée.
• handler (Nullable(String)) — Pour le type de trace Instrumentation, gestionnaire de la fonction instrumentée.
• entry_type (Nullable(Enum8(‘Entry’ = 0, ‘Exit’ = 1))) — Pour le type de trace Instrumentation, type d’entrée de la fonction instrumentée.
• duration_nanoseconds (Nullable(UInt64)) — Pour le type de trace Instrumentation, durée d’exécution de la fonction en nanosecondes.

Alias :

• build_id — Alias de l’ID de build du binaire du serveur ClickHouse en cours d’exécution.

La symbolisation peut être activée ou désactivée à l’aide du paramètre symbolize de trace_log dans le fichier de configuration du serveur. Elle est activée par défaut. Ce paramètre s’applique aux types de traces collectées par le profileur ; les lignes dont le type de trace est Instrumentation sont symbolisées indépendamment de ce paramètre.

​

Exemple

SELECT * FROM system.trace_log LIMIT 1 \G

Row 1:
──────
hostname:                clickhouse.eu-central1.internal
event_date:              2025-11-11
event_time:              2025-11-11 11:53:59
event_time_microseconds: 2025-11-11 11:53:59.128333
timestamp_ns:            1762862039128333000
revision:                54504
trace_type:              Instrumentation
cpu_id:                  19
thread_id:               3166432 -- 3.17 million
query_id:                ef462508-e189-4ea2-b231-4489506728e8
trace:                   [350594916,447733712,447742095,447727324,447726659,221642873,450882315,451852359,451905441,451885554,512404306,512509092,612861767,612863269,612466367,612455825,137631896259267,137631896856768]
size:                    0
ptr:                     0
memory_context:          Unknown
memory_blocked_context:  Unknown
event:
increment:               0
symbols:                 ['StackTrace::StackTrace()','DB::InstrumentationManager::createTraceLogElement(DB::InstrumentationManager::InstrumentedPointInfo const&, XRayEntryType, std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>>) const','DB::InstrumentationManager::profile(XRayEntryType, DB::InstrumentationManager::InstrumentedPointInfo const&)','DB::InstrumentationManager::dispatchHandlerImpl(int, XRayEntryType)','DB::InstrumentationManager::dispatchHandler(int, XRayEntryType)','__xray_FunctionEntry','DB::QueryMetricLog::startQuery(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>>, unsigned long)','DB::logQueryStart(std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>> const&, std::__1::shared_ptr<DB::Context> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, unsigned long, std::__1::shared_ptr<DB::IAST> const&, DB::QueryPipeline const&, DB::IInterpreter const*, bool, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, bool)','DB::executeQueryImpl(char const*, char const*, std::__1::shared_ptr<DB::Context>, DB::QueryFlags, DB::QueryProcessingStage::Enum, std::__1::unique_ptr<DB::ReadBuffer, std::__1::default_delete<DB::ReadBuffer>>&, std::__1::shared_ptr<DB::IAST>&, std::__1::shared_ptr<DB::ImplicitTransactionControlExecutor>, std::__1::function<void ()>)','DB::executeQuery(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::shared_ptr<DB::Context>, DB::QueryFlags, DB::QueryProcessingStage::Enum)','DB::TCPHandler::runImpl()','DB::TCPHandler::run()','Poco::Net::TCPServerConnection::start()','Poco::Net::TCPServerDispatcher::run()','Poco::PooledThread::run()','Poco::ThreadImpl::runnableEntry(void*)','start_thread','__clone3']
lines:                   ['./build/../src/Common/StackTrace.cpp:395','./src/Common/StackTrace.h:62','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:738','./build/./src/Interpreters/InstrumentationManager.cpp:257','./build/./src/Interpreters/InstrumentationManager.cpp:225','','./build/./src/Interpreters/QueryMetricLog.cpp:0','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:667','./build/./src/Interpreters/executeQuery.cpp:0','./build/./src/Interpreters/executeQuery.cpp:0','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:744','./contrib/llvm-project/libcxx/include/__memory/shared_ptr.h:583','./build/../base/poco/Net/src/TCPServerConnection.cpp:54','../contrib/llvm-project/libcxx/include/__memory/unique_ptr.h:80','./build/../base/poco/Foundation/src/ThreadPool.cpp:219','../base/poco/Foundation/include/Poco/AutoPtr.h:77','','']
function_id:             231255
function_name:           DB::QueryMetricLog::startQuery(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char>> const&, std::__1::chrono::time_point<std::__1::chrono::system_clock, std::__1::chrono::duration<long long, std::__1::ratio<1l, 1000000l>>>, unsigned long)
handler:                 profile
entry_type:              Exit
duration_nanoseconds:   58435

​

Conversion vers le format Event Trace de Chrome

Les données de profilage peuvent être converties au format Event Trace de Chrome à l’aide de la requête suivante. Enregistrez cette requête dans un fichier chrome_trace.sql :

WITH traces AS (
    SELECT * FROM system.trace_log
    WHERE event_date >= today() AND trace_type = 'Instrumentation' AND handler = 'profile'
    ORDER BY event_time, entry_type
)
SELECT
    format(
        '{{"traceEvents": [{}\n]}}',
        arrayStringConcat(
            groupArray(
                format(
                    '\n{{"name": "{}", "cat": "clickhouse", "ph": "{}", "ts": {}, "pid": 1, "tid": {}, "args": {{"query_id": "{}", "cpu_id": {}, "stack": [{}]}}}},',
                    function_name,
                    if(entry_type = 0, 'B', 'E'),
                    timestamp_ns/1000,
                    toString(thread_id),
                    query_id,
                    cpu_id,
                    arrayStringConcat(arrayMap((x, y) -> concat('"', x, ': ', y, '", '), lines, symbols))
                )
            )
        )
    )
FROM traces;

Et l’exécuter avec ClickHouse Client afin de l’exporter dans un fichier trace.json, que nous pouvons importer soit dans Perfetto, soit dans speedscope.

echo $(clickhouse client --query "$(cat chrome_trace.sql)") > trace.json

Nous pouvons omettre la partie stack si nous voulons une trace plus compacte, mais moins riche en informations.

​

Voir aussi

• SYSTEM INSTRUMENT — Ajouter ou supprimer des points d’instrumentation.
• system.instrumentation — Examiner les points instrumentés.
• system.symbols — Examiner les symboles afin d’ajouter des points d’instrumentation.