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

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

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

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.

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

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.

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.

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 :