Comment collecter et visualiser la trace d’une requête

Ce guide vous montre comment collecter et visualiser des traces de requête avec une instance ClickHouse autogérée, soit à l’aide des méthodes intégrées, soit avec Grafana. Cela est particulièrement utile lorsque vous travaillez sur des requêtes complexes et devez comprendre les mécanismes internes d’exécution au-delà de ce que fournit EXPLAIN.

Prérequis :

• Connaissance des fichiers de configuration de ClickHouse
• Une instance du serveur ClickHouse en cours d’exécution
• (Facultatif) Une instance locale de Grafana en cours d’exécution

1. Vérifiez que la table système opentelemetry_span_log est activée

   Si vous n’avez apporté aucune modification à la section opentelemetry_span_log de config.xml, vous pouvez ignorer cette étape.

   Ouvrez le fichier config.xml par défaut de ClickHouse et repérez la section suivante :

   <!--
       OpenTelemetry log contains OpenTelemetry trace spans.
   
       NOTE: this table does not use standard schema with event_date and event_time!
   -->
   <opentelemetry_span_log>
       <!--
           The default table creation code is insufficient, this <engine> spec
           is a workaround. There is no 'event_time' for this log, but two times,
           start and finish. It is sorted by finish time, to avoid inserting
           data too far away in the past (probably we can sometimes insert a span
           that is seconds earlier than the last span in the table, due to a race
           between several spans inserted in parallel). This gives the spans a
           global order that we can use to e.g. retry insertion into some external
           system.
       -->
       <engine>
           engine MergeTree
           partition by toYYYYMM(finish_date)
           order by (finish_date, finish_time_us, trace_id)
       </engine>
       <database>system</database>
       <table>opentelemetry_span_log</table>
       <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>
   </opentelemetry_span_log>
   

   Assurez-vous qu’il n’est pas commenté, sinon vous ne pourrez pas voir system.opentelemetry_span_log dans les étapes suivantes. Cela peut aussi arriver si votre serveur ClickHouse n’utilise pas le fichier de configuration par défaut.

   Vérifiez les logs de votre serveur pour y trouver quelque chose comme :

   Processing configuration file 'config.xml'.
   There is no file 'config.xml', will use embedded config.
   

   Dans les installations standard, ce fichier se trouve à l’emplacement /etc/clickhouse-server/config.xml

2. Activer le traçage OpenTelemetry

   Une fois le serveur ClickHouse démarré, ouvrez le client ClickHouse et activez la collecte des traces à l’aide de la requête suivante :

   SET opentelemetry_trace_processors=1;
   

   Vous devriez maintenant voir la table système opentelemetry_span_log en exécutant :

   SHOW TABLES IN system
   

   Prochaine exécution :

   SET opentelemetry_start_trace_probability=1;
   

   Cela définit la probabilité que ClickHouse démarre une trace pour les requêtes exécutées, où 1 signifie que le traçage est activé pour toutes les requêtes exécutées.

3. Obtenir un identifiant de requête

   Exécutez la requête de test suivante, ou la requête que vous souhaitez tracer :

   SELECT pow(number, 2) FROM numbers(10E4);
   

   Copiez l’ID de requête :

   :) SELECT pow(number, 2) FROM numbers(10E4);
   
   SELECT pow(number, 2)
   FROM numbers(100000.)
   
   Query id: a9241258-a0c4-4776-a00b-e6a1d9bec4a1
   

4. Générer un fichier de trace

   Exécutez la requête suivante en remplaçant l’ID de requête par celui que vous avez obtenu à l’étape précédente :

   WITH 'a9241258-a0c4-4776-a00b-e6a1d9bec4a1' AS my_query_id
   SELECT
       concat(substring(hostName(), length(hostName()), 1), leftPad(greatest(attribute['clickhouse.thread_id'], attribute['thread_number']), 5, '0')) AS group,
       operation_name,
       start_time_us,
       finish_time_us,
       sipHash64(operation_name) AS color,
       attribute
   FROM system.opentelemetry_span_log
   WHERE (trace_id IN (
       SELECT trace_id
       FROM system.opentelemetry_span_log
       WHERE (attribute['clickhouse.query_id']) = my_query_id
   )) AND (operation_name != 'query') AND (operation_name NOT LIKE 'Query%')
   ORDER BY
       hostName() ASC,
       group ASC,
       parent_span_id ASC,
       start_time_us ASC
   INTO OUTFILE 'trace.json'
   FORMAT JSON
   SETTINGS output_format_json_named_tuples_as_objects = 1
   

   Cela écrira la trace dans un fichier nommé trace.json. Par défaut, ce fichier est créé dans le répertoire de travail courant à partir duquel vous exécutez l’outil clickhouse-client ou clickhouse-local.

5. Visualiser une trace avec les outils intégrés

   Utilisez le visualiseur de traces hébergé à l’adresse https://trace-visualizer.clickhouse.com/. Chargez le fichier trace.json de l’étape précédente pour visualiser la trace.

6. Utiliser Grafana pour visualiser les traces

   Nous recommandons Grafana pour visualiser et explorer les données de traces à l’aide du plugin ClickHouse officiel. Le plugin a été amélioré afin de permettre la visualisation des traces à l’aide du panneau Trace Panel. Cela est pris en charge à la fois en tant que visualisation et en tant que composant dans Explore.

   Suivez les étapes décrites dans “Utiliser Grafana et ClickHouse pour l’observabilité” pour configurer Grafana avec le plugin ClickHouse.

   Depuis l’onglet Explore, vous pouvez ensuite exécuter la requête suivante en remplaçant le trace_id par le vôtre :

   SELECT
       toString(trace_id) AS traceID,
       toString(span_id) AS spanID,
       if(toString(parent_span_id)='0', '', toString(parent_span_id)) AS parentSpanID,
       'ClickHouse' AS serviceName,
       operation_name AS operationName,
       start_time_us/1000000 AS startTime,
       (finish_time_us - start_time_us)/1000 AS duration,
       arrayMap(key -> map('key', key, 'value', attribute[key]), mapKeys(attribute)) AS serviceTags
   FROM system.opentelemetry_span_log
   WHERE trace_id = '68a14b27-a61f-596d-3746-2b03d2530e42' ORDER BY startTime ASC
   

   Assurez-vous de définir Query type sur Traces :

   Cliquez sur “Run Query” et examinez le diagramme de traces :