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(day, (day, level), 8192);

  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.