Moteur de table FileLog

Ce moteur permet de traiter les fichiers de log d’application comme un flux d’enregistrements.

Ce moteur permet de traiter les fichiers de log d’application comme un flux d’enregistrements.

FileLog vous permet de :

• Vous abonner à des fichiers de log.
• Traiter les nouveaux enregistrements à mesure qu’ils sont ajoutés aux fichiers de log suivis.

​

Créer une table

CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2],
    ...
) ENGINE = FileLog('path_to_logs', 'format_name') SETTINGS
    [poll_timeout_ms = 0,]
    [poll_max_batch_size = 0,]
    [max_block_size = 0,]
    [max_threads = 0,]
    [poll_directory_watch_events_backoff_init = 500,]
    [poll_directory_watch_events_backoff_max = 32000,]
    [poll_directory_watch_events_backoff_factor = 2,]
    [handle_error_mode = 'default']

Arguments du moteur :

• path_to_logs – Chemin des fichiers de log à suivre. Il peut s’agir du chemin vers un répertoire contenant des fichiers de log ou vers un seul fichier de log. Notez que ClickHouse n’autorise que les chemins situés dans le répertoire user_files.
• format_name - Format de l’enregistrement. Notez que FileLog traite chaque ligne d’un fichier comme un enregistrement distinct et que tous les formats de données ne s’y prêtent pas.

Paramètres facultatifs :

• poll_timeout_ms - Délai d’expiration d’une opération de poll unique sur le fichier de log. Par défaut : stream_poll_timeout_ms.
• poll_max_batch_size — Nombre maximal d’enregistrements récupérés lors d’une seule opération de poll. Par défaut : max_block_size.
• max_block_size — Taille maximale du lot (en enregistrements) pour le poll. Par défaut : max_insert_block_size.
• max_threads - Nombre maximal de threads pour analyser les fichiers. La valeur par défaut est 0, ce qui signifie que ce nombre sera égal à max(1, physical_cpu_cores / 4).
• poll_directory_watch_events_backoff_init - Temporisation initiale du thread de surveillance du répertoire. Par défaut : 500.
• poll_directory_watch_events_backoff_max - Temporisation maximale du thread de surveillance du répertoire. Par défaut : 32000.
• poll_directory_watch_events_backoff_factor - Vitesse du backoff, exponentielle par défaut. Par défaut : 2.
• handle_error_mode — Mode de gestion des erreurs du moteur FileLog. Valeurs possibles : default (une exception sera levée si l’analyse d’un message échoue), stream (le message d’exception et le message brut seront enregistrés dans les colonnes virtuelles _error et _raw_message).

​

Description

Les enregistrements reçus sont suivis automatiquement, de sorte que chaque enregistrement d’un fichier de log n’est compté qu’une seule fois.

SELECT n’est pas particulièrement utile pour lire des enregistrements (sauf pour le débogage), car chaque enregistrement ne peut être lu qu’une seule fois. Il est plus pratique de créer des flux en temps réel à l’aide de vues matérialisées. Pour ce faire :

1. Utilisez le moteur pour créer une table FileLog et considérez-la comme un flux de données.
2. Créez une table avec la structure souhaitée.
3. Créez une vue matérialisée qui convertit les données du moteur et les insère dans une table créée précédemment.

Lorsqu’une MATERIALIZED VIEW est associée au moteur, elle commence à collecter des données en arrière-plan. Cela vous permet de recevoir en continu des enregistrements depuis des fichiers de log et de les convertir au format requis à l’aide de SELECT. Une table FileLog peut avoir autant de vues matérialisées que vous le souhaitez ; elles ne lisent pas les données directement depuis la table, mais reçoivent les nouveaux enregistrements (par blocs). Vous pouvez ainsi écrire dans plusieurs tables avec différents niveaux de détail (avec regroupement et agrégation, ou sans).

Exemple :

CREATE TABLE logs (
    timestamp UInt64,
    level String,
    message String
  ) ENGINE = FileLog('user_files/my_app/app.log', 'JSONEachRow');

CREATE TABLE daily (
    day Date,
    level String,
    total UInt64
  ) ENGINE = SummingMergeTree
  PARTITION BY toYYYYMM(day)
  ORDER BY (day, level);

CREATE MATERIALIZED VIEW consumer TO daily
    AS SELECT toDate(toDateTime(timestamp)) AS day, level, count() AS total
    FROM logs GROUP BY day, level;

SELECT level, sum(total) FROM daily GROUP BY level;

Pour ne plus recevoir les données des flux ou pour modifier la logique de conversion, détachez la vue matérialisée :

DETACH TABLE consumer;
ATTACH TABLE consumer;

Si vous souhaitez modifier la table cible à l’aide de ALTER, nous vous recommandons de désactiver la vue matérialisée afin d’éviter toute incohérence entre la table cible et les données de la vue.

​

Colonnes virtuelles

• _filename - Nom du fichier de log. Type de données : LowCardinality(String).
• _offset - Décalage dans le fichier de log. Type de données : UInt64.

Colonnes virtuelles supplémentaires lorsque handle_error_mode='stream' :

• _raw_record - Enregistrement brut qui n’a pas pu être analysé correctement. Type de données : Nullable(String).
• _error - Message d’exception survenu lors d’une erreur d’analyse. Type de données : Nullable(String).

Remarque : les colonnes virtuelles _raw_record et _error ne sont renseignées qu’en cas d’exception lors de l’analyse ; elles sont toujours NULL lorsque le message a été analysé avec succès.

​

Durabilité des données

Le moteur FileLog enregistre le décalage consommé pour un fragment avant que l’insertion à laquelle appartient ce fragment soit validée. Ainsi, en cas d’interruption du serveur, le décalage enregistré peut être en avance sur les données ayant atteint la table cible. Au redémarrage, chaque fichier de log reprend au décalage enregistré dans son répertoire de métadonnées, de sorte que ces lignes ne sont jamais relues : elles sont perdues sans qu’aucune erreur ne soit signalée et count() est simplement inférieur. Une défaillance de processus ordinaire suffit à provoquer ce problème, sans nécessiter de coupure d’alimentation, car le décalage est enregistré dans un fichier de métadonnées renommé à son emplacement définitif alors que la partie cible est encore en cours d’écriture.

La perte du cache de pages de l’OS peut également entraîner la perte de données déjà écrites dans la table cible, par exemple lors d’une coupure d’alimentation au niveau du périphérique ou d’une réinitialisation non propre de l’hôte ou du kernel. Les fichiers de métadonnées contenant les décalages sont eux-mêmes écrits sans fsync du fichier ni de son répertoire ; ils n’offrent donc aucune garantie de durabilité propre.

Contrairement aux moteurs de courtiers de messages, FileLog ne peut pas être protégé contre ce problème en rendant d’abord la cible durable. Comme le décalage est enregistré au sein du pipeline de lecture, avant la fin de l’insertion à laquelle il appartient, définir fsync_after_insert = 1 sur les tables MergeTree cibles ne garantit pas la durabilité de la partie insérée avant l’avancement du décalage. Considérez la consommation de FileLog comme un suivi au mieux des fichiers locaux : lorsqu’aucune ligne ne doit être perdue, conservez les fichiers de log source jusqu’à ce que les données consommées aient été vérifiées dans la cible, afin de pouvoir répéter la consommation. La suppression puis la recréation de la table effacent les décalages enregistrés et relisent les fichiers depuis le début.