Quickwit logs et search : alternative Elasticsearch — tutoriel 2026

Introduction

Imaginez votre application Node.js déployée sur un VPS Hetzner à Dakar ou Abidjan : elle génère chaque jour 500 Mo de logs applicatifs, d’erreurs et d’événements d’accès. Pendant des mois, vous vous en sortez avec un simple grep et journalctl. Puis le premier incident de production arrive à 3 h du matin, et retrouver la trace d’une erreur dans des gigaoctets de logs dispersés sur cinq serveurs devient un cauchemar de plusieurs heures. C’est exactement la situation que Quickwit résout — proprement, économiquement, sans vous forcer à maintenir un cluster Elasticsearch à plusieurs nœuds.

Quickwit est un moteur de recherche open source écrit intégralement en Rust, lancé par la société française éponyme et disponible sur quickwit.io. Son architecture est fondamentalement différente d’Elasticsearch : au lieu de stocker les index sur des disques locaux coûteux, Quickwit découple le calcul du stockage et écrit tous ses index sur du stockage objet compatible S3 — MinIO, AWS S3, Google Cloud Storage, ou le stockage objet Hetzner. Cette approche, appelée disaggregated storage, permet de conserver des téraoctets de logs à un coût marginal, tout en maintenant des temps de recherche en dessous de la seconde sur des volumes que peu de solutions open source peuvent atteindre à ce prix.

En pratique, pour une PME ouest-africaine qui cherche à centraliser ses logs, Quickwit sur un VPS Hetzner CX21 (5 EUR/mois) couplé à 1 To de stockage objet Hetzner (environ 5 EUR/mois) offre une alternative crédible à Elastic Cloud, dont l’abonnement de base pour un usage sérieux dépasse facilement 100 EUR/mois. Ce tutoriel vous guide pas à pas : déploiement Docker, création d’index, ingestion via OpenTelemetry Collector ou Vector, recherche full-text avec agrégations, connexion à Grafana, et politique de rétention automatique.

Prérequis

• Docker Engine 24+ et Docker Compose v2 installés sur votre serveur (Ubuntu 22.04 LTS recommandé)
• MinIO ou un bucket S3 compatible accessible en réseau local (ou Hetzner Object Storage)
• RAM minimum : 2 Go (4 Go recommandés pour la production)
• Disk local : 10 Go pour le cache d’index temporaire
• Connaissance de base de la ligne de commande Linux et de Docker
• Temps estimé : 30 minutes pour la mise en route complète

Étape 1 — Quickwit vs Elasticsearch vs Loki : choisir le bon outil

Avant de déployer quoi que ce soit, il est important de comprendre pourquoi Quickwit existe et dans quels cas il l’emporte sur ses concurrents. Elasticsearch est le standard de facto depuis 2010 : il est puissant, mature, doté d’un riche écosystème Kibana, et capable de faire à la fois de la recherche full-text sur documents JSON et de l’analyse de logs. Mais cette polyvalence a un prix : Elasticsearch est gourmand en RAM (minimum 4 Go par nœud en production), exige des disques SSD rapides pour ses index sur disque local, et son clustering natif est complexe à opérer. Loki, créé par Grafana Labs, prend l’approche inverse : il n’indexe que les labels (pas le contenu des logs) et stocke les logs en texte brut compressé sur objet storage — ce qui le rend très économique mais aussi très limité pour les recherches full-text complexes.

Quickwit occupe un espace intermédiaire stratégique. Il indexe intégralement le contenu des champs JSON (comme Elasticsearch) mais stocke ses index sur S3/MinIO (comme Loki). Le tableau suivant résume les différences clés :

La latence d’ingestion de Quickwit mérite une explication : Quickwit regroupe les documents ingérés dans des splits (segments d’index immutables) avant de les écrire sur S3. Ce processus prend entre 10 et 60 secondes selon la configuration. Cela signifie que Quickwit n’est pas adapté au monitoring temps-réel strict (tableau de bord qui rafraîchit toutes les secondes) mais est parfaitement adapté à l’analyse de logs avec une granularité de quelques minutes — ce qui couvre 95 % des cas d’usage réels des PME.

Étape 2 — Déployer Quickwit avec Docker Compose

Le déploiement le plus simple et le plus reproductible passe par Docker Compose. Quickwit fournit une image officielle sur Docker Hub sous le nom quickwit/quickwit. Nous allons créer une stack complète comprenant Quickwit, MinIO comme stockage objet local, et les volumes nécessaires. Cette configuration est pensée pour un environnement de développement ou une petite production mono-nœud — exactement ce qu’il faut pour commencer.

Créez un répertoire de travail et placez-y un fichier docker-compose.yml :

version: "3.8"

services:
  minio:
    image: minio/minio:RELEASE.2024-04-18T19-09-19Z
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 10s
      timeout: 5s
      retries: 5

  quickwit:
    image: quickwit/quickwit:0.8.1
    command: run
    environment:
      QW_ENABLE_OPENTELEMETRY_OTLP_EXPORTER: "true"
      QW_METASTORE_URI: s3://quickwit-indexes
      AWS_ACCESS_KEY_ID: minioadmin
      AWS_SECRET_ACCESS_KEY: minioadmin
      AWS_DEFAULT_REGION: us-east-1
      S3_ENDPOINT: http://minio:9000
    volumes:
      - ./quickwit.yaml:/quickwit/config/quickwit.yaml:ro
      - qw_cache:/quickwit/qwdata
    ports:
      - "7280:7280"
    depends_on:
      minio:
        condition: service_healthy

volumes:
  minio_data:
  qw_cache:

Ce fichier Compose définit deux services interdépendants. MinIO démarre en premier grâce à la condition service_healthy — Quickwit ne démarrera qu’une fois MinIO prêt à répondre. La variable S3_ENDPOINT redirige toutes les opérations S3 de Quickwit vers MinIO local plutôt que vers AWS, ce qui est la clé du fonctionnement en environnement auto-hébergé. Le port 7280 expose l’interface REST et l’UI web de Quickwit.

Avant de lancer la stack, créez le bucket MinIO qui accueillera les index. Vous pouvez le faire via l’interface web MinIO sur http://localhost:9001 (login : minioadmin / minioadmin) en créant un bucket nommé quickwit-indexes, ou via la CLI mc :

docker run --rm --network host minio/mc:latest \
  alias set local http://localhost:9000 minioadmin minioadmin
docker run --rm --network host minio/mc:latest \
  mb local/quickwit-indexes

Maintenant créez le fichier de configuration quickwit.yaml minimal :

version: 0.8
cluster_id: my-cluster
node_id: node-1
indexer:
  split_store_max_num_bytes: 1073741824  # 1 Go de cache local
storage:
  s3:
    endpoint: http://minio:9000
    force_path_style_access: true

Lancez la stack avec docker compose up -d et attendez 15 à 20 secondes. Vérifiez que Quickwit est opérationnel en ouvrant http://localhost:7280 dans votre navigateur — vous devriez voir l’interface web avec un tableau de bord vide. L’API REST répond sur http://localhost:7280/api/v1/version et retourne la version de Quickwit en JSON.

Étape 3 — Créer un index logs avec mapping

Un index Quickwit est défini par un fichier de configuration JSON ou YAML qui décrit le mapping des champs — c’est-à-dire comment Quickwit doit interpréter et indexer chaque champ de vos documents. Ce concept est proche du mapping Elasticsearch, mais plus orienté logs : Quickwit distingue les champs fast fields (pour les agrégations et le tri, stockés en colonne) des champs full-text (pour la recherche textuelle, indexés en inverted index) et des champs stored (retournés dans les résultats mais non indexés).

Voici un mapping adapté aux logs applicatifs standard au format JSON :

{
  "version": "0.8",
  "index_id": "app-logs",
  "doc_mapping": {
    "mode": "lenient",
    "timestamp_field": "timestamp",
    "field_mappings": [
      { "name": "timestamp", "type": "datetime",
        "input_formats": ["rfc3339", "unix_timestamp"],
        "fast": true },
      { "name": "level", "type": "text",
        "tokenizer": "raw", "fast": true },
      { "name": "service", "type": "text",
        "tokenizer": "raw", "fast": true },
      { "name": "message", "type": "text",
        "tokenizer": "default", "record": "position" },
      { "name": "host", "type": "text",
        "tokenizer": "raw", "fast": true },
      { "name": "status_code", "type": "u64", "fast": true },
      { "name": "duration_ms", "type": "f64", "fast": true }
    ]
  },
  "indexing_settings": {
    "commit_timeout_secs": 30
  },
  "search_settings": {
    "default_search_fields": ["message", "service"]
  },
  "retention": {
    "period": "30 days",
    "schedule": "@daily"
  }
}

Quelques points importants sur ce mapping : le champ timestamp est déclaré comme datetime fast — c’est le champ de partitionnement temporel que Quickwit utilise pour organiser ses splits, ce qui rend les requêtes avec filtres de date extrêmement rapides. Les champs de filtrage fréquent comme level, service, et host sont marqués fast: true pour activer le stockage en colonne. Le champ message utilise record: "position" qui active la tokenisation avec mémorisation de la position pour permettre la recherche par phrase exacte.

Créez l’index via l’API REST :

curl -X POST http://localhost:7280/api/v1/indexes \
  -H 'Content-Type: application/json' \
  -d @index-config.json

L’API retourne un objet JSON confirmant la création avec les métadonnées de l’index. Vous pouvez aussi vérifier l’index dans l’UI web sous l’onglet « Indexes ». À ce stade, l’index est vide mais prêt à recevoir des documents.

Étape 4 — Ingestion via OpenTelemetry Collector ou Vector

Quickwit supporte deux méthodes d’ingestion principales : l’API bulk REST directe (compatible avec l’API Elasticsearch _bulk pour la migration) et le protocole OpenTelemetry (OTLP gRPC et HTTP). Pour les nouveaux déploiements, Vector est souvent le choix le plus flexible : c’est un pipeline de données open source écrit lui aussi en Rust, capable de lire des logs depuis des dizaines de sources (fichiers, journald, Docker, Kafka) et de les envoyer vers Quickwit.

Voici une configuration Vector pour collecter les logs Docker et les envoyer vers Quickwit :

[sources.docker_logs]
type = "docker_logs"
include_containers = []
exclude_containers = ["vector"]

[transforms.parse_logs]
type = "remap"
inputs = ["docker_logs"]
source = '''
  .timestamp = now()
  .service = .container_name
  .host = get_hostname!() 
  .message = string!(.message)
  .level = if match(string!(.message), r'(?i)(error|fatal)') { "ERROR" }
    else if match(string!(.message), r'(?i)warn') { "WARN" }
    else { "INFO" }
'''

[sinks.quickwit]
type = "elasticsearch"
inputs = ["parse_logs"]
endpoint = "http://quickwit:7280/api/v1"
index = "app-logs"
bulk.action = "index"
batch.max_events = 1000
batch.timeout_secs = 10

Notez que Vector utilise le sink elasticsearch pour envoyer vers Quickwit : c’est possible car Quickwit implémente l’API d’ingestion Elasticsearch _bulk, ce qui simplifie considérablement la migration depuis un stack ELK existant. La transformation VRL (Vector Remap Language) enrichit les logs avec un timestamp normalisé, le nom du service extrait du nom du container, et un niveau de log déduit par expression régulière sur le message.

Pour une ingestion via OpenTelemetry Collector (recommandé si vous utilisez déjà OTel dans votre application), configurez l’exporteur OTLP HTTP vers Quickwit :

exporters:
  otlphttp/quickwit:
    endpoint: http://quickwit:7280
    logs_endpoint: http://quickwit:7280/api/v1/logs

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [otlphttp/quickwit]

Après quelques minutes d’ingestion, retournez sur l’UI Quickwit — l’onglet « Indexes » doit afficher le nombre de documents indexés et la taille sur disque (dans MinIO). La première fois, attendez au moins 30 secondes après le démarrage de l’ingestion pour voir les premiers documents apparaître, le temps que le premier split soit committés sur S3.

Étape 5 — Recherche full-text avec agrégations

L’API de recherche Quickwit expose un endpoint REST GET /api/v1/{index_id}/search qui accepte une syntaxe de requête proche de Lucene. C’est la même syntaxe qu’Elasticsearch pour les requêtes simples, ce qui facilite la transition. Mais Quickwit offre aussi une API SQL via /api/v1/{index_id}/search/stream pour les cas d’usage analytiques — une fonctionnalité qu’Elasticsearch ne propose pas nativement sans X-Pack.

Voici quelques exemples de requêtes REST curl pour explorer vos logs :

# Recherche full-text sur le champ message
curl 'http://localhost:7280/api/v1/app-logs/search?query=connection+refused&max_hits=10'

# Filtrer par niveau ERROR sur les dernières 24h
curl 'http://localhost:7280/api/v1/app-logs/search?query=level:ERROR&start_timestamp=1714038000&end_timestamp=1714124400&max_hits=50'

# Aggrégation : compter les erreurs par service
curl -X POST 'http://localhost:7280/api/v1/app-logs/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "level:ERROR",
    "max_hits": 0,
    "aggs": {
      "errors_by_service": {
        "terms": { "field": "service", "size": 10 }
      }
    }
  }'

# Histogramme temporel : erreurs par heure
curl -X POST 'http://localhost:7280/api/v1/app-logs/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "level:ERROR",
    "max_hits": 0,
    "aggs": {
      "errors_over_time": {
        "date_histogram": {
          "field": "timestamp",
          "fixed_interval": "3600s"
        }
      }
    }
  }'

Les agrégations Quickwit couvrent les cas d’usage les plus fréquents : terms, date_histogram, histogram, range, stats (min, max, avg, sum, count), et leurs combinaisons imbriquées. Ce sous-ensemble représente environ 80 % des agrégations utilisées en pratique dans les dashboards de monitoring. Pour des analyses très complexes nécessitant des agrégations imbriquées à plusieurs niveaux ou des pipeline aggregations, Elasticsearch reste plus complet — mais pour 80 % des cas, Quickwit est amplement suffisant.

Étape 6 — Connecter Grafana datasource Quickwit

Grafana est le standard de visualisation pour les stacks de monitoring self-hosted. Quickwit fournit un plugin datasource officiel pour Grafana qui permet d’interroger les index Quickwit directement depuis les dashboards Grafana, avec une interface similaire à celle du datasource Loki ou Elasticsearch. Le plugin est disponible sur github.com/quickwit-oss/grafana-quickwit-datasource.

Ajoutez Grafana à votre stack Docker Compose en ajoutant ce service :

  grafana:
    image: grafana/grafana:10.4.2
    environment:
      GF_INSTALL_PLUGINS: quickwit-quickwit-datasource
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3000:3000"
    depends_on:
      - quickwit

La variable GF_INSTALL_PLUGINS installe automatiquement le plugin Quickwit au démarrage du container Grafana. Après le démarrage, accédez à Grafana sur http://localhost:3000 (login admin/admin par défaut). Dans Configuration → Data Sources → Add data source, recherchez « Quickwit » et configurez l’URL vers http://quickwit:7280 en laissant les autres paramètres par défaut. Cliquez sur Save & Test — Grafana doit confirmer la connexion en listant les index disponibles.

Une fois la datasource configurée, créez un nouveau dashboard et ajoutez un panneau. Sélectionnez la datasource Quickwit, choisissez l’index app-logs, et construisez votre requête via l’interface graphique ou en mode JSON direct. Le plugin supporte les visualisations de type logs (liste chronologique), time series (histogrammes), et table (résultats d’agrégations). Pour aller plus vite, cherchez les dashboards Quickwit préconstruits sur grafana.com/grafana/dashboards/ — plusieurs membres de la communauté ont partagé des dashboards prêts à l’emploi.

Étape 7 — Lifecycle policy et rétention automatique

L’un des avantages majeurs de Quickwit sur S3 est la facilité de gestion du cycle de vie des données. Puisque les index sont stockés comme des objets S3, vous pouvez combiner deux mécanismes de rétention : la politique de rétention Quickwit (qui supprime les splits anciens de l’index) et les règles de lifecycle S3 de MinIO (qui suppriment les objets non référencés).

La politique de rétention est déjà intégrée dans notre mapping d’index au bloc retention :

"retention": {
  "period": "30 days",
  "schedule": "@daily"
}

Cette configuration demande à Quickwit de supprimer chaque jour les splits dont le timestamp maximum est antérieur à 30 jours. Vous pouvez modifier la politique d’un index existant via l’API REST :

curl -X PUT http://localhost:7280/api/v1/indexes/app-logs \
  -H 'Content-Type: application/json' \
  -d '{"retention": {"period": "90 days", "schedule": "@weekly"}}'

Du côté MinIO, activez une règle de lifecycle sur le bucket pour supprimer automatiquement les objets non modifiés depuis plus de 100 jours (marge de sécurité au-dessus de la rétention Quickwit) :

docker run --rm --network host minio/mc:latest \
  ilm add --expiry-days 100 local/quickwit-indexes

Cette double protection garantit qu’aucun objet orphelin n’occupe de l’espace sur MinIO si un split n’est pas proprement nettoyé par Quickwit. En production, surveillez la taille du bucket MinIO via son API de métriques et configurez une alerte quand elle dépasse 80 % de votre quota.

Erreurs fréquentes

Adaptation au contexte ouest-africain

Pour les PME et startups tech en Afrique de l’Ouest, la question du coût d’infrastructure est centrale. Une stack ELK (Elasticsearch + Logstash + Kibana) hébergée sur Elastic Cloud coûte au minimum 95 USD/mois pour un cluster de production basique avec 30 jours de rétention. En comparaison, la même capacité avec Quickwit peut être déployée sur Hetzner pour environ 10 EUR/mois tout compris : un VPS CX21 (2 vCPU, 4 Go RAM) à 5 EUR/mois fait tourner Quickwit et Vector, et 1 To de stockage objet Hetzner (compatible S3) coûte environ 5 EUR/mois. Sur 12 mois, c’est une économie de plus de 1 000 EUR — soit le coût d’un développeur junior pendant plusieurs semaines.

La connectivité reste une contrainte réelle en Afrique de l’Ouest : les VPS Hetzner sont situés en Europe (Nuremberg, Falkenstein, Helsinki) et en Amérique du Nord. Pour les applications dont les serveurs sont en Europe, la latence est négligeable. Pour les applications hébergées en Afrique, l’ingestion de logs vers Hetzner sera légèrement différée — ce qui est parfaitement compatible avec le modèle de Quickwit qui accepte une latence d’indexation de 30 à 60 secondes par design. En pratique, les logs applicatifs ne nécessitent pas une consultation en temps réel : une latence de 2 à 5 minutes entre la génération d’une erreur et sa visibilité dans Grafana est tout à fait acceptable pour la grande majorité des cas d’alerte.

Pour les alertes, intégrez Grafana Alerting avec une notification sur Telegram — un canal de communication largement utilisé dans les équipes tech ouest-africaines. Créez un bot Telegram via @BotFather, récupérez votre token API et votre chat_id, puis configurez dans Grafana : Alerting → Contact Points → New Contact Point → Telegram. Définissez une alerte sur le seuil errors_by_service count > 10 in 5m et vous recevrez un message Telegram dès qu’un service génère un pic d’erreurs anormal, même si vous n’avez pas Grafana ouvert sur votre écran. C’est une solution de monitoring complète, fiable et économique, accessible même avec un budget startup limité.

Un dernier conseil pratique pour les contextes à coupures électriques fréquentes : configurez MinIO avec le mode de synchronisation forcée (MINIO_DISK_RECOVERY=true) et activez les snapshots de volume Docker vers un stockage externe quotidiennement. Quickwit étant stateless (toutes ses données sont sur S3/MinIO), un redémarrage après coupure ne nécessite aucune récupération manuelle — Quickwit rechargera automatiquement les métadonnées depuis le bucket MinIO au démarrage.

Tutoriels frères

• Typesense search self-hosted — tutoriel 2026 — déployer Typesense pour la recherche applicative temps réel, intégration JavaScript
• Manticore Search : alternative MySQL full-text — tutoriel 2026 — moteur de recherche compatible MySQL pour les applications PHP/Laravel

Pour aller plus loin

• Retour au pilier : Moteurs de recherche self-hosted 2026 : Typesense, Quickwit, Manticore
• Documentation officielle : quickwit.io/docs — référence complète de l’API, des mappings et de la configuration
• GitHub officiel : github.com/quickwit-oss/quickwit — issues, changelog, releases
• Tutoriel suivant recommandé : Manticore Search pour la recherche full-text dans vos applications PHP/MySQL

FAQ

Q : Quickwit peut-il remplacer Elasticsearch pour la recherche applicative (e-commerce, moteur de site) ?
R : Pas directement dans sa version actuelle. Quickwit est optimisé pour les logs et les données d’événements append-only (pas de mise à jour de documents). Pour la recherche applicative avec mise à jour fréquente des documents (catalogue produit, profils utilisateurs), Typesense ou Manticore Search sont plus adaptés. Quickwit lui-même recommande cet usage sur sa documentation officielle.

Q : Quelle est la différence entre un split et un index dans Quickwit ?
R : Un index est la structure logique de haut niveau — c’est ce que vous créez avec un mapping et ce que vous interrogez. Un split est un segment d’index immutable créé par Quickwit quand il comitte une tranche temporelle de données sur S3. Chaque split est un ensemble de fichiers dans le bucket MinIO. Un index contient typiquement des centaines ou des milliers de splits. Lors d’une recherche, Quickwit détermine quels splits sont susceptibles de contenir des résultats (via les métadonnées temporelles) et ne lit que ceux-là — c’est ce qui rend les recherches rapides même sur de gros volumes.

Q : Quickwit supporte-t-il les alertes nativement ou faut-il obligatoirement Grafana ?
R : Quickwit lui-même ne propose pas de système d’alertes natif dans sa version open source (v0.8). Pour les alertes, il faut passer par Grafana Alerting (recommandé), Prometheus AlertManager en combinaison avec les métriques Quickwit exposées en format Prometheus, ou une solution maison via polling de l’API REST Quickwit depuis un script qui déclenche une notification Telegram ou WhatsApp.

Q : Peut-on migrer depuis un cluster ELK existant vers Quickwit sans interruption ?
R : Oui, via l’API de compatibilité Elasticsearch que Quickwit expose. Vector et Logstash peuvent envoyer vers Quickwit en utilisant le sink Elasticsearch en changeant simplement l’endpoint. Pour les données historiques, Quickwit propose un outil de réindexation qui lit des dumps JSON Elasticsearch et les importe. La migration peut se faire en mode double-écriture pendant une période de transition sans aucune interruption de service.

Q : Quickwit fonctionne-t-il sans connexion à S3 (stockage local uniquement) ?
R : Depuis la version 0.7, Quickwit supporte un backend de stockage local (file://) pour les environnements de développement ou les déploiements sur serveur unique sans accès S3. En production, ce mode est déconseillé car il perd les avantages de coût et de durabilité du stockage objet, mais il est utile pour tester Quickwit sans déployer MinIO.

Q : Quelle est la limite de volume que Quickwit peut gérer sur un seul nœud ?
R : Quickwit en mode mono-nœud peut gérer plusieurs téraoctets de logs indexés (le stockage est illimité car sur S3). La limite pratique est le débit d’ingestion : un seul nœud avec 4 Go de RAM peut ingérer environ 10 000 à 50 000 documents par seconde selon leur taille. Pour des débits plus élevés, Quickwit supporte le clustering horizontal avec plusieurs nœuds indexeurs partageant le même backend S3 — la documentation officielle quickwit.io/docs/guides/cluster-setup détaille la configuration.

Site réalisé par ITS ITSkillsCenter — Formation et ressources tech pour l’Afrique de l’Ouest