Aller au contenu principal

CLI Quickwit

Nous fournissons une CLI OpenSource1 nommée qwctl pour interagir avec Quickwit. Vous pouvez l'utiliser pour ingérer ou rechercher des documents, et aussi comme serveur MCP pour vos agents IA.

qwctl_1

Video demo​

Installation​

Choisissez le mode d'installation adapté à votre système d'exploitation, puis suivez les instructions.

Homebrew​

Première installation :

brew tap qwctl/qwctl https://gitlab.cwcloud.tech/oss/quickwit/homebrew-qwctl.git
brew install qwctl

Mise à jour :

brew update
brew upgrade qwctl

Curl​

Linux​

Linux x86 (64 bits)​
version="1.5.0"
curl -L "https://gitlab.cwcloud.tech/oss/quickwit/qwctl/-/releases/v${version}/downloads/quickwit/qwctl_${version}_linux_amd64.tar.gz" -o "qwctl_cli.tar.gz"
mkdir qwctl_cli && tar -xf qwctl_cli.tar.gz -C qwctl_cli 
sudo ./qwctl_cli/install.sh

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

Linux arm (64 bits)​
version="1.5.0"
curl -L "https://gitlab.cwcloud.tech/oss/quickwit/qwctl/-/releases/v${version}/downloads/quickwit/qwctl_${version}_linux_arm64.tar.gz" -o "qwctl_cli.tar.gz" 
mkdir qwctl_cli && tar -xf qwctl_cli.tar.gz -C qwctl_cli 
sudo ./qwctl_cli/install.sh

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

MacOS​

macOS x86/arm (64 bits)​
version="1.5.0"
curl -L "https://gitlab.cwcloud.tech/oss/quickwit/qwctl/-/releases/v${version}/downloads/quickwit/qwctl_${version}_darwin_all.tar.gz" -o "qwctl_cli.tar.gz"
mkdir qwctl_cli && tar -xf qwctl_cli.tar.gz -C qwctl_cli     
sudo ./qwctl_cli/install.sh

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

Windows​

Téléchargement direct​

Vous pouvez directement télécharger depuis ici. Choisissez la bonne architecture (amd64 ou arm64), téléchargez, décompressez et vous trouverez un fichier exe à l'intérieur.

Windows x86 (64 bits) avec Powershell​

$version = "1.5.0"
$user = "YOUR_USER"
cd "C:\Users\${user}"
Invoke-WebRequest -Uri "https://gitlab.cwcloud.tech/oss/quickwit/qwctl/-/releases/v${version}/downloads/quickwit/qwctl_${version}_windows_amd64.zip" -OutFile "qwctl_cli.zip"
Expand-Archive -Path "qwctl_cli.zip" -DestinationPath "qwctl_cli" -Force
Set-Location "qwctl_cli"
.\qwctl.exe

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

Windows arm (64 bits) avec Powershell​

$version = "1.5.0"
$user = "YOUR_USER"
cd "C:\Users\${user}"
Invoke-WebRequest -Uri "https://gitlab.cwcloud.tech/oss/quickwit/qwctl/-/releases/v${version}/downloads/qwctl_${version}_windows_arm64.zip" -OutFile "qwctl_cli.zip"
Expand-Archive -Path "qwctl_cli.zip" -DestinationPath "qwctl_cli" -Force
Set-Location "qwctl_cli"
.\qwctl.exe

Installation de quickwit avec la CLI​

qwctl bootstrap

Flags disponibles :

  • -r ou --release : Nom de release pour le déploiement (par défaut : qwctl)
  • -n ou --namespace : Namespace utilisé pour le déploiement (par défaut : qwctl)
  • -k ou --keep-dir : Conserver le répertoire helm local
  • -d ou --recreate-ns : Recréer le namespace
  • -o ou --openshift : Utiliser la CLI OpenShift au lieu de kubectl
  • -p ou --value : Valeurs pour surcharger la configuration (peut être répété)
  • --directory: Changer le répertoire (utile si vous souhaitez utiliser vos propres templates helm)
  • --kind-cluster : Spécifier le cluster kind à utiliser (il sera recréé même s'il existe déjà)

Exemple :

qwctl bootstrap -r my-release -n production --value key=value --value values-override.yaml

Ouvrir des tunnels​

qwctl bootstrap pfw

Ouvre des tunnels (ou port forward) vers les différents services. Vous pouvez surcharger la configuration comme ceci :

qwctl bootstrap pfw --config my-pfw-config.yml

Le format YAML de configuration attendu :

---
pfwConfigs:
  - name: "imalive-{{namespace}}"
    port: 8089
    targetPort: 8089
  - name: "quickwit-searcher"
    port: 7280
    targetPort: 7280
  - name: "{{namespace}}-grafana"
    port: 80
    targetPort: 8081
    secret:
      name: "{{namespace}}-grafana"
      user: "admin-user"
      password: "admin-password"

Configuration​

qwctl configure
qwctl configure set format pretty
qwctl configure set endpoint https://quickwit.changeit.org
qwctl configure set basic_auth_username <your user>
qwctl configure set basic_auth_password <your password>
qwctl configure set authorization_header_name Authorization
qwctl configure set authorization_header_value "Basic <your base64 encoded credentials>"

Remarque : il est aussi possible d'utiliser des variables d'environnement QWCTL_{VAR_NAME} au lieu de ce fichier de configuration. Par exemple, pour le format de sortie, vous pouvez définir la variable QWCTL_FORMAT à json ou pretty.

Informations du cluster​

qwctl infos
qwctl infos --jq .self_node_id

Lister les index​

qwctl list
qwctl list -p "otel-*" # liste les index dont le nom commence par "otel-"

Créer un index​

qwctl create -i "my-index" --field key:text --field value:i64
qwctl create -i "my-index" --field key:text --field value:i64 --time-field my-timestamp
qwctl create -i "my-index" --field key:text --field value:i64 --mode strict --max-partitions 200
qwctl create -i "my-metrics" --field "values:array<f64>" --time-field "event-time"
qwctl create -i "my-counters" --field "body:object<key:text, value:u64>" --field "metadata:json" --time-field "event-time"

Schémas/mappings préparés​

Vous pouvez créer des schémas préparés, comme pour les métriques Prometheus :

qwctl create --schema prometheus
qwctl create -i "my-prometheus-index" --schema prometheus

Cela permet d'ingérer des métriques Prometheus avec Vector en suivant ce billet de blog et de les interroger avec la syntaxe PromQL (plus de détails dans la section recherche).

Les schémas disponibles sont :

  • prometheus : pour les métriques Prometheus (v0.4)
  • otel-logs : pour les logs OpenTelemetry (v0.7)
  • otel-traces : pour les traces OpenTelemetry (v1.2)
  • imalive : pour les métriques imalive (v0.1)
  • analytics : pour les données d'analytique web (v0.4)

Schémas/mappings externes​

Vous pouvez également utiliser un fichier de schéma/mapping externe :

qwctl create -i "my-index" --file my-mapping.json

Supprimer un index​

qwctl delete -i "my-index"

Afficher le détail d'un index​

Pour afficher tout le mapping d'un index :

qwctl details -i "otel-logs-v0_7"

Filtrer la sortie avec une json query :

qwctl details -i "otel-logs-v0_7" --jq ".version"

Rechercher des logs​

qwctl search
qwctl search -i "otel-logs-v0_7" -q "*"
qwctl search -i "my-index" -q "foo:bar" --format json --jq ".foo" --max 100
qwctl search -i "my-index" -q='{foo="bar"}' --format json --syntax logql

Notes:

  • vous pouvez toujours filtrer la sortie avec une json query et l'option --jq
  • le format de sortie peut être json ou pretty (par défaut)
  • la syntaxe de recherche peut être lucene (par défaut), sql, logql (similaire à la syntaxe de Grafana Loki, proche de PromQL) ou promql (dans ce cas, votre index doit être un index de métriques créé avec le flag --prometheus)

Ingérer des documents​

qwctl ingest -i "my-index" -b '{"foo": "bar", "time": "2024-01-01T00:00:00Z"}'
qwctl ingest -i "my-index" -f "data.json"
qwctl ingest -i "my-index" -b '{"foo": "bar"}' --time "time"

Métriques​

Récupérer toutes les métriques disponibles (depuis l'URL prometheus /metrics de l'API) avec :

qwctl metrics ls

Récupérer une métrique particulière avec :

qwctl metrics get -n <metric_name>
qwctl metrics get --name <metric_name>

Remarques :

  • Le wildcard * est pris en charge pour récupérer toutes les métriques qui commencent par une chaîne particulière (ex. : qwctl metrics get -n "quickwit_metastore_*" pour récupérer toutes les métriques dont le nom commence par quickwit_metastore_)
  • Le filtrage par labels est aussi pris en charge avec le flag --filter (ex. : qwctl metrics get -n "quickwit_metastore_grpc_request_duration_seconds_bucket" --filter "kind=client" pour récupérer la métrique quickwit_metastore_grpc_request_duration_seconds_bucket avec le label kind égal à client)

IA MCP et agents​

Créer un serveur MCP​

qwctl ai mcp
qwctl ai mcp -l 127.0.0.1 -p 8080 -e /mcp

Créer un agent appelant le serveur MCP​

qwctl ai agent -p "List the indexes"
qwctl ai agent -p "Search *" -s "http://127.0.0.1:8080/mcp" --provider anthropic

Remarque : les fournisseurs disponibles sont anthropic, openai, deepseek ou openrouter. Pour le moment, vous pouvez configurer vos clés comme ceci :

qwctl configure set openai_api_key "your_key"
qwctl configure set anthropic_api_key "your_key"
qwctl configure set openrouter_api_key "your_key"
qwctl configure set deepseek_api_key "your_key"
qwctl configure set gemini_api_key "your_key"
qwctl configure set mistral_api_key "your_key"

Vous pouvez aussi utiliser des variables d'environnement :

export QWCTL_OPENAI_API_KEY="your_key"
export QWCTL_ANTHROPIC_API_KEY="your_key"
export QWCTL_OPENROUTER_API_KEY="your_key"
export QWCTL_DEEPSEEK_API_KEY="your_key"
export QWCTL_GEMINI_API_KEY="your_key"
export QWCTL_MISTRAL_API_KEY="your_key"

Remarque : vous pouvez aussi utiliser le mode interactif pour créer votre agent avec le flag -i ou --interactive :

qwctl ai agent -i

Créer un agent web​

Vous pouvez aussi utiliser un mode serveur web pour interroger votre agent via des requêtes HTTP POST au lieu de la CLI :

qwctl ai web-agent -a 0.0.0.0 -p 8081

Le chemin / peut être configuré comme un adaptateur IA externe (utilisable directement depuis Aristochat), et le chemin /gitlab comme un webhook GitLab si vous définissez les configurations suivantes :

qwctl configure set gitlab_base_url "https://gitlab.cwcloud.tech"
qwctl configure set gitlab_token "your_gitlab_token"
qwctl configure set gitlab_webhook_secret "your webhook secret"

Ou avec les variables d'environnement suivantes :

export QWCTL_GITLAB_BASE_URL="https://gitlab.cwcloud.tech"
export QWCTL_GITLAB_TOKEN="your_gitlab_token"
export QWCTL_GITLAB_WEBHOOK_SECRET="your webhook secret"

Vous pouvez également utiliser aristochat pour exposer cet agent dans une interface OpenSource similaire à chatGPT sans dépendre de l'API AI de CWCloud.

Lister tous les outils MCP disponibles​

qwctl ai agent -p "list_mcp_dynamic_tools"

Remarque : un serveur MCP qwctl doit être en cours d'exécution pour que cette commande fonctionne.

Alertes avec alertmanager​

qwctl alertmanager -f alerts.yml
qwctl alertmanager -a 127.0.0.1 -p 8083 -f alerts.yml
qwctl alertmanager -a 127.0.0.1 -p 8083 -f alerts.yml --interval 1m

Remarques :

1/ un fichier alerts.yml doit etre cree et contenir les alertes que vous voulez creer. Voici un exemple :

---
alerts:
  - name: quickwit_high_ram
    summary: High RAM detected
    description: RAM max over last 5 minutes is above 90%.
    severity: critical
    syntax: promql
    index: prom-metrics-v0.4
    jq: .gauge.value
    labels:
      - name: group
        value: cwcloud
      - name: source
        jq: .tags.source
    threshold: 10
    query: |
      ram_percent[5m]

threshold est le seuil de la valeur renvoyé par jq.value, au-dessus duquel l'alerte sera declenchée. Il peut être remplacé par hits si vous préférez évaluer un nombre de document renvoyé par la requête.

2/ vous pouvez egalement configurer une URL cible d'un alertmanager prometheus comme ceci :

qwctl configure set alertmanager_url http://127.0.0.1:9093/api/v2/alerts

Ou avec cette variable d'environnement :

export EDTCTL_ALERTMANAGER_URL="http://127.0.0.1:9093/api/v2/alerts"

3/ l'intervalle est de 1 minute par defaut. Vous pouvez utiliser le flag --interval {time}{unit} pour le modifier. L'unite peut etre s pour secondes, m pour minutes, h pour heures.

4/ un serveur web est lance par cette commande (par defaut, il est accessible sur http://127.0.0.1:8083).

Les alertes actives sont disponibles sur l'endpoint /alerts.

Vous pouvez aussi afficher un tableau de bord web avec l'endpoint / :

white

Footnotes​

  1. Sous licence MIT, les sources sont disponibles ici. ↩