Mettre en place une pile de surveillance de bases de données vectorielles avec Prometheus et Grafana

VectorAI DB propose une interface native /metrics point de terminaison au format Prometheus/OpenMetrics sur le port 6573. Ce tutoriel intègre ce point de terminaison dans une pile Docker Compose comprenant Prometheus et Grafana, crée une « tableau de bord » à quatre panneaux que vous pouvez importer directement, et configure huit règles d’alerte issues de la documentation de surveillance de VectorAI DB. Avant de procéder à la configuration, voici ce que ces métriques permettent réellement de suivre.

Quelles sont les mesures de surveillance des bases de données vectorielles ?

La surveillance d'une base de données Vector consiste à surveiller des indicateurs clés afin de s'assurer que votre base de données fonctionne comme prévu. Ces indicateurs comprennent la latence d'requête , l'utilisation de la mémoire, l'utilisation de l'processeur , l'état des index et la qualité des résultats. Chacun d'entre eux correspond à une métrique spécifique de votre instance VectorAI DB.

requête La latence correspond au temps nécessaire à votre recherche des k plus proches voisins pour renvoyer des résultats. Étant donné que la recherche vectorielle repose sur la similarité plutôt que sur des correspondances exactes, c’est le premier indicateur qui intéresse votre SLA . VectorAI DB le suit via actian_vectorai_rest_responses_duration_seconds (p95/p99 par point d'extrémité). En cas de pression sur la mémoire ou lors d'une reconstruction d'index, la latence peut atteindre des pics bien supérieurs à la valeur de référence normale, passant parfois d'environ 20 ms à 500 ms.

Les actian_vectorai_memory_resident_bytes Cet indicateur montre la quantité de mémoire vive utilisée par vos index vectoriels. Un autre indicateur clé est actian_vectorai_process_major_page_faults_total. Une augmentation constante de cette valeur indique une pression sur la mémoire et peut signifier que le système d'exploitation récupère des pages à partir d'un support de stockage sur disque, ce qui entraîne généralement une augmentation de la latence d'requête .

actian_vectorai_process_threads indique le nombre de threads lors des calculs de similarité. Une augmentation du nombre de threads sous charge reflète la sollicitation du processeur ; en associant cette information aux indicateurs d'processeur s au niveau du système fournis par l'exportateur de nœuds Prometheus, vous obtenez une vue d'ensemble complète.

« Index health » vous donne un insight s sur ce qui se passe en arrière-plan. Le actian_vectorai_collection_running_optimizations et actian_vectorai_rebuild_running Les indicateurs permettent de savoir quand des reconstructions ont lieu. actian_vectorai_rebuild_failed_total assure le suivi des défaillances, et actian_vectorai_rebuild_duration_seconds indique la durée des reconstructions.

VectorAI DB ne fournit pas le taux de rappel (pourcentage de véritables voisins les plus proches renvoyés) en tant qu’indicateur en temps réel. Validez-le hors ligne à l’aide d’un ensemble de test étiqueté et utilisez plutôt la latence et le taux d’erreur.

Ce que vous allez créer

Mettre VectorAI DB en production implique de pouvoir observer le comportement du système sous charge, de savoir repérer un état de dégradation et de comprendre comment être alerté avant qu’un incident ne se produise. La surveillance est particulièrement importante pour les charges de travail de génération augmentée par la recherche (RAG) utilisant de grands modèles linguistiques, car les pics de latence ou les défaillances d’index peuvent nuire à la qualité des réponses générées par l’IA. Une configuration de surveillance adaptée vous permet de savoir quand la latence augmente, quand la pression sur la mémoire s'accentue et quand les reconstructions d'index échouent, avant que ces problèmes n'atteignent les utilisateurs.

VectorAI DB offre une /metrics point de terminaison sur le port 6573 au format Prometheus/OpenMetrics, ce qui vous évite d'avoir recours à des exportateurs ou agents supplémentaires pour l'application metrics. L'exportateur de nœuds Prometheus, disponible en option, couvre l'processeur s et la mémoire au niveau de l'hôte si vous avez besoin d'une visibilité à l'échelle du système allant au-delà de ce que VectorAI DB expose directement.

Dans ce tutoriel, vous allez connecter ce point de terminaison à une pile Docker Compose comprenant VectorAI DB, Prometheus et Grafana. Vous allez créer un tableau de bord à quatre panneaux tableau de bord que vous pourrez importer immédiatement, puis configurer huit règles d'alerte en suivant les instructions de la documentation de VectorAI DB relative à la surveillance.

À la fin, vous disposerez d’une instance « tableau de bord » ainsi que de règles d’alerte configurées et opérationnelles sur votre propre instance.

Ce que le point de terminaison « Metrics » révèle sur les performances des bases de données vectorielles

VectorAI DB fournit ses indicateurs à l'adresse suivante : GET /metrics sur le port de l'API REST (6573 par défaut) au format Prometheus/OpenMetrics. Aucune authentification n'est requise pour ce point de terminaison ; par conséquent, si vous l'exposez sur un réseau public, protégez-le à l'aide d'un pare-feu ou d'un proxy inverse et de contrôles d'accès.

Tous les indicateurs commencent par le actian_vectorai_ préfixe. Le tableau ci-dessous répertorie les principaux indicateurs répartis en six catégories, en précisant leur type et ce qu'ils révèlent sur l'état du système et l'utilisation des ressources.

Configurer la pile

Conditions préalables

Avant de commencer, installez les éléments suivants :

• • Docker et Docker Compose
  • Python .10 ou version ultérieure
  • VectorAI DB (inscrivez-vous à la version communautaire)
  • SDK Actian-VectorAI-Client Python : pip install actian-vectorai-client

Assurez-vous que votre ordinateur dispose d'au moins 8 Go de mémoire vive (16 Go sont recommandés) et de 10 Go d'espace disque.

Si vous utilisez Windows, exécutez toutes les commandes dans WSL2. Pour configurer WSL2, exécutez la commande suivante : wsl --install Si vous utilisez PowerShell, veuillez utiliser le terminal Ubuntu pour ce tutoriel.

Structure du projet

Créer un répertoire de projet et une arborescence de dossiers :

mkdir -p vectorai-observability/{prometheus,grafana,scripts}
cd vectorai-observability

touch docker-compose.yml prometheus/prometheus.yml prometheus/alert_rules.yml scripts/load_test.py

Le répertoire de votre projet devrait se présenter comme suit :

vectorai-observability/

├── docker-compose.yml

├── prometheus/

│   ├── prometheus.yml

│   └── alert_rules.yml

├── grafana/

└── scripts/

    └── load_test.py

Votre pile « observabilité » s'exécutera sous la forme de trois services Docker Compose : VectorAI DB (REST/métriques sur le port 6573, gRPC sur le port 6574 et l'interface utilisateur locale sur le port 6575), Prometheus (port 9090) et Grafana (port 3000).

services:
  vectorai:
    image: actian/vectorai:latest
    platform: linux/amd64
    container_name: vectorai
    ports:
      - "6573:6573"
      - "6574:6574"
      - "6575:6575"
    volumes:
      - ./local_data:/var/lib/actian-vectorai
    environment:
      - ACTIAN_VECTORAI_ACCEPT_EULA=YES
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
      - ./prometheus/alert_rules.yml:/etc/prometheus/alert_rules.yml
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
    restart: unless-stopped
    depends_on:
      - vectorai

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    restart: unless-stopped
    depends_on:
      - prometheus

volumes:
  grafana_data:

Ajoutez ceci à prometheus/prometheus.yml. Pour les déploiements via Docker Compose, Prometheus identifie VectorAI DB par son nom de service. Si vous exécutez VectorAI DB dans un conteneur autonome en dehors du réseau Compose, utilisez host.docker.internal:6573 à la place, comme cible de la récupération :

global:
  scrape_interval: 15s

rule_files:
  - "alert_rules.yml"

scrape_configs:
  - job_name: "vectorai"
    scrape_interval: 15s
    static_configs:
      - targets: ["vectorai:6573"]

docker compose up -d

Aller à localhost:9090/targets. Le vectorai Le résultat devrait s'afficher 1/1 UP avec une durée de lecture inférieure à 20 ms. Si elle indique DOWN, vérifiez que le port 6573 est ouvert et qu'aucun pare-feu ne bloque la connexion.

Aller à localhost:3000 et connectez-vous avec vos identifiants d'administrateur. Rendez-vous ensuite dans « Connexions », sélectionnez « Sources de données », cliquez sur « Ajouter une nouvelle source de données », sélectionnez « Prometheus », puis définissez l'URL comme suit : http://prometheus:9090, définissez-le comme valeur par défaut, puis enregistrez.

Créer la base de données vectorielle tableau de bord

L'tableau de bord e quatre indicateurs clés : le taux de requêtes, la latence p95, le taux d'erreur et la pression mémoire. Le suivi de ces indicateurs vous aide à optimiser les performances d'indexation et de recherche. Ajoutez les requêtes PromQL suivantes au fichier grafana/tableau de bord.json au fur et à mesure que vous créez chaque tableau de bord dans Grafana.

Encadré 1 : Fréquence des requêtes REST par point de terminaison

Ce graphique présente le débit d'requête s par point de terminaison au fil du temps. Créez un graphique de séries chronologiques à l'aide de cette requête PromQL requête:

sum by (endpoint) (rate(actian_vectorai_rest_responses_total[5m]))

Définissez le format de la légende sur {{endpoint}}. Il affiche le débit pour chaque point d'extrémité, ce qui vous permet d'identifier les routes qui génèrent le plus de trafic et de repérer les tendances d'requête avant qu'elles n'affectent les performances.

Encadré 2 : Latence REST p95 par point de terminaison

Il s'agit du signal de latence principal pour la surveillance d'SLA . Métriques d'histogramme Prometheus actian_vectorai_rest_responses_duration_seconds afficher automatiquement _bucket série, c'est-à-dire histogram_quantile sur lesquelles effectuer des requêtes. Créer un panneau de séries chronologiques :

histogram_quantile(0.95, sum by (le, endpoint) (rate(actian_vectorai_rest_responses_duration_seconds_bucket[5m])))

Définissez le format de la légende sur {{endpoint}}. Si la latence augmente alors que le taux de requêtes reste stable, cela pourrait indiquer une pression sur la mémoire ou une reconstruction d'index affectant les performances de recherche.

Encadré 3 : Taux d'erreurs gRPC

Le SDK « Python » communique via gRPC ; la surveillance des erreurs s'effectue donc au niveau de la couche gRPC. Créez un panneau de statistiques à l'aide de :

sum(rate(actian_vectorai_grpc_responses_fail_total[5m]))
/
(sum(rate(actian_vectorai_grpc_responses_total[5m])) > 0 or vector(1))

La fonction « requête » renvoie une fraction comprise entre 0 et 1. Définissez les seuils à 0,01 pour le vert, 0,05 pour le jaune et toute valeur supérieure à 0,05 pour le rouge, ou configurez l'unité Grafana sur percent (0-1) pour afficher automatiquement les valeurs sous forme de pourcentages. Le voyant passe du vert au jaune lorsque les erreurs approchent les 5 %, puis au rouge dès qu’elles dépassent ce seuil, ce qui permet de détecter une erreur d’ requête de collecte ou une défaillance de connectivité avant que la situation ne s’aggrave.

Table ronde n° 4 : Pression sur la mémoire

Ce tableau de bord suit deux signaux qui, combinés, indiquent si le moteur fonctionne dans les limites de sécurité en matière d'utilisation de la mémoire. Créez un tableau de bord de séries chronologiques à l'aide de deux requêtes :

# RSS: RAM consumed by vector indexes
actian_vectorai_memory_resident_bytes

# Early warning signal for disk paging
rate(actian_vectorai_process_major_page_faults_total[5m])

Définissez les libellés de la légende comme suit : RSS et Major Page Faults/s. Si le taux de défaillance augmente alors que la valeur RSS est proche de sa limite, le processeur effectuera des opérations de pagination vers le disque, ce qui entraînera rapidement une augmentation de la latence.

Une fois les quatre panneaux configurés, ouvrez les paramètres d'tableau de bord , accédez à « Modèle JSON » et copiez le contenu. Enregistrez-le dans grafana/dashboard.json. Ce fichier se trouve également dans le dépôt GitHub, ce qui vous permet de cloner le dépôt et de l'importer immédiatement dans Grafana.

Configurer les règles d'alerte

Ajoutez les règles d'alerte suivantes à prometheus/alert_rules.yml. Prometheus les charge automatiquement au démarrage via le rule_files directive dans prometheus.yml.

groups:
  - name: vectorai
    rules:
      - alert: VectorAIHighRESTErrorRate
        expr: >
          sum(rate(actian_vectorai_rest_responses_fail_total[5m]))
          /
          sum(rate(actian_vectorai_rest_responses_total[5m]))
          > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB REST error rate above 5%"
          description: "{{ $value | humanizePercentage }} of REST requests are returning errors."

      - alert: VectorAIHighRESTLatency
        expr: >
          histogram_quantile(0.95, sum by (le) (rate(actian_vectorai_rest_responses_duration_seconds_bucket[5m])))
          > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB REST p95 latency above 2s"
          description: "REST p95 latency is {{ $value }}s."

      - alert: VectorAIHighGRPCErrorRate
        expr: >
          sum(rate(actian_vectorai_grpc_responses_fail_total[5m]))
          /
          sum(rate(actian_vectorai_grpc_responses_total[5m]))
          > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB gRPC error rate above 5%"
          description: "{{ $value | humanizePercentage }} of gRPC calls are failing."

      - alert: VectorAIRecoveryModeActive
        expr: actian_vectorai_app_status_recovery_mode == 1
        for: 0m
        labels:
          severity: critical
        annotations:
          summary: "VectorAI DB is in recovery mode"
          description: "The engine has entered recovery mode and requires immediate attention."

      - alert: VectorAIHighMemoryUsage
        expr: actian_vectorai_memory_resident_bytes > 0.8 * 8589934592  # Replace with your memory limit in bytes
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB memory usage above 80%"
          description: "RSS is {{ $value | humanize }}B, exceeding 80% of available memory."

      - alert: VectorAIMajorPageFaultsRising
        expr: rate(actian_vectorai_process_major_page_faults_total[5m]) > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB major page faults rising"
          description: "Sustained major page faults indicate memory pressure and potential disk paging."

      - alert: VectorAIFileDescriptorExhaustion
        expr: actian_vectorai_process_open_fds > 0.8 * 65536  # Replace with your system fd limit
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB file descriptors approaching limit"
          description: "Open file descriptors at {{ $value }}, approaching 80% of system limit."

      - alert: VectorAIRebuildFailures
        expr: rate(actian_vectorai_rebuild_failed_total[1h]) > 0
        for: 0m
        labels:
          severity: warning
        annotations:
          summary: "VectorAI DB index rebuild failure detected"
          description: "One or more index rebuilds have failed in the last hour."

Deux règles utilisent des valeurs spécifiques à l'environnement que vous devez définir avant le déploiement. VectorAIHighMemoryUsage se déclenche lorsque le RSS dépasse 80 % de la mémoire disponible ; remplacez donc 8589934592 en indiquant votre limite de mémoire réelle en octets. VectorAIFileDescriptorExhaustion se déclenche lorsque les descripteurs de fichiers ouverts atteignent environ 80 % de la limite du système ; remplacez donc 65536 avec le résultat de ulimit -n sur votre serveur.

VectorAIRecoveryModeActive et VectorAIRebuildFailures utilisation for: 0m, ce qui signifie qu'elles se déclenchent immédiatement plutôt que d'attendre qu'un état persistant se produise. Les échecs en mode de récupération et de reconstruction doivent être traités dès qu'ils surviennent, et non après un délai de cinq minutes.

Vérifiez que les huit règles se sont bien chargées en accédant à localhost:9090/alerts.

Valider en charge

Exécutez le script de test de charge pour générer un trafic réel de type « requête » vers votre instance de base de données VectorAI. Ajoutez ce qui suit à scripts/load_test.py:

import random
import time
from concurrent.futures import ThreadPoolExecutor
from actian_vectorai import VectorAIClient, VectorParams, Distance

COLLECTION = "load_test"
DIMENSION = 128
TOTAL_QUERIES = 1000
RPS = 50
DURATION = 60

def random_vector(dim):
    return [random.uniform(-1, 1) for _ in range(dim)]

def run_query(client):
    try:
        client.points.search(
            collection_name=COLLECTION,
            vector=random_vector(DIMENSION),
            limit=10
        )
    except Exception as e:
        print(f"Query error: {e}")

def main():
    with VectorAIClient("localhost:6574") as client:
        try:
            client.collections.create(
                name=COLLECTION,
                vectors_config=VectorParams(size=DIMENSION, distance=Distance.Cosine)
            )
            print(f"Created collection: {COLLECTION}")
        except Exception as e:
            print(f"Collection {COLLECTION} already exists, continuing... ({e})")

        print(f"Running {TOTAL_QUERIES} queries at {RPS} req/s for {DURATION}s...")
        interval = 1.0 / RPS
        start = time.time()
        count = 0

        with ThreadPoolExecutor(max_workers=10) as executor:
            while count < TOTAL_QUERIES and (time.time() - start) < DURATION:
                executor.submit(run_query, client)
                count += 1
                time.sleep(interval)

        elapsed = time.time() - start
        print(f"Done. {count} queries in {elapsed:.1f}s ({count/elapsed:.1f} req/s)")

if __name__ == "__main__":
    main()

Ensuite, lancez-le :

python scripts/load_test.py

Le script se connecte à la base de données VectorAI via gRPC sur le port 6574, crée une collection à 128 dimensions et envoie 1 000 requêtes de vecteurs aléatoires à un rythme de 50 requêtes par seconde pendant 60 secondes. Au fur et à mesure de l'exécution du script, le graphique du débit de requêtes affiche une augmentation du trafic, la latence p95 se stabilise et le taux d'erreurs gRPC reste à zéro.

Pour voir le panneau « Taux d'erreur » s'afficher, envoyez une requête à requête en indiquant une collection qui n'existe pas :

from actian_vectorai import VectorAIClient

with VectorAIClient("localhost:6574") as client:
    try:
        client.points.search(
            collection_name="nonexistent_collection",
            vector=[0.1]*128,
            limit=5
        )
    except Exception as e:
        print(f"Error: {e}")

Le graphique représentant le taux d'erreurs gRPC affiche immédiatement un pic. Cette séquence permet à votre équipe de voir à quoi ressemble le système lorsqu'il fonctionne normalement et lorsqu'un problème survient.

Trois scénarios de suivi

Le pic de taux de requêtes que vous avez observé lors du test de charge correspond au pic de trafic sur un moteur de recommandation de produits. Lorsque ce pic survient parallèlement à une augmentation de la latence p95, l’index vectoriel subit une pression mémoire. Le tableau de bord dédié à la pression mémoire permet de détecter ce phénomène avant qu’il n’atteigne l’ utilisateur.

Les échecs de reconstruction d'index dans un système de recherche d'images médicales réduisent progressivement la précision de la recherche sans générer d'erreur. Le tableau de bord du taux d'erreurs gRPC ne les détectera pas, mais actian_vectorai_rebuild_failed_total et le VectorAIRebuildFailures une alerte sera déclenchée. L'alerte se déclenche dans l'heure qui suit toute défaillance, et la surveillance actian_vectorai_rebuild_duration_seconds vous indique lorsque les reconstructions d'index, déclenchées par de nouvelles mises à jour d'ingestion de données s ou de modèles, prennent plus de temps que prévu.

Le graphique représentant le taux d'erreurs gRPC a atteint un pic à 0.952 dans notre test, car 20 requêtes consécutives ayant échoué, alors que le seuil de réussite était faible, ont fait grimper le ratio à près de 1. C'est ce même signal que détecte un pipeline de détection des fraudes lorsque des échecs d'authentification empêchent la consultation des transactions en temps réel. La comparaison des vecteurs de transaction avec des signatures de fraude connues nécessite une latence d'requête inférieure à 100 ms. Lorsque ce voyant passe au rouge, le pipeline est déjà exposé à un risque.

Configurer la journalisation structurée

Ajoutez ce qui suit à la configuration de votre base de données VectorAI pour activer les journaux au format JSON compatibles avec Elasticsearch, Loki ou Datadog.

journalisation :
  format : json
  niveau : info

Définissez le niveau de journalisation en fonction de votre environnement :

L'exécution aux niveaux « debug » ou « trace » en production génère un volume important de données de journalisation et peut affecter les performances de la base de données. N'utilisez ces niveaux que pour un dépannage à court terme, puis repassez au niveau « info ».

Pour conclure

Vous disposez désormais d’une pile de surveillance qui vous permet de détecter les variations de latence de la recherche vectorielle, de la pression mémoire ou des erreurs gRPC avant même que les utilisateurs ne s’en rendent compte. Prometheus collecte les métriques en temps réel sur le port 6573 ; votre page Grafana à quatre panneaux tableau de bord couvre les indicateurs essentiels ; et huit règles d’alerte se déclenchent dès que l’un d’entre eux dépasse un seuil défini par votre équipe.

Cloner le dépôt GitHub Pour obtenir la pile complète : docker-compose.yml, prometheus/prometheus.yml, prometheus/alert_rules.yml, grafana/dashboard.json, et scripts/load_test.py. Importez le fichier JSON « tableau de bord » dans Grafana, et la pile est prête.

Pour plus d'informations sur le point de terminaison des métriques et la configuration de la surveillance, consultez la documentation relative à la surveillance de la base de données VectorAI.

À propos de l'auteur

À propos de Tahiya Chowdhury

Tahiya Chowdhury est chef de produit pour Actian Zen et VectorAI DB, où elle dirige la stratégie de la plateforme de données en périphérie la plus robuste du secteur. Forte de son expérience chez MongoDB et Goldman Sachs, Tahiya est spécialisée dans la conception de produits qui concilient les besoins des grandes entreprises et la rapidité de développement moderne. Elle s'attache avec passion à simplifier les infrastructures de données, afin de permettre aux équipes d'ingénieurs de passer plus rapidement du prototype à la mise en production.