Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Ingestion avec Vector

View as MarkdownEdit this pageReport an issueSet up docs MCP

Vector est un pipeline de données d’observabilité hautes performances, indépendant des fournisseurs. Il est couramment utilisé pour collecter, transformer et acheminer des logs et des métriques provenant d’un large éventail de sources, et il est particulièrement apprécié pour l’ingestion de logs grâce à sa flexibilité et à sa faible consommation de ressources.

Lorsqu’ils utilisent Vector avec ClickStack, les utilisateurs doivent définir leurs propres schémas. Ces schémas peuvent suivre les conventions OpenTelemetry, mais ils peuvent aussi être entièrement personnalisés et représenter des structures d’événements définies par l’utilisateur. En pratique, l’ingestion via Vector est surtout utilisée pour les logs, lorsque les utilisateurs veulent garder un contrôle total sur l’analyse et l’enrichissement avant l’écriture des données dans ClickHouse.

Ce guide explique comment ingérer des données dans ClickStack à l’aide de Vector, aussi bien pour ClickStack Open Source que pour Managed ClickStack. Par souci de simplicité, il ne couvre pas en détail les sources Vector ni la configuration du pipeline. Il se concentre plutôt sur la configuration du sink qui écrit les données dans ClickHouse, et sur la compatibilité du schéma résultant avec ClickStack.

La seule exigence stricte de ClickStack, qu’il s’agisse d’un déploiement open-source ou Managed, est que les données incluent une colonne timestamp (ou un champ temporel équivalent), qui peut être déclarée lors de la configuration de la source de données dans la ClickStack UI.

Envoyer des données avec Vector


Le guide suivant suppose que vous avez déjà créé un service Managed ClickStack et enregistré vos identifiants de service. Si ce n'est pas le cas, suivez le guide Getting Started pour Managed ClickStack jusqu'à l'étape de configuration de Vector.

Créer une base de données et une table

Vector nécessite qu’une table et un schéma soient définis avant toute ingestion de données.

Commencez par créer une base de données. Cela peut se faire dans la ClickHouse Cloud console.

Dans l’exemple ci-dessous, nous utilisons logs :

CREATE DATABASE IF NOT EXISTS logs

Créez une table pour vos données. Celle-ci doit correspondre au schéma de sortie de vos données. L’exemple ci-dessous repose sur une structure Nginx classique. Adaptez-la à vos données, en respectant les bonnes pratiques relatives aux schémas. Nous vous recommandons vivement de vous familiariser avec le concept des clés primaires, en choisissant votre clé primaire selon les recommandations décrites ici.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Ajouter le sink ClickHouse à la configuration Vector

Modifiez votre configuration Vector pour y inclure le sink ClickHouse, en mettant à jour le champ inputs pour recevoir les événements de vos pipelines existants.

Cette configuration suppose que votre pipeline Vector en amont a déjà préparé les données pour qu'elles correspondent au schéma ClickHouse cible : les champs sont correctement analysés, nommés et typés pour l'insertion. Consultez l'exemple Nginx ci-dessous pour une illustration complète de l'analyse et de la normalisation de lignes de logs brutes en un schéma adapté à ClickStack.

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

Par défaut, nous recommandons d’utiliser le format json_each_row, qui encode chaque événement sous la forme d’un objet JSON unique par ligne. Il s’agit du format par défaut et recommandé pour ClickStack lors de l’ingestion de données JSON, et il est préférable aux autres formats, comme les objets JSON encodés sous forme de chaînes.

Le sink ClickHouse prend également en charge l’encodage Arrow en flux (actuellement en bêta). Cela peut offrir un débit plus élevé, mais s’accompagne de contraintes importantes : la base de données et la table doivent être statiques, car le schéma n’est récupéré qu’une seule fois au démarrage, et le routage dynamique n’est pas pris en charge. Pour cette raison, l’encodage Arrow convient particulièrement aux pipelines d’ingestion fixes et bien définis.

Nous vous recommandons de consulter les options de configuration disponibles pour le sink dans la documentation Vector :

Créer une source de données

Créez une source de données pour les logs. Si aucune source de données n’existe, il vous sera demandé d’en créer une lors de votre première connexion. Sinon, accédez à Team Settings et ajoutez une nouvelle source de données.

Créer une source de données - vector

La configuration ci-dessus suppose un schéma de type Nginx, avec une colonne time_local utilisée comme horodatage. Il doit s’agir, dans la mesure du possible, de la colonne d’horodatage déclarée dans la clé primaire. Cette colonne est obligatoire.

Nous vous recommandons également de mettre à jour Default SELECT afin de définir explicitement les colonnes renvoyées dans la vue des logs. Si des champs supplémentaires sont disponibles, comme le nom du service, le niveau de log ou une colonne body, ils peuvent également être configurés. La colonne d’affichage de l’horodatage peut aussi être redéfinie si elle diffère de la colonne utilisée dans la clé primaire de la table et configurée ci-dessus.

Dans l’exemple ci-dessus, il n’existe pas de colonne Body dans les données. Elle est définie à la place à l’aide d’une expression SQL qui reconstitue une ligne de log Nginx à partir des champs disponibles.

Pour les autres options possibles, consultez la référence de configuration.

Explorer les données

Accédez à la vue des logs pour explorer les données et commencer à utiliser ClickStack.

Logs Nginx dans CLickStack

Jeu de données d’exemple avec Vector

Pour un exemple plus complet, nous utilisons ci-dessous un fichier journal de Nginx.

Le guide suivant suppose que vous avez déjà créé un service Managed ClickStack et noté vos identifiants de service. Si ce n'est pas le cas, suivez le guide Getting Started pour Managed ClickStack jusqu'à l'invite de configuration de Vector.

Installation de Vector

Avant de continuer, assurez-vous que Vector est installé sur le système sur lequel vous prévoyez d’exécuter votre pipeline d’ingestion. Suivez le guide officiel d’installation de Vector pour installer un binaire précompilé ou un paquet adapté à votre environnement :

Une fois l’installation terminée, vérifiez que le binaire vector est disponible dans votre PATH avant de poursuivre avec les étapes de configuration ci-dessous.

Vector peut être installé sur la même instance que votre ClickStack OTel collector.

Suivez les bonnes pratiques en matière d’architecture et de sécurité lorsque vous faites passer Vector en production.

Téléchargez les données d’exemple

Si vous souhaitez faire des essais avec un jeu de données d’exemple, téléchargez l’exemple nginx ci-dessous.

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

Créer une base de données et une table

Vector nécessite qu'une table et un schéma soient définis avant toute ingestion de données.

Créez d'abord une base de données. Vous pouvez le faire depuis la ClickHouse Cloud console.

Créez une base de données logs :

CREATE DATABASE IF NOT EXISTS logs

Créez une table pour vos données.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Copier la configuration Vector

Copiez la configuration Vector et créez un fichier nginx.yaml en renseignant CLICKHOUSE_ENDPOINT et CLICKHOUSE_PASSWORD.

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

Démarrer Vector

Démarrez Vector avec la commande suivante, en créant d’abord le répertoire de données afin d’enregistrer les offsets de fichier.

mkdir ./.vector-data
vector --config nginx.yaml

Créer une source de données

Créez une source de données de logs. S’il n’existe encore aucune source de données, il vous sera demandé d’en créer une lors de votre première connexion. Sinon, accédez à Team Settings et ajoutez une nouvelle source de données.

Créer une source de données - vector

La configuration repose sur le schéma Nginx, avec une colonne time_local utilisée comme horodatage. Il s’agit de la colonne d’horodatage déclarée dans la clé primaire. Cette colonne est obligatoire.

Nous avons également défini la sélection par défaut sur time_local, remote_addr, status, request, ce qui détermine les colonnes renvoyées dans la vue des logs.

Dans l’exemple ci-dessus, il n’y a pas de colonne Body dans les données. À la place, elle est définie comme l’expression SQL :

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

Cela reconstitue la ligne de journal à partir des champs structurés.

Pour les autres options disponibles, consultez la référence de configuration.

Explorer les données

Accédez à la vue Search pour October 20th, 2025 afin d’explorer les données et de commencer à utiliser ClickStack.

HyperDX UI
Navigation