Guide pas à pas d'HyperDX

HyperDX est l'interface d'observabilité intégrée à ClickStack, fournie avec chaque service ClickHouse Cloud. Ce guide vous accompagne dans les quatre opérations à effectuer dans HyperDX pour l'atelier de migration :

1. Lancer ClickStack depuis la console Cloud.
2. Créer trois sources de données, une pour les traces, une pour les journaux et une pour les métriques OTEL, qui pointent vers la base de données otel alimentée à l'étape 2.
3. Rechercher des journaux en temps réel dans la vue Search afin de confirmer l'arrivée des données.
4. Construire un graphique avec l'assistant IA pour illustrer la visualisation à la volée sans écrire de SQL.

Prérequis : l'étape 4 de README.md s'est terminée sans erreur : otel.otel_logs_v2, otel.otel_traces et otel.otel_metrics_* reçoivent tous des données, ce que vous pouvez confirmer avec bash scripts/validate_migration.sh.

---

Étape A — lancer ClickStack

1. Connectez-vous à clickhouse.cloud et ouvrez le service provisionné à l'étape 1 du README.
2. Dans la barre latérale gauche de la console SQL, faites défiler la page jusqu'en bas. Cliquez sur l'icône de lancement (↗) située à côté de ClickStack (Beta).
3. ClickStack s'ouvre dans un nouvel onglet et vous authentifie au moyen du SSO Cloud ; aucune connexion distincte n'est nécessaire.

Ce que vous devez d'abord voir dans la console SQL : le sélecteur de base de données (en haut au centre) doit contenir la base otel, avec les 11 tables, 3 vues matérialisées et 2 dictionnaires créés à l'étape 2 : otel_logs, otel_logs_v2, otel_traces, otel_metrics_* (5 tables), geoip_data + geoip_country/geoip_city (1 table + 2 dictionnaires), alert_error_rate*, logs_summary_1min*. S'il en manque, exécutez à nouveau clickhouse/dictionaries.sql, clickhouse/schema.sql et clickhouse/alert-tables.sql avant de poursuivre.

---

Étape B — créer les trois sources de données

HyperDX interroge ClickHouse au moyen de « sources » nommées qui relient un onglet de l'interface (Search, Service Map, Chart Explorer, etc.) à une table donnée et à une convention de mise en correspondance des colonnes. Vous allez créer une source par type de signal.

Dans la barre latérale en bas à gauche, ouvrez Team Settings, puis Data → Sources. Cliquez sur Add source pour créer chacune des trois sources ci-dessous.

B.1 — source des traces

Cliquez sur Save Source. Le résumé Trace, Default, otel.otel_traces doit apparaître en haut de la liste Sources.

B.2 — source des journaux

Cliquez à nouveau sur Add source, puis configurez :

Pourquoi TimestampTime et non Timestamp ? Timestamp est de type DateTime64(9) (nanosecondes). Le sélecteur de période et le regroupement de l'histogramme d'HyperDX emploient par défaut la précision DateTime ; les faire pointer vers la colonne matérialisée TimestampTime évite des conversions implicites dans chaque requête de tableau de bord.

B.3 — source OTEL Metrics

Cliquez à nouveau sur Add source, puis configurez :

La source OTEL Metrics couvre les cinq tables de métriques, car le modèle de données OTel encode les différents types de métriques dans des lignes et des formes distinctes. HyperDX dirige la requête vers la bonne table en fonction du type de métrique interrogé. Le réglage Correlated Log Source = log permet de passer en un clic d'un graphique de métriques aux journaux correspondants.

Une fois les trois sources enregistrées, la liste Sources doit afficher Traces, log et otel_metrics, sous la même forme que la capture d'écran ci-dessus (une entrée repliée par source).

---

Étape C — rechercher les journaux en temps réel

Dans la barre latérale gauche, cliquez sur Search. En haut de la page, sélectionnez la source log que vous venez de créer.

Vous devez voir :

• un histogramme du nombre d'événements au fil du temps (utilisez le sélecteur de période pour choisir « Last 15 minutes » ou « Last 1 hour ») ;
• une table de lignes de journaux comportant les colonnes Timestamp, service, level, body ;
• une barre latérale de facettes à gauche, qui répertorie des champs à forte cardinalité tels que ServiceName (avec le nombre d'événements par service) et SeverityText.

Quelques essais à effectuer :

• Filtrer sur un service : cliquez sur inventory-service (ou tout autre service) sous la facette ServiceName ; la table se recharge en une fraction de seconde avec les données de ce service uniquement.
• Rechercher une chaîne : saisissez error dans la barre de recherche supérieure. Les index de texte de ClickHouse (l'index de saut text(tokenizer='sparseGrams') sur Body dans schema.sql) accélèrent considérablement cette opération par rapport à une analyse complète.
• Inspecter une ligne : cliquez sur une ligne de journal pour développer la vue structurée ; chaque clé de la Map LogAttributes devient un filtre cliquable.

Remarque concernant la période : le réglage start_at: end du collecteur de fichiers signifie que les lignes historiques antérieures à l'étape 3b ne figurent pas dans otel_logs_v2. Si « Last 24 hours » semble peu fourni pendant les premières heures, c'est normal : les données commencent au démarrage du collecteur.

---

Étape D — construire un graphique avec l'assistant IA

L'assistant IA d'HyperDX (actuellement désigné comme Experimental) traduit des descriptions en langage naturel en configurations de graphique.

1. Dans la barre latérale gauche, cliquez sur Chart Explorer.

2. En haut du volet du graphique, activez AI Assistant [A].

3. Après avoir sélectionné la source log, saisissez une instruction en langage naturel dans le champ, par exemple :

   Error count by services for past 2 hours

4. Appuyez sur Entrée. L'assistant remplit la configuration du graphique ci-dessous : type de graphique (Line/Bar), source de données (log), agrégation (Count of Events) et clause Where (SeverityText = 'ERROR').

5. Le graphique s'affiche immédiatement. Modifiez la période ou le type de graphique au moyen des onglets supérieurs (Line/Bar, Table, Number, Pie, Search, Markdown).

Enregistrez les graphiques utiles en renseignant le champ Chart Name et en cliquant sur l'icône d'enregistrement ; ils apparaîtront sous Saved Searches / Dashboards dans la barre latérale et pourront être réutilisés.

Bibliothèque d'instructions — recréer tous les panneaux Kibana de la partie 1

Les six tableaux de bord Kibana de la partie 1 contiennent 30 panneaux au total. Les tableaux ci-dessous fournissent une instruction par panneau pour recréer chaque graphique dans HyperDX. Pour chaque entrée :

• Source — sélectionnez-la dans l'assistant IA avant d'envoyer l'instruction (log pour tout ce qui provient d'otel_logs_v2, Traces pour tout ce qui provient d'otel_traces, otel_metrics pour les graphiques de métriques).
• Graphique — onglet du type de graphique HyperDX à sélectionner (ou laissez l'assistant choisir) avant l'enregistrement. Consultez la légende ci-dessous.
• Filtre — de nombreux panneaux Kibana étaient implicitement limités par flux de données (par exemple, le tableau de bord Web Traffic n'interrogeait que logs-web_access-lab). Dans ClickHouse, vous exprimez cette contrainte avec une clause Where ; les instructions ci-dessous incluent le filtre ou s'appuient sur celui de la source HyperDX. Si l'assistant IA ne reprend pas le filtre, passez le graphique en mode SQL et ajoutez l'expression Where proposée.
• Solution de repli pour le nom des champs — l'assistant IA fait correspondre les termes en langage naturel aux colonnes du schéma. Si une instruction produit un graphique vide, modifiez manuellement le champ Where / d'agrégation généré à l'aide des indications de la colonne Indication de champ.

Types de graphiques HyperDX — légende de référence

Le volet Chart Explorer comporte six onglets en haut (Line/Bar, Table, Number, Pie, Search, Markdown). Voici la correspondance entre les types de graphiques HyperDX et les visualisations Kibana qu'ils remplacent :

Où se trouve « Histogram » ? Kibana propose une visualisation « Histogram » distincte (nombre d'événements regroupés par champ numérique ou de date). HyperDX l'intègre à l'onglet Line/Bar : choisissez un champ de date ou numérique pour groupBy, sélectionnez la forme bar, et vous obtenez un histogramme. La bande d'histogramme autonome vue en haut de la vue Search à l'étape C est générée automatiquement ; il ne s'agit pas d'un graphique à créer manuellement.

Principales différences de noms de colonnes par rapport à ECS dans Kibana : request_path → RequestPath (brut) ou RequestPage (chemin uniquement, recommandé pour le regroupement) ; request_type → RequestType (méthode HTTP) ; status → StatusCode ; geo.country_name → GeoCountry ; user_agent_parsed.name → BrowserFamily ; service / service.name → ServiceName ; level → LogLevel ou SeverityText ; event.severity → SeverityText ; hostname → HostName ; event.outcome → dérivé de StatusCode (succès pour 1xx–3xx / échec pour 4xx–5xx dans les traces) ; transaction.duration.us (μs) → Duration (nanosecondes ; diviser par 1 000 pour obtenir des μs).

Web Traffic Overview — 8 panneaux

Filtrez-les tous pour ne conserver que les journaux d'accès web : dans l'assistant IA ou le champ Where du graphique, ajoutez RequestType != ''.

Application Health — 5 panneaux

Les journaux d'application sont les lignes où le niveau est défini, mais où RequestType est vide (les accès web comportent les deux). Filtre : LogLevel != '' AND RequestType = ''.

Infrastructure Overview — 4 panneaux

Les lignes d'infrastructure (syslog) ont un ServiceName qui commence par k8s- (regex_parser promeut le nom d'hôte syslog en service.name). Filtre : ServiceName LIKE 'k8s-%'.

OTel Demo — APM Traces — 6 panneaux

Les traces arrivent dans otel.otel_traces. Avant d'exécuter ces instructions, sélectionnez la source de données Traces dans l'assistant IA.

OTel Demo — Latency — 4 panneaux

OTel Demo — Logs — 3 panneaux

Les journaux OTel Demo provenant des services de la démonstration (frontend-proxy, cart, checkout, etc.) arrivent dans otel.otel_logs_v2. Ni RequestType ni LogLevel n'y sont matérialisés ; distinguez-les avec ServiceName NOT LIKE 'k8s-%' AND RequestType = ''.

Conseils lorsque l'assistant IA se trompe

1. Passez en mode SQL dans le sélecteur Where. L'assistant IA génère un graphique partiellement renseigné ; vous pouvez modifier manuellement chaque champ. Le sélecteur de schéma (bouton Schema à côté de la source de données) affiche chaque colonne et son type.
2. Fixez la période. L'assistant comprend « for the past N hours / today / yesterday », mais utilise par défaut le sélecteur de période du graphique si vous ne la précisez pas. Réglez explicitement la période dans le sélecteur avant l'enregistrement.
3. Les colonnes de type Map (LogAttributes, ResourceAttributes, SpanAttributes) posent souvent problème à l'assistant. S'il génère WHERE process = 'kernel' au lieu de WHERE LogAttributes['process'] = 'kernel', corrigez l'expression en mode SQL.
4. Enregistrez la version opérationnelle après avoir renseigné Chart Name, puis ajoutez les graphiques à un tableau de bord HyperDX pour obtenir une vue sur une seule page qui reproduit le tableau de bord Kibana d'origine.

---

Et ensuite ?

• Service Map (barre latérale, version bêta) — représente le graphe des appels entre microservices d'OTel Demo à partir d'otel_traces. Aucune configuration supplémentaire n'est nécessaire après la création de la source Traces.
• Alerts — définissez des alertes sur toute recherche enregistrée ou tout graphique. Vous les utiliserez à l'étape 8 du README principal ; consultez README.md § Étape 8 Option A pour les deux alertes recommandées (web-5xx-errors, battement de cœur du service).
• Notebooks (aperçu) — combinez des graphiques, des requêtes et des commentaires Markdown pour créer des investigations partageables.

Une fois l'exploration terminée, revenez à l'étape 6 de README.md pour vérifier la configuration du TTL.

---

Résolution des problèmes

La liste des sources est vide après l'enregistrement. HyperDX met en cache les définitions des sources pour chaque session du navigateur. Forcez le rechargement de l'onglet (Cmd-Maj-R / Ctrl-Maj-R). Si la liste reste vide, vérifiez Team Settings → Data → Server Connection : la valeur doit être Default et désigner le même service CH Cloud.

Search n'affiche aucune ligne, mais validate_migration.sh en signale des milliers.

• Vérifiez le sélecteur de période ; la valeur par défaut est « Last 15 minutes ». Passez à « Last 24 hours » si votre collecteur a démarré récemment.
• Vérifiez que le Default Select de la source utilise TimestampTime (et non Timestamp). Symptôme : l'histogramme s'affiche, mais la table indique « no rows ».
• Vérifiez que la valeur Database de la source est otel (et non default).

L'assistant IA répond « I couldn't translate that. » L'assistant est limité au schéma de la source sélectionnée. Solutions courantes :

• Changez de source de données : les questions portant sur des traces (« latence p95 ») nécessitent la source Traces, et non log.
• Précisez le champ : count by ServiceName fonctionne mieux que count by service.