supervision des logs MySQL avec ClickStack

En brefCollectez et visualisez les logs d’erreurs MySQL et les logs de requêtes lentes dans ClickStack à l’aide du receiver OTel filelog. Inclut un jeu de données de démonstration et un tableau de bord préconfiguré.

Intégration avec une instance MySQL existante

Cette section explique comment configurer votre instance MySQL existante afin d’envoyer les logs à ClickStack en modifiant la configuration du ClickStack OTel collector. Si vous souhaitez tester l’intégration des logs MySQL avant de configurer votre propre environnement, vous pouvez utiliser notre configuration préconfigurée et des données d’exemple dans la section “jeu de données de démonstration”.

Prérequis

Instance ClickStack en fonctionnement
Installation MySQL existante (version 5.7 ou ultérieure)
Accès aux fichiers de configuration de MySQL pour les modifier
Espace disque suffisant pour les fichiers journaux

Configurer la journalisation de MySQL

MySQL prend en charge plusieurs types de journaux. Pour une supervision complète avec OpenTelemetry, nous recommandons d’activer le journal des erreurs et le journal des requêtes lentes.Le fichier de configuration my.cnf ou my.ini se trouve généralement à l’un des emplacements suivants :

Linux (apt/yum) : /etc/mysql/my.cnf ou /etc/my.cnf
macOS (Homebrew) : /usr/local/etc/my.cnf ou /opt/homebrew/etc/my.cnf
Docker : la configuration est généralement définie via des variables d’environnement ou un fichier de configuration monté

Ajoutez ou modifiez ces paramètres dans la section [mysqld] :

[mysqld]
# Error log configuration
log_error = /var/log/mysql/error.log

# Slow query log configuration
slow_query_log = ON
slow_query_log_file = /var/log/mysql/mysql-slow.log
long_query_time = 1
log_queries_not_using_indexes = ON

# Optional: General query log (verbose, use with caution in production)
# general_log = ON
# general_log_file = /var/log/mysql/mysql-general.log

Le journal des requêtes lentes enregistre les requêtes qui prennent plus de long_query_time secondes. Ajustez ce seuil en fonction des exigences de performances de votre application. Si vous le définissez trop bas, cela générera un volume excessif de journaux.

Après avoir effectué ces modifications, redémarrez MySQL :

# For systemd
sudo systemctl restart mysql

# For Docker
docker restart <mysql-container>

Vérifiez que des logs sont bien générés :

# Check error log
tail -f /var/log/mysql/error.log

# Check slow query log
tail -f /var/log/mysql/mysql-slow.log

Créer une configuration personnalisée pour l’OTel collector

ClickStack vous permet d’étendre la configuration de base de l’OpenTelemetry Collector en montant un fichier de configuration personnalisé et en définissant une variable d’environnement. Cette configuration personnalisée est fusionnée avec la configuration de base gérée par HyperDX via OpAMP.Créez un fichier nommé mysql-logs-monitoring.yaml avec la configuration suivante :

receivers:
  filelog/mysql_error:
    include:
      - /var/log/mysql/error.log
    start_at: end
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^(?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}[+-]\d{2}:\d{2})\s+(?P<thread_id>\d+)\s+\[(?P<level>[^\]]+)\]\s+(\[(?P<error_code>[^\]]+)\]\s+)?(?P<message>.*)$'
        
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
        parse_to: body
      
      - type: add
        field: attributes.source
        value: "mysql-error"
      
      - type: add
        field: resource["service.name"]
        value: "mysql-production"

  filelog/mysql_slow:
    include:
      - /var/log/mysql/mysql-slow.log
    start_at: end
    multiline:
      line_start_pattern: '^# Time:'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^# Time: (?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\n# User@Host: (?P<user>[^\[]+)\[(?P<user_host>[^\]]*)\]\s+@\s+(?P<host>[^\[]*)\[(?P<ip>[^\]]*)\].*\n# Query_time: (?P<query_time>[\d.]+)\s+Lock_time: (?P<lock_time>[\d.]+)\s+Rows_sent: (?P<rows_sent>\d+)\s+Rows_examined: (?P<rows_examined>\d+)'
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999Z'
        parse_to: body
      
      - type: add
        field: attributes.source
        value: "mysql-slow"
      
      - type: add
        field: resource["service.name"]
        value: "mysql-production"

service:
  pipelines:
    logs/mysql:
      receivers: [filelog/mysql_error, filelog/mysql_slow]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

Cette configuration :

Lit les logs d’erreurs MySQL et les logs de requêtes lentes depuis leurs emplacements standard
Gère les entrées de log sur plusieurs lignes (les requêtes lentes s’étendent sur plusieurs lignes)
Analyse les deux formats de log pour extraire des champs structurés (level, error_code, query_time, rows_examined)
Préserve les horodatages d’origine des logs
Ajoute les attributs source: mysql-error et source: mysql-slow pour le filtrage dans HyperDX
Achemine les logs vers le ClickHouse exporter via un pipeline dédié

Deux receivers sont nécessaires, car les logs d’erreurs MySQL et les logs de requêtes lentes ont des formats complètement différents. Le time_parser utilise le format gotime pour gérer le format d’horodatage ISO8601 de MySQL avec des décalages de fuseau horaire.

Configurer ClickStack pour charger une configuration personnalisée

Pour activer une configuration personnalisée du collecteur dans votre déploiement ClickStack existant, montez le fichier de configuration personnalisé à l’emplacement /etc/otelcol-contrib/custom.config.yaml et définissez la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml.Mettez à jour la configuration de déploiement de ClickStack :

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./mysql-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mysql:/var/log/mysql:ro
      # ... other volumes ...

Assurez-vous que le collecteur ClickStack dispose des permissions appropriées pour lire les fichiers de journal MySQL. Utilisez des montages en lecture seule (:ro) et appliquez le principe du moindre privilège.

Vérifier les logs dans HyperDX

Une fois la configuration terminée, connectez-vous à HyperDX et vérifiez que les logs remontent correctement :

Accédez à la vue Search
Définissez la source sur Logs
Filtrez sur source:mysql-error ou source:mysql-slow pour afficher les logs spécifiques à MySQL
Vous devriez voir des entrées de log structurées avec des champs tels que level, error_code, message (pour les logs d’erreur) ainsi que query_time, rows_examined, query (pour les logs de requêtes lentes)

Jeu de données de démonstration

Pour les utilisateurs qui souhaitent tester l’intégration MySQL logs avant de configurer leurs systèmes de production, nous fournissons un jeu de données d’exemple contenant des logs MySQL pré-générés aux schémas réalistes.

Téléchargez le jeu de données d’exemple

Téléchargez les exemples de fichiers journaux :

# Download error log
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/error.log

# Download slow query log
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/mysql-slow.log

Le jeu de données comprend :

Des entrées du journal des erreurs (messages de démarrage, avertissements, erreurs de connexion, messages InnoDB)
Des requêtes lentes avec des caractéristiques de performances réalistes
Des événements du cycle de vie des connexions
Des séquences de démarrage et d’arrêt du serveur de base de données

Créer une configuration de test du collecteur

Créez un fichier nommé mysql-logs-demo.yaml avec la configuration suivante :

cat > mysql-logs-demo.yaml << 'EOF'
receivers:
  filelog/mysql_error:
    include:
      - /tmp/mysql-demo/error.log
    start_at: beginning  # Read from beginning for demo data
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^(?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}[+-]\d{2}:\d{2})\s+(?P<thread_id>\d+)\s+\[(?P<level>[^\]]+)\]\s+(\[(?P<error_code>[^\]]+)\]\s+)?(?P<message>.*)$'
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
        parse_to: body
      - type: add
        field: attributes.source
        value: "mysql-demo-error"
      - type: add
        field: resource["service.name"]
        value: "mysql-demo"

  filelog/mysql_slow:
    include:
      - /tmp/mysql-demo/mysql-slow.log
    start_at: beginning  # Read from beginning for demo data
    multiline:
      line_start_pattern: '^# Time:'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^# Time: (?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\n# User@Host: (?P<user>[^\[]+)\[(?P<user_host>[^\]]*)\]\s+@\s+(?P<host>[^\[]*)\[(?P<ip>[^\]]*)\].*\n# Query_time: (?P<query_time>[\d.]+)\s+Lock_time: (?P<lock_time>[\d.]+)\s+Rows_sent: (?P<rows_sent>\d+)\s+Rows_examined: (?P<rows_examined>\d+)'
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999Z'
        parse_to: body
      - type: add
        field: attributes.source
        value: "mysql-demo-slow"
      - type: add
        field: resource["service.name"]
        value: "mysql-demo"

service:
  pipelines:
    logs/mysql-demo:
      receivers: [filelog/mysql_error, filelog/mysql_slow]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

Exécuter ClickStack avec la configuration de démonstration

Exécutez ClickStack avec les logs et la configuration de démonstration :

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/mysql-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/error.log:/tmp/mysql-demo/error.log:ro" \
  -v "$(pwd)/mysql-slow.log:/tmp/mysql-demo/mysql-slow.log:ro" \
  clickhouse/clickstack-all-in-one:latest

Vérifier les logs dans HyperDX

Une fois ClickStack démarré :

Attendez quelques instants que ClickStack soit complètement initialisé (généralement 30 à 60 secondes)
Ouvrez HyperDX et connectez-vous à votre compte (vous devrez peut-être d’abord en créer un)
Accédez à la vue Search et définissez la source sur Logs
Définissez l’intervalle de temps sur 2025-11-13 00:00:00 - 2025-11-16 00:00:00
Vous devriez voir 40 logs au total (30 logs d’erreur avec source:mysql-demo-error + 10 requêtes lentes avec source:mysql-demo-slow)

Si vous ne voyez pas immédiatement les 40 logs, attendez environ une minute pour que le collecteur termine le traitement. Si les logs n’apparaissent toujours pas après cela, exécutez docker restart clickstack-demo, puis vérifiez à nouveau une minute plus tard. Il s’agit d’un problème connu du récepteur filelog d’OpenTelemetry lors du chargement en masse de fichiers préexistants avec start_at: beginning. Les déploiements de production utilisant start_at: end traitent les logs à mesure qu’ils sont écrits en temps réel et ne rencontrent pas ce problème.

Affichage du fuseau horaireHyperDX affiche les timestamps dans le fuseau horaire local de votre navigateur. Les données de démonstration couvrent 2025-11-14 00:00:00 - 2025-11-15 00:00:00 (UTC). Cet intervalle de temps étendu vous permet de voir les logs de démonstration où que vous soyez. Une fois les logs visibles, vous pouvez réduire la plage à 24 heures pour obtenir des visualisations plus claires.

Tableaux de bord et visualisations

Pour vous aider à démarrer la supervision de MySQL avec ClickStack, nous fournissons des visualisations essentielles pour les logs MySQL.

la configuration du tableau de bord

Importer le tableau de bord préconfiguré

Ouvrez HyperDX et accédez à la section Dashboards
Cliquez sur Import Dashboard dans le coin supérieur droit, dans le menu des points de suspension

Téléversez le fichier mysql-logs-dashboard.json, puis cliquez sur Finish Import

Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations préconfigurées.

Pour le jeu de données de démonstration, définissez l’intervalle de temps sur 2025-11-14 00:00:00 - 2025-11-15 00:00:00 (UTC) (à ajuster selon votre fuseau horaire local). Par défaut, le tableau de bord importé n’aura pas d’intervalle de temps défini.

Dépannage

La config personnalisée ne se charge pas

Vérifiez que la variable d’environnement est définie :

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Vérifiez que le fichier de configuration personnalisé est bien monté et lisible :

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml | head -10

Aucun log ne s’affiche dans HyperDX

Vérifiez que la configuration effective inclut votre receiver filelog :

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Recherchez des erreurs dans les logs du collector :

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i mysql

Si vous utilisez le jeu de données de démonstration, vérifiez que les fichiers de logs sont accessibles :

docker exec <container> cat /tmp/mysql-demo/error.log | wc -l
docker exec <container> cat /tmp/mysql-demo/mysql-slow.log | wc -l

Les logs de requêtes lentes n’apparaissent pas

Vérifiez que le log de requêtes lentes est activé dans MySQL :

SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';

Vérifiez si MySQL enregistre les requêtes lentes :

tail -f /var/log/mysql/mysql-slow.log

Générez une requête lente de test :

SELECT SLEEP(2);

Les logs ne sont pas analysés correctement

Vérifiez que le format des logs MySQL correspond au format attendu. Les motifs d’expression régulière de ce guide sont conçus pour les formats par défaut de MySQL 5.7+ et 8.0+. Vérifiez quelques lignes de votre journal d’erreurs :

head -5 /var/log/mysql/error.log

Format attendu :

2025-11-14T10:23:45.123456+00:00 0 [System] [MY-010116] [Server] /usr/sbin/mysqld (mysqld 8.0.35) starting as process 1

Si votre format diffère sensiblement, ajustez les motifs d’expression régulière dans la configuration.

Étapes suivantes

Configurez des alertes pour les événements critiques (échecs de connexion, requêtes lentes dépassant les seuils, pics d’erreurs)
Créez des tableaux de bord personnalisés pour analyser les requêtes lentes par modèle de requête
Ajustez long_query_time en fonction des tendances de performances des requêtes observées

Passage en production

Ce guide s’appuie sur l’OpenTelemetry Collector intégré à ClickStack pour une mise en route rapide. Pour les déploiements en production, nous vous recommandons d’exécuter votre propre OTel Collector et d’envoyer les données vers l’endpoint OTLP de ClickStack. Consultez Envoi de données OpenTelemetry pour la configuration en production.

​Intégration avec une instance MySQL existante

Prérequis

​Configurer la journalisation de MySQL

​Créer une configuration personnalisée pour l’OTel collector

​Configurer ClickStack pour charger une configuration personnalisée

​Vérifier les logs dans HyperDX

​Jeu de données de démonstration

​Téléchargez le jeu de données d’exemple

​Créer une configuration de test du collecteur

​Exécuter ClickStack avec la configuration de démonstration

​Vérifier les logs dans HyperDX

​Tableaux de bord et visualisations

​ la configuration du tableau de bord

​Importer le tableau de bord préconfiguré

​Afficher le tableau de bord

​Dépannage

​La config personnalisée ne se charge pas

​Aucun log ne s’affiche dans HyperDX

​Les logs de requêtes lentes n’apparaissent pas

​Les logs ne sont pas analysés correctement

​Étapes suivantes

​Passage en production

Intégration avec une instance MySQL existante

Configurer la journalisation de MySQL

Créer une configuration personnalisée pour l’OTel collector

Configurer ClickStack pour charger une configuration personnalisée

Vérifier les logs dans HyperDX

Jeu de données de démonstration

Téléchargez le jeu de données d’exemple

Créer une configuration de test du collecteur

Exécuter ClickStack avec la configuration de démonstration

Vérifier les logs dans HyperDX

Tableaux de bord et visualisations

la configuration du tableau de bord

Importer le tableau de bord préconfiguré

Afficher le tableau de bord

Dépannage

La config personnalisée ne se charge pas

Aucun log ne s’affiche dans HyperDX

Les logs de requêtes lentes n’apparaissent pas

Les logs ne sont pas analysés correctement

Étapes suivantes

Passage en production