Aller au contenu

Supervision ​

Arkvory offre quatre sources de faits : des points de terminaison d’état qui répondent à « est-il en marche », des métriques Prometheus, des lignes de journal JSON et les diagnostics de la console. Cette page décrit ce que contient chaque source et se termine par un ensemble d’alertes pour commencer.

Les métriques, les points de terminaison d’état et les événements de journal décrivent un processus API. Le processus de traitement et l’agent de sauvegarde n’ont pas de port HTTP. Vous les voyez à travers les lignes de journal, les métriques de la file de finalisation et l’état des sauvegardes.

Vérifier un serveur maintenant ​

  1. Interrogez le point de terminaison d’état public. Il ne demande aucune clé :

    bash
    curl -fsS http://127.0.0.1:8080/health/status

    {"status":"ready"} avec HTTP 200 signifie que l’API atteint sa base de données et son répertoire de stockage.

  2. Demandez la réponse de disponibilité complète avec la clé d’état créée par le programme d’installation :

    bash
    sudo sh -c 'curl -fsS -H "Authorization: Bearer $(cat /opt/proanima-arkvory/config/health-token.txt)" http://127.0.0.1:8080/health/ready'
    powershell
    $root = 'C:\ProgramData\ProAnima\Arkvory'
    $key = (Get-Content "$root\config\health-token.txt" -Raw).Trim()
    Invoke-RestMethod -Headers @{ Authorization = "Bearer $key" } http://127.0.0.1:8080/health/ready
  3. Vérifiez les sauvegardes :

    bash
    arkvoryctl backup status

    La commande nécessite la clé de récupération ou la session d’un administrateur. Elle se termine avec le code 9 lorsqu’un avertissement critique est actif. Pour les contrôles automatisés, utilisez les alertes Prometheus ci-dessous. Voir Ligne de commande.

  4. Vérifiez les services et les dernières lignes de journal. Voir Journaux.

arkvory status --root <root> affiche la version installée, le mode d’installation et la politique de mise à jour. Il n’interroge pas le serveur. arkvoryctl doctor montre le serveur, le dépôt, les fonctionnalités et les autorisations d’une clé. C’est un contrôle côté client, pas un contrôle d’état.

État et disponibilité ​

Trois points de terminaison répondent sur le port de l’API. Aucun d’eux ne compte dans le budget de requêtes ARKVORY_MAX_REQUESTS, donc une charge de transfert ne peut pas faire paraître un serveur mort. Tous les trois continuent de répondre pendant que le serveur se vide avant un arrêt.

CheminCléRéponseUsage
/health/liveNon200 {"status":"ok"} tant que le processus répondUn contrôle de processus
/health/statusNon200 {"status":"ready"}, ou 503 {"status":"unavailable"} ou {"status":"draining"} avec Retry-After: 2Répartiteurs de charge et sondes de disponibilité
/health/readyToute clé valide200 avec les détails ci-dessous, ou 503 avec l’enveloppe d’erreur et Retry-AfterContrôles de déploiement et le contrôle d’état de Compose

/health/status et /health/ready vérifient trois choses : la base de données répond et possède exactement les migrations de cette version, le dossier blobs du répertoire de stockage existe, et le processus détient toujours son verrou de stockage. Le résultat de /health/status est mis en cache pendant une seconde, de sorte que les sondes publiques ne peuvent pas multiplier les requêtes vers la base de données. Un serveur en cours de vidage répond draining immédiatement.

Sans clé, /health/ready renvoie 401. La clé deployment-health que crée le programme d’installation n’a ni droits sur les dépôts ni droits d’administrateur. Son secret se trouve dans config/health-token.txt.

Une réponse 200 de /health/ready contient ces champs :

ChampSignification
statusToujours ready dans une réponse 200
writablefalse lorsque l’espace libre du volume de stockage est inférieur à ARKVORY_STORAGE_RESERVE_BYTES, et sur une passerelle de lecture. Les lectures fonctionnent toujours
replicationUniquement dans un cluster à haute disponibilité : copies, required et singleCopyUntil, ou null lorsque les copies ne peuvent pas être lues. writable vaut false tant que des copies manquent
roleapi, ou reader pour une passerelle de lecture
sharedDownloadsLe bail d’une passerelle de lecture (slot, slots, active, leaseSeconds), ou null
transfersPour uploads et downloads : admission (active, waiting, capacity, perPrincipalCapacity, waitingCapacity, perPrincipalWaitingCapacity, timeoutMs, rejected, timedOut, cancelled) et bandwidth (bytesPerSecond, perPrincipalBytesPerSecond, burstBytes, perPrincipalBurstBytes, waiting, grantedBytes)

Un contrôle de disponibilité en échec ne redémarre jamais un service à lui seul. Voir Autoréparation.

Métriques ​

GET /health/metrics renvoie les métriques du processus API au format texte Prometheus (version 0.0.4). Toute clé valide peut les lire, et cela fonctionne pendant que le serveur se vide. Créez une clé de service avec le minimum de droits pour le collecteur, et conservez-la dans un fichier que seul Prometheus lit.

yaml
scrape_configs:
  - job_name: arkvory
    metrics_path: /health/metrics
    scheme: https
    authorization:
      credentials_file: /etc/prometheus/arkvory.key
    static_configs:
      - targets: ['arkvory.example:443']

La tâche doit être nommée arkvory : les règles d’alerte fournies la sélectionnent par son nom.

Les valeurs appartiennent au processus et repartent de zéro après un redémarrage. arkvory_process_start_time_seconds change lorsque cela se produit. Les étiquettes sont bornées : route est le modèle de route, jamais l’URL, et status_class vaut 2xx, 5xx, etc.

MétriqueÉtiquettesSignification
arkvory_http_requests_totalmethod, route, status_classRéponses closes
arkvory_http_request_duration_secondsidemHistogramme de durée de 5 ms à 1800 s. Les transferts interrompus sont inclus
arkvory_http_request_bytes_total, arkvory_http_response_bytes_totalmethod, routeOctets de socket, en-têtes inclus
arkvory_http_requests_in_flightRequêtes admises dont les réponses sont encore ouvertes
arkvory_transfer_active, arkvory_transfer_queue_depthdirectionTransferts admis et transferts en attente d’un emplacement
arkvory_transfer_admission_failures_totaldirection, reasonTransferts refusés par l’admission : rejected (file pleine), timed_out, cancelled
arkvory_download_sessions_active, arkvory_download_sessions_waitingclassSessions de téléchargement qui ont une place ; celles en attente par classe
arkvory_download_queue_oldest_wait_secondsDepuis combien de temps attend le téléchargement le plus ancien
arkvory_download_session_events_totaleventSessions de téléchargement admitted, queued, completed, released après une pause, yielded à une limite de plage, abandonnées en no_show, refused au-delà de la limite
arkvory_completion_jobsstate (queued, running)Tâches de finalisation de téléversement dans la base de données
arkvory_completion_oldest_queued_secondsAttente de la plus ancienne tâche en file exécutable
arkvory_diagnostic_records_totaloutcome (written, dropped, truncated, oversized)Lignes de journal par résultat
arkvory_metrics_collection_failures_totalcollector (jobs, backup, mirror, webhook, fleet)Lectures échouées de métriques adossées à la base de données
arkvory_backup_last_success_timestamp_secondsHeure d’instantané du point de sauvegarde terminé le plus récent
arkvory_backup_agent_last_seen_timestamp_secondsDernier battement de cœur de l’agent de sauvegarde
arkvory_backup_warningscode1 tant que l’avertissement est actif, 0 sinon
arkvory_mirror_last_sync_timestamp_seconds, arkvory_mirror_last_check_timestamp_secondsrepository, modeDernière synchronisation avec la source et dernière lecture de son flux
arkvory_mirror_failingrepository, mode1 tant que la dernière tentative de synchronisation a échoué
arkvory_mirror_conflictsrepository, modeEntrées de la source mises de côté à cause d’un conflit pendant que le reste se synchronise
arkvory_webhook_failing, arkvory_webhook_last_success_timestamp_secondssubscription, repositoryLivraison des webhooks : 1 tant que la dernière tentative a échoué, et heure de la dernière réponse 2xx
arkvory_tls_certificate_expiry_timestamp_secondsExpiration du certificat HTTPS intégré. Présent uniquement avec HTTPS intégré
arkvory_build_infoservice, versionToujours 1
arkvory_process_start_time_seconds, arkvory_process_resident_memory_bytesHeure de démarrage et mémoire résidente
arkvory_database_pool_connections, arkvory_database_pool_idle, arkvory_database_pool_waitingpool (queries, sessions, locks)Connexions des pools de la base de données : ouvertes, libres et en attente ; une attente durable signifie que le pool est trop petit
arkvory_fleet_site_upsite, nameSur un contrôleur : 1 si la dernière lecture du site géré a obtenu une réponse, 0 sinon
arkvory_fleet_site_last_seen_timestamp_secondssite, nameSur un contrôleur : dernière réponse du site géré
arkvory_fleet_mirror_lag_changessite, repositorySur un contrôleur : retard, en changements, d’un miroir d’un site géré sur sa source ; tant que le site ne répond pas, la dernière valeur connue
arkvory_fleet_mirror_lag_alert_changesSur un contrôleur : ARKVORY_FLEET_LAG_ALERT (1000 par défaut), le retard à partir duquel un miroir déclenche une alerte ; ArkvoryFleetMirrorBehind s’y compare
arkvory_fleet_alertsseverity, kindSur un contrôleur : alertes de la page Sites, cette installation comprise

Les métriques adossées à la base de données (finalisation, sauvegarde, miroir) sont lues au plus toutes les 5 secondes. Lorsqu’une lecture échoue, le serveur omet ces métriques au lieu d’afficher d’anciennes valeurs, et arkvory_metrics_collection_failures_total augmente. Les métriques des sites gérés (arkvory_fleet_*) font exception : elles gardent la dernière lecture du contrôleur, afin qu’une lecture en échec ne remette pas à zéro la durée for des règles d’alerte des sites.

Le 99e centile des requêtes de gestion, sans les transferts de fichiers :

text
histogram_quantile(0.99, sum by (le) (rate(arkvory_http_request_duration_seconds_bucket{route!~".*(content|parts).*"}[10m])))

Arkvory n’exporte pas l’espace libre du volume de stockage ni celui de la base de données. Utilisez node_exporter pour les volumes et postgres_exporter pour PostgreSQL.

Journaux ​

L’API, le processus de traitement, l’agent de sauvegarde et les outils de maintenance écrivent un objet JSON par ligne sur la sortie standard. Le serveur n’écrit pas lui-même de fichiers de journal. Le gestionnaire de services de votre plateforme recueille les lignes.

InstallationOù lireRotation
Linux (paquets, install.sh)journalctl -u arkvory-api -u arkvory-worker -u arkvory-backup. La base de données gérée est arkvory-database, le programme de mise à jour est arkvory-updateDéfinie par journald
Windowslogs\arkvory-api.out.log, arkvory-worker.out.log, arkvory-backup.out.log dans la racine d’installation. La sortie d’erreur va dans les fichiers .err.log voisins. Le programme de mise à jour écrit logs\updater.log, le service de base de données écrit dans database\20 MiB par fichier, 5 anciens fichiers conservés
Docker Composedocker logs --tail 100 proanima-arkvory-api-1, et de même pour -worker-1 et -backup-120 MiB par fichier, 5 fichiers par conteneur

Un blocage termine un processus avec l’enregistrement process.stalled sur la sortie d’erreur, alors regardez aussi dans le fichier .err.log ou dans le journal. Voir Windows pour les autres fichiers de logs\.

Chaque ligne commence par les mêmes champs :

ChampValeur
timestampHeure UTC au format ISO 8601
leveldebug, info, warning ou error
serviceapi, worker, backup, migrate, gc ou scrub
version, pid, hostnameVersion, processus et hôte
componentapi, http, storage, worker, maintenance, backup, mirror, migrate, process ou diagnostics
codeLe nom de l’événement

Les autres champs proviennent d’une liste fixe : identifiants (requestId, traceId, jobId, uploadId, artifactId, repository, principal, clientIp), nombres (status, durationMs, bytesSent, bytesReceived, attempts) et champs de raison (errorCode, errorName, errno, sqlstate, reason). ARKVORY_LOG_LEVEL définit le niveau le plus bas qui est écrit.

Événements importants ​

Événement (code)NiveauSignification et première action
api.listeninginfoL’API sert les requêtes. Champs address, port et tls
startup.failederrorL’API n’a pas démarré. reason nomme la cause. Voir Dépannage
worker.unavailableerrorLe processus de traitement n’a pas démarré ou s’est arrêté sur une erreur
http.plaintext_exposedwarningL’API écoute sur une adresse non locale sans TLS et sans proxy de confiance
http.accessinfoUne ligne par requête terminée ou interrompue
le code d’erreur d’une requête, par exemple unavailable ou internalwarning pour les 4xx, error pour les 5xxUne requête échouée avec requestId, route, status et, pour les erreurs système, errorName, errno ou sqlstate
upload.input_timeout, upload.deadlinewarningUn téléversement a cessé d’envoyer des données, ou a duré plus longtemps que ARKVORY_UPLOAD_DEADLINE_MS
api.ownership_lost, worker.ownership_losterrorLa session de base de données qui prouve la propriété du stockage s’est rompue. Le processus se termine et redémarre
process.stallederrorLe watchdog a terminé un processus bloqué. Champ stalledSeconds
process.unhandlederrorUne erreur inattendue a terminé le processus
process.watchdog_failedwarningLe watchdog n’a pas pu démarrer. Le service fonctionne sans lui
drain.started, drain.settled, drain.timeout, api.stoppedinfo ou warningUn arrêt gracieux. drain.timeout signifie que des requêtes ont été coupées
tls.reloaded, tls.reload_failed, tls.expiringinfo ou warningLes fichiers de certificat ont été relus, n’ont pas pu être lus, ou expirent dans moins de 14 jours. tls.expiring se répète une fois par jour
completion.completed, completion.failed, completion.lease_lost, completion.attempts_exhaustedinfo ou errorLe résultat d’une tâche de finalisation de téléversement, avec jobId, uploadId et errorCode
backup.agent.started, backup.agent.standby, backup.agent.lease_lostinfo ou warningÉtat de l’agent de sauvegarde
backup.request.failed, backup.request.requeued, backup.failederror ou warningUne tâche de sauvegarde a échoué ou est exécutée de nouveau. Champ errorCode
mirror.step_failed, mirror.recoveredwarning ou infoUne étape de synchronisation de miroir a échoué (errorCode, attempts), ou fonctionne de nouveau
mirror.conflict_set_aside, mirror.conflict_resolvedwarning ou infoUn miroir a mis de côté une entrée de sa source à cause d’un conflit, ou l’a réessayée sans succès (artifactId, action, errorCode, attempts) ; ou l’entrée a été résolue
webhook.step_failed, webhook.recoveredwarning ou infoUne livraison de webhook a échoué (subscription, errorCode, attempts) ou refonctionne
migrate.started, migrate.completed, migrate.failedinfo ou errorLa migration de base de données d’une mise à jour
diagnostics.dropped, diagnostics.oversizedwarningDes lignes ont été écartées parce que le lecteur de journal est trop lent, ou une ligne était trop longue

Un lecteur de journal lent ne ralentit jamais un transfert. Lorsque la sortie est bloquée, le serveur écarte des lignes, les compte et écrit diagnostics.dropped avec le nombre une fois la sortie de nouveau libre. Une ligne de plus de 4096 caractères est remplacée par diagnostics.oversized. Les champs texte sont coupés à 256 caractères.

ID de requête ​

Chaque réponse porte l’en-tête X-Request-Id, et chaque corps d’erreur contient le champ requestId. La même valeur se trouve dans la ligne http.access, dans la ligne d’erreur, dans les lignes de la tâche de finalisation que la requête a lancée et dans les enregistrements d’audit. Un client qui signale un problème n’a besoin de vous donner que cette valeur.

bash
journalctl -u arkvory-api -u arkvory-worker --since "1 hour ago" -o cat | grep 'REQUEST_ID'
powershell
Select-String -Path "$root\logs\*.log" -Pattern 'REQUEST_ID'

Derrière un proxy inverse, le serveur ne reprend un X-Request-Id entrant que depuis une adresse figurant dans ARKVORY_TRUSTED_PROXIES, et uniquement s’il s’agit d’une valeur unique de 8 à 128 caractères (lettres, chiffres, ., _, : et -). Laissez le proxy réécrire l’en-tête, par exemple avec proxy_set_header X-Request-Id $request_id; dans nginx. Un en-tête traceparent W3C valide provenant d’un client quelconque devient le champ traceId. Il sert uniquement à la recherche et n’accorde jamais rien.

Ce qui n’est jamais journalisé ​

Le journal ne contient aucun mot de passe, clé, jeton, en-tête Authorization, corps de requête, chaîne de requête, URL ou texte d’exception. Les liens de téléchargement portent un secret dans la chaîne de requête, donc seul le modèle de route est journalisé. Le champ reason est le seul texte libre. Il est expurgé et coupé à 240 caractères. La ligne montre le principal (l’ID d’un compte ou d’une clé) et le clientIp. Traitez le journal comme des données personnelles.

ARKVORY_ACCESS_LOG=false désactive http.access. Les requêtes réussies vers /health/live et /health/status ne sont jamais journalisées. Les niveaux warning et error masquent aussi les lignes d’accès.

Diagnostics dans la console ​

Les administrateurs voient l’état du serveur dans la console sans passer par un shell. Voir La console web.

OùCe que vous voyez
SauvegardesLa ligne principale indique Sauvegardes en bon état, Attention requise et Intervention requise. En dessous se trouvent la sauvegarde Dernière sauvegarde, le Prochaine exécution, le Agent de sauvegarde, le Stockage des sauvegardes et la liste des avertissements avec l’action pour chacun
Mises à jourLa version installée et la dernière version, l’heure du dernier contrôle et l’état du programme de mise à jour de l’hôte
Stockage et nettoyage d’un dépôtL’utilisation du quota avec les états Le stockage approche de son quota. Revoyez la rétention et planifiez un nettoyage physique. et Le stockage atteint ou va atteindre son quota. Les nouvelles réservations qui dépassent le quota sont rejetées., et la liste Avertissements, erreurs et événements de stockage
Journal d’activité d’un compte de serviceQui a créé, modifié, émis ou révoqué quoi
La fiche du dépôtLe badge Miroir, avec l’état Miroir · erreur de synchronisation lorsque la dernière synchronisation a échoué

La liste Avertissements, erreurs et événements de stockage nécessite l’autorisation de lire les diagnostics. Entre autres événements, elle contient les requêtes échouées des clés de service dans ce dépôt, avec l’ID de requête, la route et le statut.

Les seuils de quota sont de 80 % pour l’avertissement et de 95 % pour l’état critique, sauf si un administrateur les a modifiés. Un dépôt sans quota n’a aucun seuil.

Avertissements de stockage et de disque ​

Le serveur conserve ARKVORY_STORAGE_RESERVE_BYTES (1 GiB par défaut) d’espace libre sur le volume de stockage pour la base de données, les journaux et le système. En dessous de cette réserve :

  • /health/ready signale "writable": false, mais répond quand même 200.
  • Les téléversements échouent avec 507 et la raison storage_full. Les téléchargements et la console continuent de fonctionner.

Le serveur ne mesure pas l’espace libre à votre place. Surveillez le volume de stockage, le volume de la base de données et le volume de sauvegarde avec vos propres outils, et alertez avant que la réserve ne soit atteinte. La réserve n’est pas un quota. ARKVORY_CAPACITY_BYTES limite la somme du contenu réservé et n’est pas un contrôle de disque. Voir Stockage.

État des sauvegardes ​

L’agent de sauvegarde envoie un battement de cœur à chaque renouvellement de bail. L’API transforme le battement de cœur et l’historique des tâches de sauvegarde en avertissements dotés de codes fixes. Voir Sauvegardes pour ce que chaque code vous demande de faire.

CodeGravitéCondition
agent_offlinecriticalAucun battement de cœur pendant 2 minutes
backup_stalecriticalLe point le plus récent date de plus de 26 heures et le plan est actif
vault_unavailablecriticalLe volume du coffre n’est pas monté, n’a pas de vault.json ou ne peut pas être écrit
verify_failedcriticalUn point de restauration a échoué à sa vérification
vault_not_configured, schedule_disabled, no_backup_yet, last_run_failedwarningPas de coffre, plan désactivé, aucune première sauvegarde, dernière sauvegarde échouée
vault_low_spacewarningLe coffre a moins de 10 % d’espace libre, ou moins du double des nouveaux octets du dernier point
never_deep_verifiedwarningAucune vérification complète depuis plus de 8 jours

La métrique arkvory_backup_warnings porte les mêmes codes. L’âge d’une sauvegarde se compte à partir de son heure d’instantané, et non du moment où elle s’est terminée.

Alertes suggérées ​

La version contient des règles Prometheus prêtes dans releases/<version>/deploy/monitoring/arkvory-alerts.yml. Ajoutez le fichier à rule_files dans prometheus.yml. Les seuils sont des points de départ. Ajustez-les selon le trafic que vous mesurez.

AlerteConditionGravité
ArkvoryDownLe scrape échoue pendant 2 minutesCritique
ArkvoryHighServerErrorRatePlus de 5 % des réponses sont des 5xx pendant 10 minutesAvertissement
ArkvorySlowMetadataRequestsLe 99e centile des requêtes de gestion dépasse 2 s pendant 15 minutesAvertissement
ArkvoryCompletionBacklogLa plus ancienne tâche de finalisation en file attend plus de 10 minutesAvertissement
ArkvoryTransferAdmissionRejectionsPlus de 0,1 transfert refusé ou expiré par seconde pendant 15 minutesAvertissement
ArkvoryDiagnosticsDroppedDes lignes de journal ont été écartées dans les 15 dernières minutesAvertissement
ArkvoryMetricsCollectionFailingUne métrique adossée à la base de données n’a pas pu être lueAvertissement
ArkvoryTlsCertificateExpiring, ArkvoryTlsCertificateExpiredLe certificat intégré expire dans moins de 14 jours, ou a expiréAvertissement, critique
ArkvoryBackupStaleLe point le plus récent date de plus de 26 heuresCritique
ArkvoryBackupAgentOfflineAucun battement de cœur pendant plus de 2 minutes, pendant 5 minutesCritique
ArkvoryBackupWarningvault_unavailable ou verify_failed pendant 10 minutesCritique
ArkvoryMirrorStaleUn miroir n’a pas rattrapé sa source pendant une heureAvertissement
ArkvoryMirrorFailingLa dernière synchronisation d’un miroir a échoué, pendant 15 minutesAvertissement
ArkvoryMirrorConflictsUn miroir a des entrées de sa source mises de côté, pendant 30 minutesAvertissement
ArkvoryRestartLoopLe processus de l'API a redémarré 3 fois ou plus en 30 minutesAvertissement
ArkvoryWebhookFailingUne livraison de webhook échoue depuis 15 minutesAvertissement
ArkvoryFleetSiteDownUn site géré ne répond pas au contrôleur pendant 5 minutesCritique
ArkvoryFleetMirrorBehindLe retard d’un miroir d’un site géré atteint ou dépasse ARKVORY_FLEET_LAG_ALERT (1000 par défaut) pendant 30 minutesAvertissement
ArkvoryFleetCriticalLa page Sites du contrôleur affiche des alertes critiques pendant 5 minutesCritique

Ajoutez vous-même ces alertes, car Arkvory n’exporte pas les données :

AlerteSourcePourquoi
Espace libre des volumes de stockage, de base de données et de sauvegardenode_exporterUn disque plein arrête les téléversements, la base de données et les sauvegardes
PostgreSQL est arrêté ou a trop de connexionspostgres_exporterL’API se termine et redémarre tant que la base de données est absente
L’état public n’est pas readyUne sonde externe de /health/statusLe chemin réseau, le proxy et le certificat, vus depuis un client

Pour les volumes et pour PostgreSQL, la version contient des règles prêtes pour node_exporter et postgres_exporter dans deploy/monitoring/arkvory-host-alerts.yml. Remplacez les expressions mountpoint par vos propres volumes avant de charger le fichier.

Testez une alerte une fois. Par exemple, arrêtez arkvory-backup : ArkvoryBackupAgentOffline se déclenche environ 7 à 8 minutes plus tard (2 minutes sans battement de cœur, 5 minutes dans la règle, plus l’intervalle de scrape).

Arkvory · ProAnimaStudio