Supervision
Cette page décrit ce que Barrel mesure, comment vous le lisez et comment vous surveillez les tâches de réplication. Lisez-la quand vous mettez un nœud en production et devez savoir qu’il est en bonne santé et qu’il suit le rythme.
Ce que Barrel mesure
La couche documents, barrel_docdb, enregistre des métriques sur chaque nœud, que vous les exportiez ou non. Elles suivent les conventions Prometheus : un counter se termine par _total, et les labels sont exportés comme labels. Écrivez vos requêtes avec les noms ci-dessous.
| Nom exporté | Type | Ce qu’il compte |
|---|---|---|
barrel_doc_operations_total{db,operation} | counter | Écritures, lectures et suppressions de documents |
barrel_doc_operation_duration_seconds{db,operation} | histogram | Durée de chaque opération sur un document |
barrel_write_group_size{db} | histogram | Écritures validées ensemble dans un même lot |
barrel_query_operations_total{db} | counter | Requêtes exécutées |
barrel_query_duration_seconds{db} | histogram | Durée de chaque requête |
barrel_query_results_count{db} | histogram | Lignes renvoyées par requête |
barrel_query_timeouts_total | counter | Requêtes qui ont atteint leur échéance |
barrel_replication_docs_total{direction} | counter | Documents écrits par la réplication |
barrel_replication_errors_total{task_id} | counter | Erreurs de réplication, par identifiant de réplication |
barrel_replication_active{task_id} | gauge | 1 tant que la tâche tourne, 0 quand elle est en pause, en échec, terminée ou supprimée |
barrel_replication_lag_seconds{task_id} | gauge | Secondes écoulées depuis l’écriture sur la source du dernier changement copié ; 0 une fois à jour |
barrel_db_documents_total{db} | gauge | Documents vivants (les documents supprimés ne sont pas comptés), nombre exact |
barrel_db_attachments_total{db} | gauge | Pièces jointes, nombre exact, pour les stockages blob et S3 |
barrel_db_size_bytes{db} | gauge | Taille du stockage des documents sur disque |
barrel_db_pending_compaction_bytes{db} | gauge | Octets que la compaction doit encore réécrire |
barrel_db_compactions_running{db}, barrel_db_compactions_queued{db} | gauge | Compactions en cours, et en attente d’un thread |
barrel_db_stubs_total{db}, barrel_db_stubs_bytes{db} | gauge | Documents supprimés conservés comme stubs, après chaque purge de rétention |
Les gauges de taille et de compaction se mettent à jour chaque minute (stats_interval), et une première fois dans la seconde qui suit l’ouverture. Un retard de compaction qui ne cesse de grandir, ou des compactions en attente qui restent au-dessus de zéro, signifient que la compaction ne suit plus vos écritures.
Une métrique apparaît dans l’export dès qu’elle a une valeur : un nœud qui n’a jamais répliqué n’affiche aucune métrique de réplication.
Avant barrel_docdb 3.0, les labels étaient intégrés au nom : les opérations sur les documents étaient exportées sous barrel_doc_operations_db_operation_total{db,operation}, et il en allait de même pour chaque métrique avec labels. Mettez à jour les tableaux de bord et les alertes qui utilisent les anciens noms.
Les nombres de documents et de pièces jointes sont exacts : chaque écriture qui en ajoute ou en retire un met le compte à jour dans la même écriture atomique (barrel_docdb 2.4.0). Une base écrite avant la 2.4.0 est comptée une fois en arrière-plan après son ouverture ; d’ici là, ses comptes ne sont pas publiés et db_info les renvoie à undefined.
barrel_vectordb, barrel, barrel_server, barrel_spaces et barrel_embed n’enregistrent aucune métrique.
Lire les métriques
Dans le nœud, barrel_metrics:export_text/0 renvoie le format texte Prometheus sous forme de binaire (export/0 renvoie de l’iodata).
io:format("~s", [barrel_metrics:export_text()]).
barrel_doc_operations_total{db="mon",operation="put"} 1.0
barrel_doc_operations_total{db="mon",operation="get"} 1.0
barrel_query_operations_total{db="mon"} 1.0
barrel_doc_operation_duration_seconds_count{db="mon",operation="put"} 1 Les envoyer à un collecteur
barrel_server ne sert pas de route /metrics. Poussez les métriques en OTLP vers votre collecteur, que Prometheus ou un autre backend lit ensuite. Définissez les exporters dans l’environnement applicatif de barrel_docdb :
[{barrel_docdb, [
{metrics, [{exporter, otlp},
{otlp_endpoint, "http://collector:4318"}]},
{tracing, [{enabled, true}, {exporter, otlp},
{otlp_endpoint, "http://collector:4318"}]}
]}].
L’exporter vaut none par défaut ; console et {Mod, Map} sont aussi acceptés. Métriques, traces et logs ont chacun leur propre exporter, voir Configuration.
Les traces couvrent les opérations sur les documents, les requêtes et la réplication. Les requêtes de réplication sortantes transmettent les en-têtes de trace au pair.
La clé export_interval montrée dans certaines docs de barrel_docdb n’est jamais lue.
Si vous voulez un point d’accès à scraper, servez barrel_metrics:export_text() depuis un handler de votre propre application.
Les statistiques disponibles
| Appel | Renvoie |
|---|---|
barrel:info(Db), GET /db/:db | Configuration, rétention, plancher d’historique, compteurs de groupes d’écriture, embedder, et storage : taille sur disque, retard de compaction, et les comptes documents et attachments. |
barrel:vector_stats(Db) | Nombre de vecteurs, dimension, type d’index et si l’index a été chargé ou reconstruit |
barrel_docdb:stub_stats(Name) | Nombre de stubs et octets. Parcourt le flux de changements dans le processus appelant. |
barrel_rep_tasks:list_tasks() | Chaque tâche de réplication avec son statut |
barrel_rep_tasks:get_task(Id) | Une tâche : status, last_seq, last_error, paused_reason |
{ok, S} = barrel:vector_stats(Db),
maps:with([count, dimension, index_origin], S).
L’outil MCP db_info annonce renvoyer un nombre de documents ; il renvoie la même map que barrel:info/1, qui n’en contient pas.
Surveiller les tâches de réplication
Une tâche continue garde le statut running pendant qu’elle réessaie, avec un backoff exponentiel. L’erreur est portée par la tâche, pas par son statut : alertez donc sur last_error.
{ok, Tasks} = barrel_rep_tasks:list_tasks(#{mode => continuous}),
[{Id, Status, maps:get(last_error, T, none)}
|| #{id := Id, status := Status} = T <- Tasks].
- Statuts :
pending,running,paused,completed,failed. pausedavecpaused_reason<<"db_closed">>signifie que la base locale de la tâche n’est pas ouverte. La tâche reprend quand la base s’ouvre.- Une tâche ponctuelle échoue tout de suite ; seules les tâches continues réessaient.
Vérifications de santé
GET /health répond 200 {"status":"ok"} sans authentification. Cela indique que l’écoute HTTP fonctionne ; aucune base n’est ouverte et aucun magasin n’est vérifié.
curl -s localhost:8080/health
GET /ready est la vérification de disponibilité (readiness). Elle ne demande pas de token non plus. Elle répond 200 {"status":"ready"} quand les processus des bases et de la réplication tournent, et 503 {"status":"not_ready","failed":[...]} sinon, où failed nomme les vérifications en échec parmi databases, stores et replication. Pointez-y un répartiteur de charge ou un orchestrateur.
curl -s localhost:8080/ready
Pour vérifier une base précise, lisez GET /db/:db avec un token. La route répond 404 db_not_found quand la base n’existe pas ; elle ne la crée pas.
curl -s -H "authorization: Bearer $TOKEN" \
localhost:8080/db/kb
barrel_server n’enregistre pas encore de métriques sur les requêtes HTTP et ne sert pas de route /metrics.