Barrel
EN GitHub

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éTypeCe qu’il compte
barrel_doc_operations_total{db,operation}counterÉcritures, lectures et suppressions de documents
barrel_doc_operation_duration_seconds{db,operation}histogramDuré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}counterRequêtes exécutées
barrel_query_duration_seconds{db}histogramDurée de chaque requête
barrel_query_results_count{db}histogramLignes renvoyées par requête
barrel_query_timeouts_totalcounterRequêtes qui ont atteint leur échéance
barrel_replication_docs_total{direction}counterDocuments écrits par la réplication
barrel_replication_errors_total{task_id}counterErreurs de réplication, par identifiant de réplication
barrel_replication_active{task_id}gauge1 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}gaugeSecondes écoulées depuis l’écriture sur la source du dernier changement copié ; 0 une fois à jour
barrel_db_documents_total{db}gaugeDocuments vivants (les documents supprimés ne sont pas comptés), nombre exact
barrel_db_attachments_total{db}gaugePièces jointes, nombre exact, pour les stockages blob et S3
barrel_db_size_bytes{db}gaugeTaille du stockage des documents sur disque
barrel_db_pending_compaction_bytes{db}gaugeOctets que la compaction doit encore réécrire
barrel_db_compactions_running{db}, barrel_db_compactions_queued{db}gaugeCompactions en cours, et en attente d’un thread
barrel_db_stubs_total{db}, barrel_db_stubs_bytes{db}gaugeDocuments 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.

Modifié dans barrel_docdb 3.0

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()]).
Sortie, abrégée, après une écriture, une lecture et une requête sur la base mon (exécution réelle de l’image Barrel 2026.11.9)
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.

Remarque

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

AppelRenvoie
barrel:info(Db), GET /db/:dbConfiguration, 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.
  • paused avec paused_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
Manque connu

barrel_server n’enregistre pas encore de métriques sur les requêtes HTTP et ne sert pas de route /metrics.

Traduit de la page anglaise: /docs/operate/monitoring/ Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir