Cette page est une traduction automatique de la page en anglais, qui fait foi. Lire la page en anglais
Exécuter le serveur : démarrage, arrêt et contrôles de santé
Comment démarrer et arrêter le serveur, obtenir son image et le surveiller pendant son fonctionnement : métriques, traces, file de tâches et contrôles de santé.
Démarrer le serveur
Section intitulée « Démarrer le serveur »my config check # report every configuration problem at oncemy config check -instance # also warn about instance settings that are not set (opens the database)my serve # start according to the configured role (-config <file> reads a TOML file)my version # print the version of the binarymy serve valide la configuration, construit les adaptateurs de base de données, de file de jobs et de gestion des clés, et accepte le HTTP sur listen.
Avec tls = off, la valeur par défaut, il y parle en HTTP/1.1 simple : placez devant lui un proxy inverse ou un répartiteur de charge qui termine le HTTPS (et le HTTP/2 ou HTTP/3 pour les clients) et transmet en HTTP/1.1.
Pour servir le HTTPS sans proxy, voir Servir le HTTPS depuis le serveur.
Les mises à jour en temps réel (GET /api/v1/streaming, les flux des fils local et fédéré, et les flux des salons de chat vocal) sont des réponses de longue durée qui envoient un commentaire de présence toutes les 30 secondes (15 pour un salon vocal) et restent ouvertes tant qu’elles sont inactives.
Le proxy ne doit pas mettre ces réponses en mémoire tampon (nginx : le serveur envoie X-Accel-Buffering: no), et son délai d’inactivité ou de lecture doit être plus long que l’intervalle de présence.
Il n’applique pas le schéma ni n’exécute les étapes de mise à niveau des données : exécutez my schema apply puis my db upgrade avant de démarrer (voir Base de données ; les mises à niveau exécutent les deux dans le cadre de Mettre à niveau). Tant que my db upgrade n’a pas enregistré chaque étape de la version, /readyz répond 503.
Dans la configuration Docker Compose (deploy/docker/compose.yaml ; voir Déployer avec Docker Compose), les services ponctuels schema et upgrade exécutent my schema apply et my db upgrade avant le démarrage du serveur.
Si le schéma n’est pas appliqué, le processus démarre quand même et la disponibilité renvoie 503, et il ne sert rien d’autre tant que le schéma n’est pas là.
Le premier my serve ou la première commande my qui utilise la base de données y enregistre host et account_domain. Lorsque la configuration diffère des valeurs enregistrées, my serve journalise start failed avec les deux paires de valeurs et se termine avec le code 1, et les commandes affichent la même erreur. Les exceptions sont my schema apply et my db backup, qui ne vérifient pas, et le mode maintenance, qui ne lit pas la base de données. my config check -instance et my db upgrade -check vérifient mais n’enregistrent rien.
Un processus qui n’a pas pu lire la base de données à son démarrage n’est pas prêt tant qu’il ne le peut pas, et d’ici là il n’exécute aucun job et répond 503 avec Retry-After à chaque requête sauf les vérifications de santé (/healthz, /readyz, /health/live, /health/ready, /api/v1/instance/health). C’est aussi ce que fait un serveur démarré avant my schema apply. S’il trouve ensuite des valeurs différentes, il s’arrête avec la même erreur.
Dans le profil production, my config check vérifie aussi que les paramètres valides conviennent à une instance de production : les erreurs, comme un host que les autres serveurs ne peuvent pas atteindre ou une KEK qui n’est pas aléatoire, le font se terminer avec 1, et les avertissements, comme mail = none, non.
my serve journalise les deux comme des avertissements au démarrage mais démarre quand même ; exécutez donc my config check dans le cadre du déploiement.
La liste de contrôle de production liste les vérifications et ce qu’il faut vérifier à la main avant la mise en service.
role |
HTTP | Worker de jobs |
|---|---|---|
all (par défaut) |
Toutes les routes | S’exécute |
web |
Toutes les routes | Ne s’exécute pas |
worker |
Vérifications de santé uniquement (pour les sondes de la plateforme) | S’exécute |
Les journaux vont sur l’erreur standard en JSON Lines. Chaque ligne a level (DEBUG, INFO, WARN, ERROR) et severity, le même niveau sous la forme que lit Cloud Logging (DEBUG, INFO, WARNING, ERROR, et CRITICAL pour une erreur qui arrête le processus).
Les journaux écrits pendant le traitement d’une requête portent un request_id, et le même ID est renvoyé dans l’en-tête de réponse X-Request-Id.
Si le X-Request-Id de la requête compte au plus 128 caractères parmi les lettres, les chiffres et -_.:, il est utilisé tel quel, comme l’ID attribué par un répartiteur de charge.
Les journaux à l’intérieur d’une trace (requêtes et jobs) portent aussi trace_id et span_id (voir Traces).
Chaque requête HTTP et chaque exécution de job écrit une ligne à sa fin. La ligne a les mêmes noms et valeurs que les étiquettes des métriques ci-dessous ;
sur Cloud Run avec metrics_exporter = none, vous pouvez donc construire à partir de ces lignes des métriques basées sur les journaux de Cloud Logging (compteurs et distributions).
Ligne (msg) |
Champs |
|---|---|
http request (INFO ; les vérifications de santé utilisent DEBUG) |
http.request.method, http.route, my.surface et http.response.status_code (un nombre) ont les mêmes valeurs que les étiquettes de http.server.request.duration. Aussi duration_seconds (un nombre de secondes), url.path (le chemin sans la chaîne de requête), http.response.body.size et request_id. http.route et my.surface sont absents pour les requêtes qui n’ont atteint aucune route (vérifications de santé, requêtes refusées avant le routage), et la métrique ne les compte pas. Une requête dont le client est parti avant que le serveur puisse répondre a l’état 499 au lieu d’un 5xx, sauf si un gestionnaire a paniqué ; le client n’a rien reçu, ce qui ne compte donc pas comme une erreur du serveur |
job (INFO en cas de succès et pour postponed, WARN pour retry, ERROR pour dead) |
my.job.type et my.outcome ont les mêmes valeurs que les étiquettes de my.job.duration. Aussi duration_seconds (my.job.duration), wait_seconds (my.job.wait), job_id, attempt, et error en cas d’échec |
error report (ERROR ; CRITICAL pour un échec qui arrête le processus) |
Une ligne par erreur signalée (Signalements d’erreurs) |
Rapports d’erreurs
Section intitulée « Rapports d’erreurs »Le guide Rapports d’erreurs explique où lire ces lignes sur chaque plateforme, l’écran Erreurs, les notifications, et l’envoi de rapports à un outil de suivi d’erreurs.
Le serveur signale les erreurs qui demandent l’attention de l’exploitant sous la forme d’une ligne error report chacune :
- une panique dans un gestionnaire HTTP, une tâche ou une tâche d’arrière-plan ;
- une erreur derrière une réponse 5xx de l’API cliente, de l’API d’administration, des pages de connexion, d’ActivityPub, d’OAuth ou des médias ;
- une tâche qui échoue définitivement (
dead) : elle a épuisé ses nouvelles tentatives, ou a refusé de s’exécuter de nouveau. Les envois qui ont abandonné parce que l’autre serveur échouait sans cesse ne sont pas signalés ; - un échec de démarrage : une configuration invalide, ou une base de données ou un adaptateur qui ne peut pas être mis en place.
Les réponses 4xx, les nouvelles tentatives de tâches, le mode de maintenance, les vérifications de disponibilité échouées, les requêtes dont le client est parti et les échecs causés par d’autres serveurs ne sont pas signalés ; les métriques et les autres lignes de journal les couvrent.
Lorsque le client d’une requête s’en va, les autres lignes d’erreur du serveur pour cette requête sont écrites à INFO au lieu de ERROR, puisque la plupart d’entre elles disent seulement que la requête a été annulée.
La ligne est sous la forme que lit Google Cloud Error Reporting : sur Cloud Run, les rapports apparaissent dans Error Reporting regroupés comme des erreurs sans aucune configuration. Sur les autres plateformes, c’est une simple ligne JSON :
| Champ | Valeur |
|---|---|
@type, serviceContext |
Le type d’événement Error Reporting, et {"service": "my", "version": "<version>"} |
my.error.fingerprint |
32 chiffres hexadécimaux identiques pour chaque occurrence de la même erreur : construits à partir de la source, du lieu, du type d’erreur et des fonctions du serveur dans la pile, sans numéros de ligne |
my.error.source, my.error.kind |
server (ou web), et panic ou error |
my.error.where |
Où cela s’est produit : <surface> <method> <route> pour une requête (comme client_api GET /api/v1/statuses/{id}), le type de tâche pour une tâche, le nom de la tâche pour une tâche d’arrière-plan, startup pour un échec de démarrage |
my.role, deployment.environment.name |
Le role du processus et errors_environment |
request_id, job_id, attempt, trace_id, span_id |
Les ID permettant de retrouver les lignes de requête ou de tâche de la même erreur, lorsqu’elle en a |
context.httpRequest |
Pour une erreur de requête : method, url (la route, comme /api/v1/statuses/{id}, jamais le chemin demandé par le client) et responseStatusCode, le statut répondu (500) |
message |
En dernier sur la ligne : <type>: <message>, un saut de ligne, puis la pile Go |
Avant qu’un rapport quitte le processus, le message voit ses URL, adresses e-mail, identifiants @user@host, adresses IP, UUID et ULID, et nombres de 10 chiffres ou plus remplacés par <url>, <email>, <acct>, <ip>, <id> et <n>, et il est coupé à 1 KiB.
La pile conserve ses positions de fichier mais pas les valeurs d’arguments de ses lignes de fonction (elles sont affichées comme (...)), et est coupée à 16 KiB. Aucun rapport ne porte de corps de requête, d’en-tête, de requête, de cookie, de compte, de nom d’utilisateur, d’adresse IP ni de User-Agent.
Aucune autre ligne ne porte de pile ; Error Reporting ne trouve donc que les piles de ces lignes.
Un nom de champ est une clé unique qui contient . ; il n’est pas imbriqué. Mettez-le entre guillemets dans les filtres et extractions de Cloud Logging (par exemple jsonPayload."http.route", et EXTRACT(jsonPayload.duration_seconds) pour une valeur de distribution).
Les champs utilisés comme libellés ne prennent leurs valeurs que dans un ensemble fini ; url.path, request_id et job_id ne sont jamais des libellés.
Avec metrics_exporter = emf, ces deux lignes sont les lignes EMF elles-mêmes. La ligne http request porte la valeur de http.server.request.duration, et la ligne job porte les valeurs de my.job.duration et my.job.wait (clés nommées d’après les métriques), plus la directive _aws, service.name, service.version et my.role. Ces trois métriques ne sont écrites sur aucune autre ligne. Les champs que vous choisissez dans metrics_emf_dimensions sont écrits sous forme de chaînes, comme l’exige EMF (par exemple la dimension http.response.status_code vaut "200").
Les journaux vont vers la sortie d’erreur standard et les autres lignes EMF vers la sortie standard. Le pilote de journaux awslogs d’ECS envoie les deux à CloudWatch Logs ; les métriques sont donc extraites des deux.
Fichiers Docker Compose
Section intitulée « Fichiers Docker Compose »deploy/docker/ contient ce qui déploie une instance. compose.yaml s’exécute seul, et les autres fichiers s’empilent par-dessus.
| Fichier | Ajoute | À utiliser lorsque |
|---|---|---|
compose.yaml |
Le serveur et ses services ponctuels de base de données, sur SQLite et des fichiers de médias dans le volume data |
Toujours |
compose.postgres.yaml |
PostgreSQL dans un conteneur, dans le volume postgres |
Vous voulez PostgreSQL sur cette machine. Pour un serveur PostgreSQL ailleurs, omettez-le et définissez MY_DATABASE et MY_DATABASE_URL dans .env |
compose.s3.yaml |
Les médias dans un bucket compatible S3 ; avec COMPOSE_PROFILES=garage aussi un stockage Garage à un nœud dans le volume garage |
Les médias dépassent un disque, ou vous les voulez dans un bucket. Sans le profil, le stockage est l’externe défini par les paramètres MY_BLOB_S3_* |
compose.caddy.yaml |
Caddy, avec des certificats TLS sur les ports 80 et 443 | MY_HOST est un domaine public et rien d’autre ne termine le TLS sur cette machine |
compose.build.yaml |
Construit l’image à partir d’une copie du dépôt | Vous exécutez votre propre construction |
Choisissez la base de données et le stockage des médias avant le premier démarrage : les données ne se déplacent pas d’elles-mêmes lorsque les fichiers changent (Sauvegarder montre ce qui doit être déplacé).
Empilez les fichiers avec des options -f dans cet ordre, ou nommez-les une fois dans .env, afin que chaque commande docker compose ultérieure
(exec, logs, pull, et celles des autres guides) utilise les mêmes fichiers :
cd deploy/dockercp example.env .env# In .env: COMPOSE_FILE=compose.yaml:compose.postgres.yaml:compose.caddy.yamlUn fichier nommé compose.override.yaml dans le répertoire n’est lu que lorsque ni -f ni COMPOSE_FILE ne nomment de fichiers. Avec
eux, listez-le aussi.
Paramètres. Copiez example.env vers .env. Compose lit .env pour renseigner les variables de ses fichiers, et transmet tout le
fichier aux conteneurs du serveur ; chaque paramètre de la référence de la configuration fonctionne donc
en étant défini à cet endroit. Le modèle les liste tous, avec une phrase pour chacun.
- La clé de chiffrement de clés reste hors de
.env, dans le fichiersecrets/kek, et les conteneurs la lisent comme le secret Docker/run/secrets/my_kek, de sorte qu’elle ne devient jamais une variable d’environnement. Une ligneMY_KEKdans.envarrête le serveur, qui refuseMY_KEKetMY_KEK_FILEensemble (gérer la clé). - Le serveur s’exécute sous l’utilisateur
65532, et Compose monte le fichier avec les permissions qu’il a ; le fichier doit donc être lisible par d’autres. Conservez-le dans un répertoire que vous seul pouvez ouvrir, comme le font les commandes deexample.env. - Les autres secrets parviennent aux conteneurs sous forme de variables d’environnement. Pour en passer un sous forme de fichier à la place, montez-le avec un secret
dans un
compose.override.yamlà vous et définissez son<NAME>_FILE, commecompose.yamlle fait pour la clé. .envcontient des secrets :chmod 600 .env, et conservez-en une copie avec vos sauvegardes.MY_LISTENreste:8080, puisque les fichiers se connectent à ce port, sauf si le serveur sert lui-même le HTTPS (Servir le HTTPS depuis le serveur).
TLS avec Caddy. Définissez MY_HOST sur un domaine dont le DNS pointe vers la machine, avec les ports 80 et 443 accessibles depuis
Internet, et retirez MY_WEB_ORIGIN de .env. Caddy obtient et renouvelle le certificat tout seul à la première requête.
Le serveur fait confiance au X-Forwarded-For des plages d’adresses par défaut de Docker ; définissez MY_TRUSTED_PROXIES si les vôtres diffèrent.
Le Garage inclus. compose.s3.yaml avec COMPOSE_PROFILES=garage a besoin des valeurs que example.env liste en tête.
Le service ponctuel garage-init prépare le stockage à chaque up. Il reste à l’intérieur du réseau Compose, puisque le serveur
sert lui-même les médias. Un nœud, c’est un disque : sauvegardez le volume garage ou le bucket (Sauvegarder).
Servir le HTTPS depuis le serveur
Section intitulée « Servir le HTTPS depuis le serveur »my peut servir lui-même le HTTPS, de sorte qu’une petite machine exécute tout le serveur sous forme d’un seul binaire avec un domaine et les ports 80 et 443,
sans proxy inverse. Avec tls = acme, il obtient ses certificats auprès d’une autorité de certification ACME comme Let’s
Encrypt. Avec tls = files, il sert un certificat et une clé que vous fournissez et que vous tenez à jour avec un autre outil, comme
certbot.
MY_TLS=acmeMY_TLS_ACME_AGREE_TERMS=true # you agree to the terms of service of the certificate authority# MY_TLS_ACME_EMAIL=ops@social.example optional contact of the account# MY_LISTEN=:443 the default with tls other than off# MY_TLS_HTTP_LISTEN=:80 the default; empty opens no port 80MY_TLS=filesMY_TLS_CERT_FILE=/etc/letsencrypt/live/social.example/fullchain.pemMY_TLS_KEY_FILE=/etc/letsencrypt/live/social.example/privkey.pem- Ports. Le serveur sert le HTTPS sur
listen(:443par défaut dès quetlsn’est pasoff). Surtls_http_listen(:80par défaut), il redirige par301les requêtesGETetHEADvers le même chemin enhttps, et répond400à toute autre méthode, de sorte qu’aucun corps de requête ne circule en clair. - Hôtes. Le serveur sert
host, et l’hôte deweb_originlorsqu’il diffère. Une négociation pour tout autre nom échoue sans certificat, et ne fait jamais commander un certificat au serveur. - Connexions. TLS 1.2 ou ultérieur avec les suites de chiffrement par défaut de Go, HTTP/2 et HTTP/1.1, au plus 64 KiB d’en-têtes
de requête, et au plus 100 flux concurrents sur une connexion HTTP/2. Les délais sont ceux du HTTP simple. Le serveur
ajoute toujours
Strict-Transport-Securityà chaque réponse (En-têtes de sécurité). - Rôles. Seuls les rôles
webetallécoutent avec TLS. Unworkersert ses vérifications de santé en HTTP simple surlisten(:8080par défaut) et n’ouvre pas de port 80. - Adresses des clients. Sans proxy devant, le pair de la connexion est le client : laissez
trusted_proxiesvide. Ne le définissez que lorsqu’un CDN placé devant se connecte au serveur enhttps. - Mode maintenance.
my serve -maintenancene lit nitlsni les certificats et répond en HTTP simple surlisten(:8080sauf si vous le définissez) ; dirigez doncMY_LISTENet votre pare-feu vers ce port pendant son exécution, ou conservez un proxy inverse pour la maintenance.
Certificats d’une autorité de certification ACME
Section intitulée « Certificats d’une autorité de certification ACME »Avec tls = acme, le serveur commande un certificat pour chacun de ses hôtes qui n’en a pas, auprès de l’autorité de certification
à tls_acme_directory (Let’s Encrypt par défaut).
- Avant de commencer.
hostdoit être un nom DNS qui pointe vers le serveur, et les ports 443 et 80 doivent être accessibles depuis Internet : l’autorité de certification vérifie que le serveur contrôle le nom en s’y connectant. Il répond surlisten(le défi TLS-ALPN-01) ou surtls_http_listen(le défi HTTP-01) ; untls_http_listenvide fonctionne donc avec le seul port 443. Les certificats génériques et la validation par enregistrements DNS ne sont pas disponibles. - Premier démarrage. Le serveur commence à écouter sans attendre de certificat, puis les commande. Tant qu’un hôte n’a pas son
certificat, une négociation pour lui échoue ; avec Let’s Encrypt, les premiers certificats arrivent généralement en moins d’une minute. Le journal
indique
obtained a TLS certificatepour chaque hôte, etthe TLS certificate could not be obtainedavec la raison lorsqu’une commande échoue. - Renouvellements. Le serveur renouvelle chaque certificat à l’heure que l’autorité de certification suggère pour lui (ACME Renewal
Information) : il choisit une fois une heure aléatoire dans la fenêtre suggérée, la conserve tant que la fenêtre reste, et redemande
comme l’indique le
Retry-Afterde l’autorité, au moins toutes les 12 heures, de sorte qu’une autorité qui doit remplacer des certificats plus tôt puisse déplacer la fenêtre. Lorsque l’autorité ne propose pas une telle fenêtre, le serveur renouvelle après les deux tiers de la durée de vie du certificat, ou après la moitié pour un certificat valable moins de 10 jours. Un renouvellement indique à l’autorité quel certificat il remplace, ce qui le maintient hors des limites de débit de Let’s Encrypt. Le certificat actuel reste en service jusqu’à l’arrivée de son renouvellement, et un renouvellement qui échoue attend comme une première commande. - Commandes en échec. Après une commande en échec, le serveur attend avant la suivante pour le même hôte : 1 minute après le premier échec, 10 minutes après le deuxième, 100 minutes après le troisième, puis un jour, afin de rester dans les limites de l’autorité de certification. L’attente est conservée dans la base de données et survit aux redémarrages. Corrigez la cause (DNS, pare-feu, port) et la commande suivante part à la fin de l’attente.
- Où ils sont conservés. Le compte auprès de l’autorité de certification, les certificats et l’enregistrement de chaque commande sont conservés dans la base de données ; les clés privées sont scellées avec la clé de chiffrement de clés, comme les autres secrets (gestion des clés). Une sauvegarde de la base de données les inclut, et un serveur redémarré sert les certificats stockés aussitôt, sans commander. Changer la clé de chiffrement de clés les ré-enveloppe ; cela ne commande pas de nouveaux certificats.
- Plusieurs processus. Les processus qui partagent la base de données et le magasin
kvse coordonnent : l’un commande le certificat d’ un hôte pendant que les autres attendent puis le chargent, et le processus auquel l’autorité de certification se connecte répond à sa vérification. Utilisezkv = dboukv = valkey;kv = memoryest refusé sauf si un seul processus exécute tout (role = all). Le processus qui obtient un certificat en informe les autres par le courtierstream, et ils le servent en quelques secondes ; chaque processuswebavectls = acmereste donc à l’écoute du courtier. Avecstream = hub, ou lorsqu’un avis est perdu, chaque processus relit quand même les certificats actuels dans la base de données toutes les 5 minutes, et chaque minute une fois que son certificat a atteint son heure de renouvellement, de sorte qu’un renouvellement les atteint bien avant l’expiration de l’ancien certificat. - Profils.
tls_acme_profilechoisit un profil que l’autorité de certification propose, commeshortlivedchez Let’s Encrypt. Vide, il prend sa valeur par défaut. Après un changement de profil, le prochain renouvellement le suit, et le certificat qu’il apporte est servi même s’il expire avant celui qu’il remplace.
Pour l’essayer sans dépenser les limites de l’environnement de production de Let’s Encrypt, commencez avec son environnement de test (staging), qui émet des certificats auxquels les navigateurs ne font pas confiance, sous des limites bien plus élevées :
MY_TLS_ACME_DIRECTORY=https://acme-staging-v02.api.letsencrypt.org/directoryUne fois que le journal indique que les certificats ont été obtenus et que curl -kv https://social.example/ montre un certificat issu de
(STAGING), retirez le paramètre et redémarrez. Le serveur enregistre un nouveau compte auprès de l’environnement de production et
y commande ses certificats ; ceux du test restent dans la base de données et ne sont plus servis.
Certificats issus de fichiers
Section intitulée « Certificats issus de fichiers »Avec tls = files, tls_cert_file contient d’abord le certificat du serveur, puis ses intermédiaires (le fullchain.pem de certbot) ; tls_key_file contient sa clé. Le certificat doit couvrir host, et il sert aussi l’hôte de
web_origin lorsqu’il diffère et que le certificat le couvre.
Le serveur regarde chaque minute les dates de modification des deux fichiers et les recharge lorsque l’un change, sans redémarrage. Une paire qui ne correspond pas encore (un nouveau certificat avant sa nouvelle clé) maintient le certificat précédent en service jusqu’à la vérification suivante, et le journal en indique la raison.
Commandes et métriques
Section intitulée « Commandes et métriques »my tls affiche et contrôle les certificats avec la configuration du serveur, depuis toute machine qui atteint la
base de données (la CLI d’administration) :
my tls status # each host: certificate, renewal, latest ordersmy tls renew -host social.example # order now, without waitingmy tls revoke -host social.example -reason key_compromisestatusaffiche, pour chaque hôte, le certificat actuel (son numéro de série, son émetteur et son expiration), la date de son renouvellement (la fenêtre de l’autorité de certification, ou l’heure dérivée de sa durée de vie), le nombre de commandes consécutives qui n’en ont obtenu aucun, et les dernières commandes avec leurs erreurs. Avectls = files, il affiche le certificat detls_cert_file.renewcommande un certificat maintenant, en ignorant l’heure de renouvellement et l’attente après des commandes en échec : exécutez-le une fois que vous avez corrigé la cause des commandes en échec. Le serveur en cours d’exécution répond à la vérification de l’autorité de certification ; il doit donc être démarré, et ses processus servent le nouveau certificat en quelques secondes, ou en 5 minutes avecstream = hub.revokecommande d’abord un certificat qui remplace l’actuel, puis demande à l’autorité de certification de révoquer l’actuel et l’enregistre ; chaque processus cesse de servir le certificat révoqué en quelques secondes, ou en 5 minutes avecstream = hub. Utilisezkey_compromiselorsque la clé privée peut être connue d’autres personnes,supersededouoperatorsinon. Lorsque le remplaçant ne peut pas être commandé, la révocation a quand même lieu : les processus servent le certificat précédent de l’hôte s’il n’est pas révoqué, ou rien jusqu’à ce que le serveur en obtienne un nouveau.renewetrevokeexigenttls = acmeet unkvautre quememory, puisque les processus auxquels l’autorité de certification se connecte lisent les réponses à ses vérifications dans le magasinkv. Avectls = files, ils sont refusés : renouvelez ou révoquez le certificat avec l’outil qui écrit les fichiers.
Avec metrics_exporter défini, mettez en place une alerte sur my.tls.certificate.expiry sous 7 jours et sur
my.tls.order.consecutive_failures de 3 ou plus (alertes) : un renouvellement en échec se voit
des semaines avant l’expiration du certificat.
Vérifications et exécution
Section intitulée « Vérifications et exécution »my config check signale, avec tls = acme, des conditions non acceptées, un host qui est une adresse IP, localhost,
ou un nom sans point, un tls_acme_directory qui n’est pas une URL https, et kv = memory avec un role autre que
all, comme des erreurs. Avec tls = files, il signale comme des erreurs un certificat ou une clé illisible, une clé qui ne correspond pas au
certificat, et un certificat qui ne couvre pas host, a expiré ou n’est pas encore valide, et avertit lorsqu’il reste
moins de 14 jours. Il avertit lorsque trusted_proxies est défini avec tls autre que off. Avec tls = off, il avertit
lorsque listen est le port 80 ou 443 sur une adresse autre que loopback, puisque rien ne semble terminer le TLS devant le
serveur ; le serveur journalise le même avertissement une fois par démarrage lorsqu’un tel serveur, avec trusted_proxies vide, reçoit une requête HTTP simple
d’une adresse autre que loopback.
systemd. Les ports inférieurs à 1024 exigent une capacité pour un utilisateur autre que root. Donnez-la au service et à rien d’autre :
[Service]User=myAmbientCapabilities=CAP_NET_BIND_SERVICECapabilityBoundingSet=CAP_NET_BIND_SERVICEAvec tls = files, l’utilisateur doit aussi pouvoir lire les fichiers de certificat. Avec certbot, ses répertoires live et archive
ne sont lisibles que par root : donnez au groupe du service l’accès (chgrp et chmod g+rx sur les répertoires, g+r sur
les clés), ou copiez les fichiers dans un hook de déploiement vers un répertoire que le service lit.
Docker. Docker 20.10 et les versions ultérieures laissent un conteneur ouvrir des ports inférieurs à 1024 sans capacité, de sorte que l’image fonctionne telle
quelle. L’image définit MY_LISTEN=:8080 ; définissez donc MY_LISTEN=:443 dans .env, et publiez les deux ports dans un
compose.override.yaml (ports: ["80:80", "443:443"]). Avec tls = files, montez les fichiers de certificat en lecture seule
là où pointent MY_TLS_CERT_FILE et MY_TLS_KEY_FILE ; le serveur s’exécute sous l’utilisateur 65532, qui doit pouvoir les lire.
Avec tls = acme, il n’y a rien à monter : les certificats vivent dans la base de données.
Omettez compose.caddy.yaml, qui prendrait les mêmes ports. Cela ne vaut pas avec network_mode: host, où
le conteneur partage le réseau de la machine et a besoin de la même capacité qu’un service hors conteneur.
Comparé à Caddy. Servir le HTTPS depuis my renonce au HTTP/3, à la compression des réponses (le serveur envoie les fichiers du
client web compressés et ne compresse rien d’autre), à un journal d’accès propre (les lignes de journal http request du serveur subsistent), et aux certificats validés par
DNS, y compris les certificats génériques. Conservez compose.caddy.yaml, ou un autre proxy, lorsque vous avez besoin de l’un d’eux.
Obtenir l’image
Section intitulée « Obtenir l’image »L’image du serveur est ghcr.io/mycroblog/my, publique, pour linux/amd64 et linux/arm64, avec tous les adaptateurs.
| Tag | Pointe vers | À utiliser pour |
|---|---|---|
0.1.0 |
Cette version, définitivement | Nommer une version |
0.1 |
Le dernier correctif de v0.1 |
Docker Compose, qui applique le schéma à chaque up |
0.1.0-rc.1 |
Cette préversion | Essayer une version avant sa sortie |
nightly |
Le dernier commit de main qui a passé les tests nocturnes, déplacé chaque nuit où il change |
Essayer des changements avant une préversion, sur une instance que vous pouvez jeter |
Il n’y a ni latest ni 0 : les deux franchiraient une version mineure, et chaque mise à niveau vers une nouvelle version mineure doit passer par la précédente. Nommez une version dans chaque commande ; docker pull ghcr.io/mycroblog/my seul échoue avec manifest unknown.
Une version corrective peut aussi avoir besoin de my schema apply et de my db upgrade ; en dehors de Docker Compose, suivez donc Mise à niveau pour chaque version. En production, épinglez le condensat que donnent les notes de la version :
ghcr.io/mycroblog/my:0.1.0@sha256:...nightly n’a aucun chemin de mise à niveau. Les mises à niveau ne sont promises qu’entre versions publiées : d’une image nightly à la suivante, ou de nightly à une version, le schéma et les étapes de données de my db upgrade peuvent changer d’une façon par laquelle aucune version ne passe ; attendez-vous donc à recréer sa base de données. Ne l’exécutez jamais en production. my version indique de quel commit il s’agit, comme dans v0.1.0-rc.5.0.20261109182600.g7a789720a1b2 : une version postérieure à la dernière publiée (v0.1.0-rc.5), l’heure du commit en UTC, et les 12 premiers caractères du commit après g. Pour conserver un build, épinglez son condensat (ghcr.io/mycroblog/my:nightly@sha256:...) : un build plus ancien perd le tag mais reste récupérable par son condensat.
Où l’exécuter :
- Docker Compose :
deploy/docker/compose.yamlexécute l’image deMY_VERSIONdans.env(fichiers Docker Compose). Pour la construire plutôt depuis un checkout, ajoutez la surchargecompose.build.yaml(docker compose -f compose.yaml -f compose.build.yaml up -d --build), et définissezMY_VERSIONsur un nom à vous, puisqu’il nomme votre image locale et c’est ce qu’affichemy version. - Kubernetes : récupérez-la depuis
ghcr.iotelle quelle. - Cloud Run : utilisez directement l’image
ghcr.io. Un déploiement résout le tag en condensat. - AWS (ECS, EKS) : copiez l’image dans Amazon ECR, ou utilisez un pull through cache d’ECR, qui nécessite des identifiants ghcr.io.
Vérifier une image
Section intitulée « Vérifier une image »Chaque image publiée a une provenance signée via Sigstore, qui lie le condensat au workflow et au commit qui l’ont construite, ainsi qu’un SBOM. Avec la CLI GitHub, et connecté à ghcr.io si la commande le demande :
gh attestation verify oci://ghcr.io/mycroblog/my@sha256:... -R mycroblog/my \ --signer-workflow mycroblog/my/.github/workflows/release.ymldocker buildx imagetools inspect ghcr.io/mycroblog/my@sha256:... --format '{{ json .SBOM }}'La première commande échoue sauf si l’image a été construite par le workflow de publication de ce dépôt. Pour une image nightly, vérifiez-la plutôt avec --signer-workflow mycroblog/my/.github/workflows/nightly.yml. Elle affiche le commit, qui est celui du tag de la version ; le label org.opencontainers.image.revision de l’image nomme le même.
Publier le code source (AGPL-3.0)
Section intitulée « Publier le code source (AGPL-3.0) »my est sous licence AGPL-3.0-only. La section 13 de l’AGPL-3.0 exige de quiconque exécute le serveur et laisse des utilisateurs interagir avec lui via un réseau
qu’il offre à ces utilisateurs un moyen d’obtenir le code source correspondant du programme en cours d’exécution. Cela s’applique à toute personne qui interagit avec le serveur, pas seulement à celles qui ont un compte.
Indiquez où le code source est publié avec le paramètre source_url (variable d’environnement MY_SOURCE_URL ; consultez la référence de configuration).
| Valeur | Signification |
|---|---|
| Non défini | La valeur par défaut, https://github.com/mycroblog/my. Utilisez-la lorsque vous exécutez my sans modification : le GET /instance d’une version désigne alors la source de cette version, https://github.com/mycroblog/my/tree/v0.1.0, et NodeInfo le dépôt |
Une URL https: |
Un endroit où le code source peut être lu (le dépôt d’un fork, le tag ou l’archive d’une version particulière, etc.) |
Un URI mailto: |
Une adresse e-mail à laquelle demander le code source (par exemple mailto:source@example.org ; ?subject=... est autorisé) |
Toute autre valeur (http:, git@..., un chemin relatif, une URL avec des informations d’utilisateur ou un #, un mailto: sans adresse, etc.) fait échouer my config check, et le serveur ne démarre pas.
La valeur apparaît à ces endroits :
source_urldans leGET /instancede l’API client- La section « Code source » de la page d’informations du serveur du client web (
/about) et un lien sur la page d’accueil (/) metadata.sourceCodedans NodeInfo (/nodeinfo/2.1). Une URLhttps:est aussi publiée soussoftware.repository(le schéma NodeInfo 2.1 n’autorise qu’une URLhttp(s)danssoftware.repository; une valeurmailto:n’apparaît donc que dansmetadata.sourceCode)
Lorsque vous forkez ou modifiez my
Section intitulée « Lorsque vous forkez ou modifiez my »Si vous exécutez un my modifié (vous appliquez des correctifs, construisez un fork ou remplacez des dépendances), l’URL par défaut ne pointe plus vers le code source de ce qui s’exécute.
Remplacez source_url par l’endroit où l’on peut trouver le code source de la version en cours d’exécution, avec vos modifications. Pointer vers le commit, le tag ou l’archive qui correspond à la version en cours d’exécution, plutôt que vers l’état le plus récent d’un dépôt, permet aux utilisateurs d’obtenir de façon fiable le même code source.
Si vous exécutez une version officielle non modifiée, gardez la valeur par défaut.
Lorsque vous utilisez mailto:
Section intitulée « Lorsque vous utilisez mailto: »- Soyez prêt à remettre rapidement le code source correspondant (y compris les scripts nécessaires pour le construire) lorsque quelqu’un le demande. Se contenter de nommer une adresse, sans être prêt à livrer, ne remplit pas l’obligation.
- Utilisez une adresse qui fonctionne encore après que vous cessez d’exploiter le serveur ou que la personne responsable change. Une adresse d’exploitation partagée vaut mieux qu’une boîte personnelle.
- Assurez-vous que le filtrage antispam ne supprime pas les demandes.
- Utilisez une adresse que vous acceptez de rendre publique : n’importe qui peut la voir sur la page d’informations, sur la page d’accueil et dans NodeInfo.
Métriques
Section intitulée « Métriques »Le paramètre metrics_exporter (par défaut none) exporte les métriques du service. Ses paramètres associés se trouvent dans la référence de la configuration.
metrics_exporter |
Chemin | Adapté à |
|---|---|---|
none |
Rien n’est exporté. L’instrumentation ne coûte presque rien. Les valeurs de toute l’instance vont quand même dans une ligne de journal metrics snapshot toutes les 15 minutes |
Cloud Run (utilisez plutôt les métriques de la plateforme et les métriques basées sur les journaux) |
prometheus |
GET /metrics sur metrics_listen (par défaut 127.0.0.1:9464). C’est un écouteur distinct du listen public, sans authentification, qui s’exécute pour chaque role |
Auto-hébergé (collecté par un serveur compatible Prometheus ou KEDA) |
otlp |
Envoyé à un OpenTelemetry Collector via OTLP/HTTP. La destination provient des variables d’environnement OTel standard comme OTEL_EXPORTER_OTLP_ENDPOINT |
Les configurations où vous pouvez exécuter un collecteur |
emf |
Lignes JSON au format CloudWatch Embedded Metric Format. Les métriques de requêtes et de jobs voyagent sur les lignes de journal de fin ci-dessus ; les autres sont écrites sur la sortie standard, une ligne par ensemble d’étiquettes, à la fin d’une requête ou d’un job | AWS ECS |
Les métriques sont listées ci-dessous. Dans Prometheus, . dans un nom devient _ et un suffixe d’unité (_seconds, et _total pour un compteur) est ajouté.
| Métrique | Type | Étiquettes |
|---|---|---|
http.server.request.duration |
Histogramme, secondes | http.request.method, http.route (le chemin du motif de route ; other si aucun ne correspond), http.response.status_code, my.surface (client_api / admin / activitypub / oauth / media / web / payments / voice / queue) |
http.server.active_requests |
UpDownCounter | my.surface |
my.inbox.activities |
Compteur | activity.type (un type d’Activity connu, ou other), my.outcome (accepted / duplicate / rejected / ignored / error), my.inbox.rejection (uniquement avec rejected : signature pour une signature ou une preuve d’intégrité absente, invalide ou qui ne se vérifie pas, ou dont la clé n’a pas pu être récupérée ; suspended pour un domaine suspendu ; federation_off ; rate_limited ; invalid pour une activité sans id, type, actor ou object valide) |
my.relay.activities |
Compteur | my.outcome (admitted / over_limit / restricted / not_receiving : si une activité transportée par un relais a été ingérée, et pourquoi elle a été abandonnée ; voir Relais de fédération) |
my.move.activities |
Compteur | my.outcome (recorded / duplicate / not_own_actor / same_account / target_unavailable / alias_missing / target_moved / suspended / too_soon : si un Move reçu a été enregistré, et pourquoi il a été abandonné) |
my.delivery.attempts |
Compteur | my.outcome (success / retry / gone / failed ; gone couvre un 410 et les livraisons ignorées parce que le serveur est indisponible ou suspendu) |
my.delivery.duration |
Histogramme, secondes | my.outcome |
my.ux.duration |
Histogramme, secondes | my.ux.metric (lcp / inp / long_frame / transition / press / call_rtt / call_jitter), my.ux.name (la route, le type d’interaction, l’action ou le transport de l’appel ; Mesures d’expérience utilisateur) |
my.ux.call.packet_loss |
Histogramme, pourcentage | my.ux.name (le transport de l’appel) |
my.plugin.failures |
Compteur | my.plugin.kind (un type de plugin), my.plugin.code (le code Connect de l’échec) |
my.plugin.slot_wait |
Histogramme, secondes | my.plugin.kind (combien de temps un appel a attendu son tour parmi les appels de ce type qui s’exécutent en même temps) |
my.hook.decisions |
Compteur | hook, mode, outcome (les décisions qu’un hook de décision a enregistrées) |
my.hook.failures |
Compteur | hook, outcome (timeout, error, invalid ou breaker_open) |
my.hook.duration |
Histogramme | hook (secondes par appel du plugin) |
my.job.duration |
Histogramme, secondes | my.job.type (un type de job enregistré, ou other), my.outcome (success / retry / dead / postponed : postponed est une exécution qui n’a fait aucun travail et n’utilise aucune des tentatives du job, comme la récupération d’une carte de lien qui attend son hôte) |
my.job.wait |
Histogramme, secondes | my.job.type |
my.link_card.host_pauses |
Compteur | http.response.status_code (429 / 503). Un par pause des récupérations de cartes de lien auprès d’un hôte ; voir Aperçus de liens |
my.translation.requests |
Compteur | my.outcome (author / cache / provider / no_provider / limit / unsupported / failed). Un par demande de traduction d’une publication que le spectateur peut voir, ou de la publication ou du commentaire d’un signalement qu’un modérateur demande : satisfaite à partir des propres mots de l’auteur, d’une traduction conservée ou d’un fournisseur, ou refusée parce qu’aucun fournisseur ne peut recevoir la publication, qu’une limite mensuelle est atteinte, qu’aucun fournisseur ne traduit la langue, ou qu’aucun fournisseur n’a renvoyé de traduction utilisable. |
my.translation.lock_waits |
Compteur | Aucune. Une par demande qui a attendu une autre demande traduisant la même publication dans la même langue, au lieu de solliciter un fournisseur |
my.translation.characters |
Compteur | my.provider (l’ID d’un fournisseur de traduction). Les caractères des publications et des commentaires de signalements envoyés au fournisseur, sans marqueurs, y compris les appels qui échouent. C’est ce que comptent les limites mensuelles, et cela peut différer de ce que le fournisseur facture |
my.timeline.delivery.lag |
Histogramme, secondes | Aucune (de la création d’une publication locale à son écriture dans les fils d’accueil et à la notification aux flux) |
my.stream.connections |
UpDownCounter | my.stream.kind (user, timeline pour les flux des fils local et fédéré, voice pour les flux des salons de chat vocal) |
my.stream.signals |
Compteur | my.stream.kind (user / timeline). Un par signal qu’un flux ouvert a traité, qu’il ait ou non envoyé quelque chose au client |
my.accounts.registered |
Compteur | Aucune |
my.statuses.created |
Compteur | my.visibility |
my.billing.imports |
Compteur | my.billing.source (aws / gcp / plugin), my.outcome (success / failed), error.type (uniquement avec failed : le type d’échec, comme dans Importer les frais d’utilisation du cloud). Chaque tentative compte, y compris les nouvelles tentatives et les échecs qui attendent l’import quotidien suivant |
my.supporter.tip_checkouts |
Compteur | my.outcome (started / rate_limited / paid / expired). Un par démarrage d’un pourboire qui a obtenu la page du fournisseur, par démarrage que les limites ont refusé, et par pourboire payé ou terminé sans paiement ; voir pourboires pour les alertes qu’il sert |
my.voice.turn.credentials |
Compteur | my.voice.turn (coturn / cloudflare), my.outcome (issued / reused / failed). Un par identifiant TURN qu’un participant à un chat vocal a demandé en rejoignant un salon ou en renouvelant sa connexion : reused signifie que des identifiants Cloudflare émis plus tôt pour la même connexion ont été renvoyés, et failed que Cloudflare n’a pas pu être joint ou a refusé, de sorte que le participant a reçu une erreur et n’a pas pu se connecter |
my.errors.exported |
Compteur | my.outcome (success / dropped / failed : un par signalement d’erreur pour le service de errors_exporter. dropped signifie que le signalement n’a pas été envoyé parce que 1 000 signalements attendaient déjà ou que le service a demandé au serveur de ralentir, et le serveur attend aussi longtemps que le service le demande avant de renvoyer ; failed signifie que le service n’a pas pu être joint ou a refusé le signalement. Un signalement est envoyé une fois et jamais réessayé, et les signalements encore en attente 2 secondes après le début d’un arrêt sont perdus) |
my.queue.ready |
Jauge | my.job.type (le nombre de jobs exécutables dans la file de la base de données) |
my.queue.oldest_ready_age |
Jauge, secondes | my.job.type (depuis combien de temps attend le plus ancien job exécutable de chaque type dans la file de la base de données ; un type sans job exécutable n’a pas de valeur) |
my.queue.dead |
Jauge | Aucune |
my.instance.users, my.instance.statuses |
Jauge | Aucune (les nombres d’utilisateurs locaux et de publications, comme dans NodeInfo) |
my.media.stored_bytes |
Jauge, octets | my.media.origin (local / remote_cache) |
my.db.size |
Jauge, octets | Aucune (la taille de la base de données : pg_database_size pour PostgreSQL ; le fichier de la base de données sans son journal d’écriture anticipée pour SQLite) |
my.billing.import.failing |
Jauge | my.billing.source (1 lorsque le dernier import de la source a échoué, 0 sinon) |
my.federation.instances |
Jauge | my.federation.instance.state (available : les serveurs auxquels les livraisons vont encore mais qui ont échoué au moins un jour depuis leur dernière réponse ; unavailable : les serveurs dont les livraisons sont suspendues) |
my.metrics.snapshot.age |
Jauge, secondes | my.metrics.snapshot.part (queue / totals) |
my.errors.reported |
Compteur | my.error.source (server / web), my.error.kind (panic / error). Un par signalement d’erreur |
my.tls.certificate.expiry |
Jauge, secondes | host (le temps restant avant l’expiration du certificat que ce processus sert pour l’un de ses hôtes, avec tls = acme ou tls = files ; chaque processus signale le sien, de sorte qu’un processus resté avec un ancien certificat se voit. Voir Commandes et métriques) |
my.tls.order.attempts |
Compteur | host, result (issued / failed). Un par commande d’un certificat auprès de l’autorité de certification ACME, par le processus qui l’a passée, my tls renew et my tls revoke compris |
my.tls.order.consecutive_failures |
Jauge | host (les commandes depuis le certificat actuel de l’hôte qui n’en ont obtenu aucun : le nombre qui fixe l’attente avant la commande suivante) |
my.tls.rounds |
Compteur | Aucune. Un par tour du gestionnaire de certificats sur ses hôtes avec tls = acme ; un nombre qui cesse de croître signifie que le gestionnaire s’est arrêté |
Les vérifications de santé (/healthz, /readyz, /health/live, /health/ready) ne sont pas mesurées. Aucune étiquette ne contient de domaine distant, de compte, d’URL ni d’IP de client.
my.queue.*, my.instance.*, my.media.stored_bytes, my.db.size, my.federation.instances et my.billing.import.failing sont des valeurs pour toute l’instance : chaque processus signale la même valeur à partir d’un instantané conservé dans le magasin clé-valeur.
Métriques système
Section intitulée « Métriques système »Les métriques sur le processus, le runtime Go et les connexions aux ressources sont exportées par le même metrics_exporter.
Le CPU des conteneurs, la mémoire, le nombre d’instances et les requêtes entrantes sont laissés aux métriques de la plateforme ; celles-ci couvrent la saturation à l’intérieur du processus que la plateforme ne peut pas voir.
Ne les utilisez pas pour déclencher la mise à l’échelle ; utilisez-les pour les alertes et pour estimer le plafond d’instances.
| Métrique | Type | Étiquettes |
|---|---|---|
go.memory.used, go.memory.limit, go.memory.gc.goal |
Jauge, octets | Seul go.memory.used a go.memory.type (stack / other). go.memory.limit n’apparaît que lorsque GOMEMLIMIT est défini |
go.memory.allocated, go.memory.allocations |
Compteur | Aucune |
go.goroutine.count, go.processor.limit, go.config.gogc |
Jauge | Aucune |
go.schedule.duration, go.memory.gc.pause.duration |
Histogramme, secondes | Aucune (l’attente entre le moment où une goroutine devient exécutable et son exécution, et les pauses du GC) |
go.memory.gc.cycles |
Compteur | Aucune |
process.cpu.time |
Compteur observable, secondes (total depuis le démarrage) | cpu.mode (user / system) |
process.memory.usage |
Jauge, octets | Aucune (mémoire résidente, RSS) |
process.unix.file_descriptor.count, my.process.file_descriptor.limit |
Jauge | Aucune (les descripteurs de fichiers ouverts et la limite) |
process.uptime |
Jauge, secondes | Aucune |
db.client.connection.count |
Jauge | db.client.connection.pool.name (postgres / sqlite), db.client.connection.state (idle / used) |
db.client.connection.max |
Jauge | db.client.connection.pool.name |
db.client.connection.wait_time, my.db.client.connection.waits, db.client.connection.timeouts |
Compteur observable (total depuis le démarrage ; secondes ou nombre) | db.client.connection.pool.name. timeouts n’existe que pour PostgreSQL |
my.adapter.operation.duration |
Histogramme, secondes | my.adapter (queue.db / kv.db / kv.memory / kv.valkey / stream.<stream> / blob.fs), my.operation, my.outcome (success / error) |
my.adapter.connections |
UpDownCounter | my.adapter (connexions valkey, et abonnés stream.<stream>) |
my.adapter.reconnects |
Compteur | my.adapter |
http.client.request.duration |
Histogramme, secondes | my.http.purpose (json / html / image / video / human_check / web_push / webhook / client_metadata / login_provider / robots / domain_list), http.request.method, my.http.status_class (2xx et ainsi de suite), error.type (forbidden_destination est un refus par la protection SSRF) |
http.client.open_connections |
UpDownCounter | Aucune |
my.readiness.failures |
Compteur | Aucune |
my.readiness.shared |
Compteur | Aucune. Un par requête de disponibilité qui a repris le résultat d’une vérification déjà en cours au lieu d’en démarrer une |
my.http.origin_refused |
Compteur | Aucune. Un par requête refusée parce qu’elle n’est pas passée par le CDN (origin_secret). Les sondes de l’adresse de l’origine le font augmenter lentement ; un bond alors que le trafic s’arrête signifie que le CDN n’envoie plus l’en-tête. Le mode maintenance ne mesure rien, de sorte que seul son journal d’accès les montre |
- Les métriques du runtime Go (
go.*) ne sont exportées que parprometheusetotlp. Avecemf, un job d’instantané périodique écrit les jauges du processus et du pool de connexions ainsi que les compteurs observables. - Les attentes du pool et le temps CPU sont des compteurs observables : le pool et le noyau conservent des totaux depuis le démarrage, et ils sont lus au moment de la collecte. Dans Prometheus, ce sont des compteurs
_total(commeprocess_cpu_time_seconds_total), dans OTLP ce sont des sommes monotones, et vous voyez leur croissance avecrate()de PromQL.emfn’a pas de compteurs totaux ; il écrit donc l’augmentation depuis l’écriture précédente (additionnez-les avec la statistique Sum de CloudWatch). - Le
claimde la file n’est mesuré que lorsqu’il prend un job ou échoue. L’interrogation d’un worker en attente n’enregistre rien. db.client.connection.pending_requestsn’est pas exporté : les statistiques de pgx et dedatabase/sqlne signalent pas combien attendent ; le nombre et la durée des attentes en tiennent donc lieu.- Mettez en place une alerte sur le rapport entre la somme de
go.memory.usedetgo.memory.limit, et sur la croissance dedb.client.connection.wait_time(la limite du pool est atteinte).
Limite de mémoire (GOMEMLIMIT)
Section intitulée « Limite de mémoire (GOMEMLIMIT) »GOMEMLIMIT est une variable d’environnement du runtime Go que l’opérateur définit ; l’application ne la choisit pas.
Sans elle, Go s’exécute avec sa valeur par défaut (aucune limite), et le tas ne se vide pas de façon anticipée à l’approche de la limite de mémoire du conteneur.
Sur les configurations avec une limite de mémoire de conteneur (Cloud Run, ECS, Kubernetes), définissez-la à environ 90 % de cette limite (par exemple GOMEMLIMIT=460MiB pour un conteneur de 512 Mio).
Ne définissez pas GOMAXPROCS : la valeur par défaut de Go suit la limite de processeur du conteneur.
Le réglage traces_exporter (none par défaut) exporte des traces distribuées. Ses réglages associés se trouvent dans la référence de configuration.
| Span | Nom | Attributs |
|---|---|---|
| Requête HTTP (serveur) | <method> <http.route> (<method> pour une requête qui n’a atteint aucune route) |
http.request.method, http.route, http.response.status_code, my.surface. Un 5xx est un échec |
| Exécution d’une tâche (consommateur) | Le type de tâche (my.job.type) |
my.job.type, my.job.attempt, my.outcome. Chaque nouvelle tentative est un span distinct |
| Transaction | my.db.transaction |
db.system.name. Chaque nouvelle tentative est un span distinct |
| Requête (client) | Le nom de la requête sqlc (comme InsertJobs ; sinon le premier mot du SQL, comme BEGIN) |
db.system.name, db.operation.name |
Envoi (my.delivery) |
my.delivery |
activity.type, my.outcome |
| HTTP sortant (client) | <method> |
http.request.method, server.address (uniquement le nom d’hôte de la destination), http.response.status_code. Un 4xx ou un 5xx est un échec |
Un span en échec a error.type (un nom fini tel que timeout, ou un code de statut). Les attributs ne contiennent jamais d’ID de compte, de publication ou de tâche, d’URL, de chemins ou de requêtes, d’IP clientes, de valeurs de User-Agent, de texte SQL ni de chaînes d’erreur.
server.address laisse les noms d’hôte des serveurs distants au récepteur ; c’est donc vous qui décidez combien de temps le récepteur les conserve et qui peut les consulter. Les vérifications d’état et les requêtes refusées par origin_secret ne créent aucun span.
- Une exécution de tâche n’est pas l’enfant du span qui l’a mise en file (généralement une requête HTTP). C’est la racine d’une nouvelle trace avec un lien vers le span qui l’a mise en file. Dans un visualiseur, suivez le lien depuis la trace de la requête.
- Un
traceparententrant ne devient le parent que lorsque le pair connecté figure danstrusted_proxieset, avecorigin_secret, que la requête porte le secret. Sinon, il est écarté et une nouvelle trace commence.tracestateest toujours écarté. Le HTTP sortant (fédération, WebFinger, médias, Web Push, etc.) ne porte aucuntraceparent. - Échantillonnage : une requête est enregistrée si son parent de proxy de confiance l’a été, ou si la cible du lien d’une tâche l’a été ; sinon elle est enregistrée selon le ratio
traces_sample_ratio(0,01 par défaut). Abaisser le ratio ne laisse jamais sans leur trace les tâches qui prolongent une requête enregistrée.
| Cible | Réglages | Chemin |
|---|---|---|
| Par défaut, petit auto-hébergement | traces_exporter = none |
Aucun span n’est exporté. Suivez request_id et job_id dans les journaux. Si un proxy de confiance fournit un traceparent, son trace_id et son span_id sont ajoutés aux journaux |
| Auto-hébergement (Jaeger, Tempo, un OpenTelemetry Collector, etc.) | traces_exporter = otlp, traces_flush = batch |
Envoyé par OTLP/HTTP au récepteur à OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (ou OTEL_EXPORTER_OTLP_ENDPOINT, http://localhost:4318 par défaut). Les en-têtes d’authentification vont dans OTEL_EXPORTER_OTLP_HEADERS. Pour conserver de façon fiable les erreurs et les traces lentes, utilisez l’échantillonnage en queue du Collector |
| Google Cloud (Cloud Run) | none, ou otlp avec unit pour activer les traces |
Voir ci-dessous |
| AWS (ECS) | none, ou otlp avec batch pour activer les traces |
Voir ci-dessous |
Cloud Run
Section intitulée « Cloud Run »Même avec none, la trace de requête que Cloud Run crée automatiquement et le trace_id dans les journaux partagent le même ID (lorsque vous faites confiance avec trusted_proxies à la connexion en amont de Cloud Run).
Le fait que Cloud Run écrase toujours le traceparent des requêtes publiques n’est pas encore vérifié.
Les journaux n’ont pas la forme du champ de trace que Cloud Logging reconnaît (logging.googleapis.com/trace).
Pour envoyer les spans de l’application à Cloud Trace, exécutez un OpenTelemetry Collector en sidecar dans le même service. Le serveur ne détient aucun identifiant Google ; le sidecar envoie au point de terminaison OTLP de Cloud Trace avec les Application Default Credentials.
- Serveur (le conteneur d’entrée) :
MY_TRACES_EXPORTER=otlp,MY_TRACES_FLUSH=unit,OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 - Sidecar : un OpenTelemetry Collector qui reçoit avec un récepteur
otlpen HTTP surlocalhost:4318et envoie avec l’exportateurgooglecloud, ou l’exportateurotlphttp(https://telemetry.googleapis.com, avec l’extensiongoogleclientauth). Accordez au compte de service la permission d’écrire dans Cloud Trace. - À la fin de chaque requête ou tâche enregistrée,
unitvide les spans accumulés vers le sidecar avant de retourner. Pour que le sidecar puisse les envoyer alors qu’aucun processeur n’est alloué, utilisez la facturation par instance pour une configuration avec traces activées. - Le coût est celui des ressources du sidecar et du volume de spans (tarifs de Cloud Trace). Choisissez le ratio avec
traces_sample_ratio.
Pour envoyer vers X-Ray, exécutez le AWS Distro for OpenTelemetry (ADOT) Collector comme conteneur sidecar dans chaque tâche. Le serveur n’a pas de signature SigV4 ; le Collector signe avec le rôle de la tâche et envoie vers X-Ray. Le module mycroblog-aws du déploiement OpenTofu fait tout cela par défaut (observability.traces = "x-ray") ; le reste de cette section s’adresse à une définition de tâche à vous.
- Serveur :
MY_TRACES_EXPORTER=otlp,OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/traces, et la valeur par défautMY_TRACES_FLUSH=batch, puisque le processus reste actif. - Collector : une image épinglée par version, comme
public.ecr.aws/aws-observability/aws-otel-collector:v0.50.0, avec sa configuration dans la variableAOT_CONFIG_CONTENT: un récepteurotlpsur HTTP à127.0.0.1:4318et l’exportateurawsxray. Le point de terminaison OTLP de X-Ray (https://xray.<region>.amazonaws.com/v1/traces, par un exportateurotlphttpavec l’extensionsigv4auth) fonctionne aussi, mais exige que CloudWatch Transaction Search soit activé pour le compte. - Accordez au rôle de la tâche
xray:PutTraceSegments, avec lequel l’exportateurawsxrayécrit. Le serveur échantillonne lui-même les traces ; le Collector n’a donc besoin d’aucune règle d’échantillonnage de X-Ray. - Donnez au Collector une part de la tâche :
mycroblog-awslui donne 32 unités de CPU et 128 MiB, et le reste au serveur, avecGOMEMLIMITà 90 % de ce reste. Faites dépendre le conteneur du serveur du démarrage de celui du Collector, afin que le Collector s’arrête après le serveur et reçoive ses derniers spans. - Le coût est la part du sidecar dans les ressources de la tâche, et le nombre de traces qu’enregistre X-Ray (les 100 000 premières par mois sont gratuites). La valeur par défaut
traces_sample_ratiode 0,01 enregistre environ 30 000 traces par mois pour 100 000 requêtes par jour.
Les métriques système disent combien de mémoire et de CPU un processus utilise ; un profil du runtime Go dit ce qui les utilise.
pprof_listen nomme l’adresse d’un écouteur qui sert les profils sous /debug/pprof/, pour chaque role. Il est vide par défaut, ce qui n’ouvre aucun écouteur.
MY_PPROF_LISTEN=127.0.0.1:6060 my serve
go tool pprof -sample_index=inuse_space http://127.0.0.1:6060/debug/pprof/heap # what holds the heap nowgo tool pprof -sample_index=alloc_space http://127.0.0.1:6060/debug/pprof/heap # what has allocated since the startgo tool pprof 'http://127.0.0.1:6060/debug/pprof/profile?seconds=30' # where the CPU goes, for 30 secondscurl 'http://127.0.0.1:6060/debug/pprof/goroutine?debug=1' # every goroutine, by where it waitscurl 'http://127.0.0.1:6060/debug/pprof/heap?debug=1' | grep '^# ' # the runtime's memory statisticsL’écouteur n’a pas d’authentification, un profil montre l’intérieur du processus, et en prendre un coûte du CPU : gardez-le sur loopback et atteignez-le par un tunnel (ssh -L 6060:127.0.0.1:6060 <host>, kubectl port-forward), puis désactivez-le lorsque vous avez terminé.
Le profil du tas ne couvre que le tas Go. La mémoire résidente du processus contient aussi les pages du binaire qui ont été lues, les piles et les propres structures du runtime ; les statistiques de mémoire les donnent.
Les profils de mutex et de blocage sont vides : le serveur ne les échantillonne pas.
Arrêter le serveur
Section intitulée « Arrêter le serveur »Sur SIGTERM ou SIGINT, le serveur s’arrête proprement.
- Il cesse d’accepter de nouvelles connexions et de prendre des tâches.
- Il attend jusqu’à 25 secondes que les requêtes en cours et les tâches en cours d’exécution se terminent.
- Après 25 secondes, il annule le contexte des requêtes et des tâches restantes et ferme les connexions. Il laisse ensuite à une tâche annulée jusqu’à 3 secondes de plus pour enregistrer son résultat, et se termine avec le code 1 (28 secondes au plus en tout, dans le délai de grâce par défaut de 30 secondes de Kubernetes et d’ECS). Une tâche annulée est retentée. Une tâche qui ne s’arrête pas dans ces 3 secondes, ou qui est tuée en cours de route, est abandonnée et reprise par un worker lorsque son bail expire ; elle peut donc s’exécuter deux fois.
Une panique dans l’une des tâches d’arrière-plan du serveur déclenche le même arrêt, afin que le serveur ne continue jamais de s’exécuter dans un état défectueux.
La ligne de journal serve failed nomme la tâche, et le processus se termine avec le code 1 pour que la plateforme ou le gestionnaire de processus le redémarre.
Pour un travail sur la base de données, le magasin clé-valeur ou la file, redémarrez en mode maintenance (MY_MAINTENANCE=true) plutôt que de l’arrêter. Consultez Maintenance.
La file de jobs et les jobs en échec (morts)
Section intitulée « La file de jobs et les jobs en échec (morts) »Jobs liste chaque type de job : ce qu’il fait, ce qui le déclenche, comment il réessaie et ce que fait son ré-exécution.
La page d’administration des jobs (Administration → Jobs, /admin/jobs, permission manage_jobs) comporte trois pages :
- État de la file (
/admin/jobs) : d’abord combien de jobs ont échoué, avec un lien vers eux ; le nombre par état (en file, en cours, en attente de nouvelle tentative, en échec), chacun menant aux jobs de cet état ; depuis combien de temps attend le plus ancien job dû ; et un tableau des nombres par type et par état avec le temps pendant lequel chaque type fait attendre un job. - Liste des jobs (
/admin/jobs/list) : les jobs qui ne sont pas terminés (en file, en cours, en attente de nouvelle tentative), ou d’un état, et d’un type, une page à la fois, avec le type, le nombre de tentatives, l’heure à laquelle il est dû ou a échoué, l’état et la première ligne de la dernière erreur. - Un job (
/admin/jobs/<id>, depuis le type dans la liste) : Exécuter de nouveau pour un job en échec, qui demande d’abord confirmation, car une exécution peut répéter ce que le job a fait avant d’échouer ; chaque fait du job, son ID et ses clés chacun avec un bouton de copie ; sa dernière erreur et sa charge utile, chacune avec un bouton de copie ; un tableau des tentatives infructueuses, les plus récentes d’abord (résultat, heure de fin, worker et erreur) ; et un lien vers les jobs de son type.
L’API d’administration comprend GET /api/v1/admin/queue, GET /api/v1/admin/jobs?state=&type=, GET /api/v1/admin/jobs/{id}, GET /api/v1/admin/jobs/{id}/attempts et POST /api/v1/admin/jobs/{id}/retry.
Un job terminé n’est plus dans la file ; sa page est donc introuvable.
- Les jobs en attente, en cours et en attente de nouvelle tentative ne peuvent être listés que pour les files dont le serveur détient les jobs :
queue = db,queue = cloudtasks(les jobs sont aussi dans la base de données) etqueue = inline. Les jobs en échec et l’historique des tentatives se trouvent dans la base de données de l’application pour toutes les files, et peuvent donc toujours être listés. - L’historique des tentatives ne conserve que les tentatives infructueuses (les nouvelles tentatives et la tentative qui a finalement échoué). Suivez une exécution réussie par la ligne de journal structurée
job(qui portejob_id). L’historique est supprimé par le nettoyage horaire une fois quejob_attempt_retention(30 jours par défaut ; voir le paramètre) s’est écoulé depuis la fin de la tentative. L’historique ne contient ni charge utile ni journal de gestionnaire, et un message d’erreur est tronqué à ses 2 000 premiers octets. Les gestionnaires de jobs tiennent les adresses e-mail, les adresses IP, les jetons et les corps de publications hors des messages d’erreur. Pour une vue limitée aux types de jobs d’e-mail, voir Envoyer des e-mails.
Un job dont le gestionnaire a décidé qu’il avait échoué définitivement, et un job qui a épuisé ses nouvelles tentatives, devient un job mort dans la file de la base de données (queue = db et queue = cloudtasks).
my job les liste, les relance et les supprime. L’état « En échec » de la page des jobs et l’API d’administration peuvent aussi les lister et les relancer.
my job list # newest failures first: ID, type, run count, time of failure, last error (-limit sets the count, default 50)my job retry <id> [<id>...] # reset the attempt count and put the job back in the queue to run immediatelymy job delete <id> [<id>...] # remove without runningmy job types # print every job type of this release- Si un job avec la même clé d’idempotence est déjà en attente, ce job tient lieu de celui qui est relancé. Les gestionnaires de jobs sont idempotents ; remettre le même job en file un nombre quelconque de fois est donc sans risque.
- Un ID inconnu est affiché et la commande se termine avec le code 1 ; les autres ID sont quand même traités. Le code de sortie 2 signifie une erreur d’utilisation.
- Un job mort que personne ne relance est supprimé par le nettoyage horaire une fois que
dead_job_retention(30 jours par défaut ; voir le paramètre) s’est écoulé depuis l’échec. - Les jobs morts de
queue = inlinevivent dans la mémoire du processus du serveur ;my jobne peut donc pas les gérer (code de sortie 1).
Répartir les workers par type de tâche
Section intitulée « Répartir les workers par type de tâche »Par défaut, chaque worker exécute chaque type de tâche, dans l’ordre où les tâches sont arrivées à échéance, une tâche à la fois par processus (consultez Exécuter plusieurs tâches à la fois). Une rafale de remises retarde alors les e-mails et les notifications, et tout worker que vous ajoutez partage son temps entre tous. Avec queue = db, vous pouvez donner à certains types leurs propres workers :
worker_job_types: ce processus n’exécute que ces types.worker_job_types_except: ce processus exécute tous les types sauf ceux-ci.
Chacun est une liste séparée par des virgules de types de tâches (my job types les affiche ; my config check refuse un nom qui n’en correspond à aucun), écrits sous forme de nom (federation.deliver) ou de préfixe (federation.*). Définissez-les par processus, par exemple avec MY_WORKER_JOB_TYPES. Vous ne pouvez pas définir les deux sur un même processus. Un nom ou un préfixe qui ne correspond à aucun type de tâche arrête le démarrage, ce qui détecte aussi un type qu’une version a renommé, ou un type qui n’existe qu’avec un paramètre que vous n’avez pas défini. Ils ne fonctionnent pas avec role = web, ni avec queue = cloudtasks ou inline, où le démarrage échoue aussi : là, un signal nomme la tâche à exécuter, de sorte qu’un processus ne peut pas choisir ses tâches.
Au démarrage, un processus doté de l’un des paramètres consigne les types qu’il ignore. Il ne peut pas voir les paramètres des autres processus ; assurez-vous donc qu’un processus exécute chaque type, faute de quoi ces tâches attendent indéfiniment. Le nettoyage périodique et l’e-mail sont aussi des types de tâches. Chaque processus démarre tout de même les tâches périodiques ; le processus qui les exécute dépend de ces paramètres.
Décidez de ce qu’il faut répartir d’après les métriques, pas d’après les noms de types. my.job.wait (Prometheus : my_job_wait_seconds) indique combien de temps les tâches ont attendu par type avant de démarrer :
histogram_quantile(0.95, sum by (my_job_type, le) (rate(my_job_wait_seconds_bucket[15m])))sum by (my_job_type) (rate(my_job_duration_seconds_sum[1h])) indique le temps de worker qu’utilise chaque type, ce qui correspond aussi à peu près au nombre de processus dont il a besoin. Un type qui utilise la majeure partie du temps et fait attendre les autres est celui à déplacer.
Trois dispositions courantes, avec le nombre de processus de votre choix :
| Disposition | Processus |
|---|---|
| Empêcher les remises de retarder le reste | worker_job_types = federation.fanout,federation.deliver pour les remises, et worker_job_types_except = federation.fanout,federation.deliver pour tout le reste. Ajoutez des processus au premier groupe pendant une rafale. |
| Empêcher un moteur de recherche de retarder le reste | worker_job_types = search.* pour les tâches de recherche, et worker_job_types_except = search.* pour tout le reste (Empêcher la recherche de retarder les autres tâches). |
| Garder les e-mails et les notifications rapides | worker_job_types = identity.verification_email,identity.password_reset_email,identity.password_notice_email,identity.closure_email,identity.deactivation_email,notification.email,notification.moderator_email,notification.supporter_email,notification.push,notification.post_subscribers,instance.notify_announcement,voice.notify_started pour ceux-ci, et un worker sans paramètre pour tout, ce qui aide aussi pour ces types lorsqu’il est libre. Omettez les types dont vous n’avez pas défini les paramètres, faute de quoi le démarrage s’arrête : notification.push nécessite vapid_private_key, et notification.email, notification.moderator_email et notification.supporter_email nécessitent mail. Consultez Tâches qui dépendent de paramètres. |
Un préfixe tel que identity.* est le module de code qui possède les types, pas un type de travail. identity.* prend aussi les exports de données, les imports et les tâches d’expiration, et il manque instance.notify_announcement et voice.notify_started ; une disposition pour un type de travail nomme donc chaque type.
Gardez-les ensemble, sur des workers ayant le même paramètre. Les tâches d’une même clé d’ordre s’exécutent dans l’ordre quel que soit leur type ; si rien n’exécute la tâche précédente, la suivante attend aussi, et si le groupe de la tâche précédente est engorgé, la tâche suivante l’attend :
| Types | Ce qu’ils maintiennent dans l’ordre |
|---|---|
federation.fanout, federation.deliver |
Les remises d’un J’aime et de son annulation |
voice.apply_media_event, voice.apply |
Les événements d’un même salon vocal |
supporters.sync, supporters.command |
Les modifications d’un même abonnement |
Lors d’une mise à niveau :
- Un processus doté de
worker_job_typesn’exécute pas les types qu’une nouvelle version ajoute. Consultez les notes de version et les types ignorés dans le journal. Un processus doté deworker_job_types_exceptles exécute, ce qui en fait l’endroit le plus sûr pour tout le reste. - Un type renommé arrête le démarrage ; lisez donc d’abord les notes de version.
Pour déployer une répartition, démarrez d’abord les nouveaux workers, puis ajoutez le paramètre aux anciens. Pour l’annuler, retirez le paramètre d’un groupe avant d’arrêter l’autre. Les tâches restent dans la file, rien n’est donc perdu, et un type qu’aucun processus n’exécute pendant un moment ne fait qu’attendre.
Détecter un type qu’aucun processus n’exécute. Les tâches d’un tel type attendent ; my.queue.oldest_ready_age croît donc pour ce type, et les alertes MyQueueBacklog et MyQueueStalled se déclenchent sur le type qui attend le plus longtemps. Pour voir lequel, ou pour alerter par type :
max by (my_job_type) (my_queue_oldest_ready_age_seconds) > 1800La page d’administration des tâches montre la même attente par type. Un worker doté de l’un des paramètres laisse aussi de côté une tâche dont le type n’a aucun gestionnaire (elle compte sous other dans la métrique) ; sans worker dépourvu de paramètre, une telle tâche attend donc au lieu de devenir une tâche morte.
Exécuter plusieurs jobs à la fois
Section intitulée « Exécuter plusieurs jobs à la fois »worker_job_concurrency définit combien de jobs un processus exécute à la fois, de 1 à 128. Il fonctionne avec queue = db ; avec Cloud Tasks, c’est la plateforme qui en décide. La valeur par défaut est un job à la fois, et une valeur de 1 se comporte de même.
Augmentez-le pour les jobs qui passent leur temps à attendre d’autres serveurs, comme federation.deliver. Ceux-ci utilisent peu de mémoire et peu de connexions à la base de données par job, de sorte qu’un processus fait le travail de beaucoup : dans un test local où un job n’attendait qu’une réponse de 200 ms, un processus avec 32 emplacements égalait 32 processus à un emplacement chacun, en utilisant une petite part de la mémoire. Ces jobs ne faisaient rien d’autre ; mesurez donc votre propre instance. Associez-le à worker_job_types, et donnez à chaque type de job un processus avec son propre nombre.
Gardez ces limites à l’esprit :
- Connexions à la base de données : un job a besoin d’une connexion pour être réclamé, pour son propre travail et pour enregistrer son résultat. Le paramètre doit être inférieur au maximum du pool, sinon le serveur ne démarre pas. Le maximum est
pool_max_connsdansdatabase_url, par défaut le plus grand de 4 et du nombre de CPU, si bien qu’un vCPU en autorise 3 tant que vous ne l’augmentez pas. Vérifiez que votre base de données ou votre pooler de connexions accepte les connexions de tous vos processus. - SQLite : il n’écrit qu’une transaction à la fois, et dans un test local il était plus lent à 128 qu’à 32.
- Jobs gourmands en CPU : les emplacements se partagent le CPU et la mémoire d’un seul processus.
media.processattend son tour à une limite de la moitié des CPU par défaut, et l’attente compte dans le bail de 5 minutes du job ; un processus plein demedia.processpeut donc dépasser le bail et recommencer. Donnez à de tels jobs un processus avec peu d’emplacements. - Un serveur à la fois : un processus établit au plus 8 connexions vers un même hôte ; un processus ne livre donc pas à un seul serveur plus vite que 8 connexions le permettent, quel que soit son nombre d’emplacements. Là où la plupart des livraisons vont vers quelques gros serveurs, davantage de processus aident là où davantage d’emplacements n’aident pas.
- Un serveur bloqué retient des emplacements : les emplacements qui attendent un serveur lent ne sont pas libres pour d’autres jobs ; gardez donc les livraisons séparées des e-mails et des notifications.
- Les déploiements consomment des tentatives : lorsque le serveur s’arrête, les jobs encore en cours après
ShutdownTimeout(25 secondes par défaut) sont annulés, et chaque job annulé consomme une tentative. Plus il y a d’emplacements qui exécutent des jobs lents, plus chaque déploiement consomme de tentatives. Un job annulé dont le résultat n’est pas enregistré à temps attend l’expiration de son bail avant de s’exécuter de nouveau. - Un plantage emporte tous les emplacements : si le processus manque de mémoire, tous ses jobs attendent l’expiration de leurs baux.
Pour décider d’augmenter, lisez my.job.wait par my.job.type : si les jobs d’un type attendent longtemps alors que my.job.duration est surtout du temps passé à attendre d’autres serveurs et que le CPU et la mémoire restent bas, davantage d’emplacements devraient aider. Si les attentes restent élevées après l’augmentation, regardez les connexions à la base de données et la limite par hôte ci-dessus avant d’augmenter de nouveau.
Tant qu’aucun job n’est dû, un emplacement interroge et les autres attendent ; un processus inactif coûte donc à la base de données ce que coûte un processus à un seul job.
Attendre une connexion à la base de données
Section intitulée « Attendre une connexion à la base de données »Avec database = postgres, chaque instruction et chaque transaction attend d’abord une connexion libre du pool du processus.
database_acquire_timeout (60s par défaut) borne cette attente, et rien d’autre : une longue requête ou
transaction qui a déjà sa connexion se poursuit, quelle que soit sa durée. 0 attend sans limite. SQLite n’a aucune limite de connexions à attendre ; le définir là fait donc échouer le démarrage.
Lorsque l’attente expire :
- Une requête reçoit la réponse
503 Service UnavailableavecRetry-After: 5. - Une tâche s’exécute de nouveau 30 secondes plus tard et ne consomme aucune tentative ; une base de données occupée ne transforme donc jamais une tâche en tâche morte.
- La métrique
db.client.connection.timeoutsla compte, et l’alerteMyDBPoolWaitingse déclenche.
La valeur par défaut est le délai d’écriture de 60 secondes du serveur : une requête qui a attendu plus longtemps ne pourrait de toute façon pas envoyer sa réponse ; la valeur par défaut ne fait donc échouer aucune requête qui aurait encore pu réussir. Choisissez une valeur d’après le fonctionnement de votre serveur :
- Abaissez-la pour délester rapidement : les clients réessaient après
Retry-Afterau lieu de garder leurs requêtes ouvertes. Gardez-la supérieure à vos transactions normales les plus lentes, faute de quoi une courte rafale se met à recevoir des503. - Dimensionnez d’abord le pool. Un processus a besoin d’à peu près autant de connexions qu’il exécute de travaux à la fois.
pool_max_connsdansdatabase_urlvaut par défaut le plus grand de 4 et du nombre de processeurs, et tous les processus ensemble doivent rester sous la limite de connexions de la base de données.- Avec
worker_job_concurrency, les emplacements attendent aussi des connexions, et le paramètre doit rester inférieur au maximum du pool. - Sur Cloud Run, un service accepte 80 requêtes simultanées par instance par défaut. Avec un pool de 4, une rafale de requêtes lentes fait la queue ici ; augmentez donc
pool_max_conns, abaissez la simultanéité du service, ou les deux.
- Avec
- Des
503fréquents ou desdb.client.connection.timeoutssignifient que le pool est trop petit ou que les requêtes sont devenues plus lentes ; un délai plus long ne fait que le masquer. SuivezMyDBPoolSaturated.
Cloud Tasks
Section intitulée « Cloud Tasks »Déployer sur Cloud Run met en place tout ce qui suit avec des modules OpenTofu.
Avec queue = cloudtasks, les tâches restent dans la base de données (database = postgres), et Google Cloud Tasks ne fait que réveiller le serveur pour chacune d’elles :
- Pour chaque tâche qu’il stocke, relance ou remet en file, le serveur crée une tâche dans
queue_cloudtasks_queueune fois la transaction validée. La tâche appellePOST {queue_cloudtasks_url}/_internal/jobsà l’heure à laquelle la tâche est due, avec l’ID de la tâche comme corps et un jeton d’ID OIDC dequeue_cloudtasks_service_account. Une tâche due à plus de 30 jours est signalée à 30 jours, et de nouveau lorsque cette tâche arrive. - Le processus qui reçoit la tâche exécute le travail et répond
204une fois son résultat enregistré, y compris lorsque le travail a déjà été exécuté ou n’est pas dû. Une tâche qui échoue est relancée par le serveur à sa prochaine heure de tentative, pas par Cloud Tasks. Cloud Tasks ne relance une tâche que lorsque la réponse est5xx(la base de données n’a pas pu être jointe) ou401(un jeton que le serveur a refusé) ; sonretryConfign’a donc besoin d’aucun réglage. - Aucun processus n’interroge la table et aucun processus n’exécute de lui-même les tâches périodiques. Créez un travail Cloud Scheduler qui appelle
POST {queue_cloudtasks_url}/_internal/tickchaque minute (* * * * *) avec un jeton OIDC du même compte de service (et l’audience dequeue_cloudtasks_audience, lorsqu’elle est définie). Chaque tick met en file les tâches périodiques dont la période est venue, une fois pour toute l’instance (les périodes sont réservées dans le KV ;kvdoit donc êtredbouvalkey), et signale de nouveau les tâches dues depuis plus de 2 minutes sans s’être exécutées, ce qui récupère un signal perdu. /_internal/jobset/_internal/ticksont servis par les processus avecrole = allouworker, et n’acceptent qu’un jeton signé par Google pourqueue_cloudtasks_service_accountavec une adresse e-mail vérifiée, dont la seule audience estqueue_cloudtasks_audienceou, par défaut, l’URL appelée. Toute autre requête reçoit un401.- Une livraison exécute une tâche, pendant au plus le bail de 5 minutes. Gardez
queue_cloudtasks_dispatch_deadline(10 minutes par défaut) et le délai d’attente des requêtes du service Cloud Run supérieurs à cette durée. - Le compte de service propre du serveur a besoin de
roles/cloudtasks.enqueuersur la file et deroles/iam.serviceAccountUsersurqueue_cloudtasks_service_account. Il s’authentifie avec les Application Default Credentials.
Avec quel retard s’exécutent les tâches périodiques
Section intitulée « Avec quel retard s’exécutent les tâches périodiques »Une tâche périodique s’exécute avec jusqu’à une période de son déclencheur après son heure, plus le temps que met la plateforme à la démarrer. C’est ce qui détermine le retard avec lequel arrivent les rappels et les notifications de début des événements et avec lequel s’ouvrent leurs salons de chat vocal, puisque gathering.tick les démarre : un rappel a un retard pouvant aller jusqu’à l’intervalle du tableau. Les valeurs sont celles que donnent le code de l’ordonnanceur et le déclencheur de chaque plateforme ; elles n’ont pas été mesurées sur un serveur en fonctionnement.
| Plateforme | Ce qui démarre les tâches périodiques | Retard attendu d’un rappel ou du début d’un événement |
|---|---|---|
Auto-hébergement et Docker Compose (queue = db) |
L’ordonnanceur de chaque processus avec role = all ou worker vérifie une fois par minute, à partir du démarrage du processus, et met en file chaque tâche une fois par période pour tout le serveur |
Jusqu’à 1 minute, plus environ une seconde pour qu’un worker prenne la tâche |
AWS ECS Fargate (queue = db) |
Le même ordonnanceur, dans les tâches worker | Jusqu’à 1 minute, plus environ une seconde |
Cloud Run (queue = cloudtasks) |
Cloud Scheduler appelle /_internal/tick selon son calendrier, * * * * * (chaque minute) par défaut ; Cloud Tasks réveille ensuite le serveur pour chaque tâche |
Jusqu’à 1 minute, plus le démarrage d’une instance lorsqu’aucune ne tourne (un démarrage à froid, généralement quelques secondes). Avec un tick_schedule plus long, tel que */10 * * * *, jusqu’à cet intervalle |
| AWS Lambda | my n’a pas de déploiement Lambda ; sur AWS, exécutez-le sur ECS Fargate |
— |
Un rappel qui arriverait après le début de son événement n’est pas envoyé, pas plus qu’une notification de début après la fin de l’événement. Avec un tick de plus de 5 minutes, les rappels les plus courts peuvent donc être perdus.
Acheminer des types de tâches vers leurs propres files
Section intitulée « Acheminer des types de tâches vers leurs propres files »Avec queue = cloudtasks, un worker ne peut pas choisir les tâches qu’il exécute : worker_job_types ne fonctionne qu’avec queue = db, car la plateforme décide qui reçoit un signal.
Pour donner à certains types de tâches leur propre capacité, envoyez leurs signaux vers leur propre file, et définissez la capacité de cette file sur la plateforme.
Rien ne change tant que vous ne définissez pas de route.
queue_cloudtasks_routes : federation.*=projects/p/locations/l/queues/my-federation@https://federation-worker.example.com,notification.email=projects/p/locations/l/queues/my-mail.
Une route sans @ ni URL appelle queue_cloudtasks_url.
Le côté gauche est un type de tâche de la référence des tâches ou un préfixe. Un nom l’emporte sur un préfixe, et un préfixe plus long sur un plus court.
Les types qui ne correspondent à aucune route, y compris ceux qu’ajoute une version ultérieure, utilisent la file par défaut (queue_cloudtasks_queue), et continuent donc de s’exécuter.
my config check vérifie la forme des routes ; un côté gauche qui ne correspond à aucun type de tâche arrête my serve au démarrage.
Donnez à chaque processus les mêmes routes, role = web compris. Un signal est envoyé par le processus qui stocke la tâche : un processus web pour la plupart de ce que font les utilisateurs, comme la
première tâche d’une publication, et un worker pour les tâches qu’une tâche stocke, retente, la tâche suivante d’une clé d’ordre et le balayage des signaux perdus.
Lorsque chaque rôle a ses propres paramètres, comme les services Cloud Run, transmettez la même valeur à tous :
routes='federation.*=projects/p/locations/l/queues/my-federation@https://federation-worker.example.com'gcloud run services update my-web --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"gcloud run services update my-worker --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"gcloud run services update my-federation-worker --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"Un processus avec d’autres routes ne lève aucune erreur et ne perd aucune tâche : ses signaux vont vers une autre file, et les tâches s’y exécutent, en dehors de la capacité que vous avez définie.
my.queue.oldest_ready_age ne le montre pas, car ces tâches n’attendent pas. Pour comparer les processus, chacun consigne au démarrage une ligne avec ses routes et leur routes_hash :
le hachage doit être le même partout. Pour voir où vont les signaux, lisez les métriques propres à la plateforme de chaque file.
Permissions. Les identifiants de chaque processus doivent pouvoir envoyer vers chaque file des routes : roles/cloudtasks.enqueuer.
Un envoi qui échoue est consigné et non retenté sur une autre file, afin qu’un type que vous limitez ne déborde pas vers les autres. Ces tâches démarrent en retard, une fois que le balayage renvoie leurs signaux après 2 minutes.
Capacité. N’importe quel récepteur exécute n’importe quelle tâche ; vous choisissez donc jusqu’où les séparer :
| Plateforme | Un seul récepteur | Récepteurs distincts |
|---|---|---|
| Google Cloud | Un service. Chaque file a ses propres maxConcurrentDispatches et maxDispatchesPerSecond ; la limite d’instances du service est partagée |
Un service par file, nommé par l’URL dans la route, chacun avec sa propre limite d’instances et sa simultanéité. Chacun définit queue_cloudtasks_url sur sa propre URL |
Une file nécessite la même configuration que celle par défaut : le rôle sur la file. Seule la file par défaut a besoin du tick.
Ce qu’ajoute une file. Chaque file est une chose de plus à créer, surveiller et payer, et son importance dépend de la taille de votre serveur.
Répartissez ce que vous avez vu attendre dans my.job.wait, pas tout.
Le balayage. Chaque minute, le balayage cherche les tâches dues depuis plus de 2 minutes sans s’être exécutées, jusqu’à 500 par route et 500 pour la file par défaut, et les signale de nouveau. Une file qui ne suit pas reçoit donc jusqu’à 500 signaux en double par minute. Ils n’exécutent pas une tâche deux fois, mais ce sont des messages que vous payez, et ils cessent une fois l’arriéré résorbé.
Les clés d’ordre tiennent toujours : la base de données décide de ce qui peut s’exécuter. Les tâches d’une même clé peuvent se trouver sur des files différentes, mais une file bloquée retarde aussi les tâches suivantes de ses clés.
Ajouter, déplacer et supprimer une file.
- Créez la file et son récepteur, et donnez à chaque processus la permission d’y envoyer.
- Modifiez les routes sur chaque processus. Tant qu’elles diffèrent, les signaux vont vers l’une ou l’autre file et les tâches s’exécutent aux deux endroits.
- Pour supprimer une file, retirez-la d’abord des routes partout, et attendez qu’elle soit vide avant de la supprimer. Un signal dans une file supprimée est perdu, pas sa tâche : le balayage signale de nouveau la tâche une fois qu’elle est due depuis 2 minutes. Une tâche Cloud Tasks peut porter le signal d’une tâche jusqu’à 30 jours à l’avance ; une tâche due plus tard que l’attente est donc simplement signalée par le balayage lorsque son heure arrive.
Vérifications d’état
Section intitulée « Vérifications d’état »| Chemin | Type | Quand il renvoie 200 |
|---|---|---|
GET /healthz, GET /health/live |
vivacité | Le processus peut répondre en HTTP. Il ne regarde pas les dépendances telles que la base de données (de sorte qu’une base de données lente ne redémarre pas le processus) |
GET /readyz, GET /health/ready |
disponibilité | La base de données est joignable et le schéma est appliqué |
GET /api/v1/instance/health |
Surveillance de disponibilité, pages d’état et clients (servi par le rôle web) |
Comme la disponibilité. Le résultat est mis en cache dans le processus pendant 60 secondes |
- Cloud Run réserve certains chemins qui se terminent par
z, dont/healthz, et y répond lui-même par un404; derrière lui, appelez/health/liveet/health/ready, qui répondent de la même façon. - Un 200 de n’importe lequel d’entre eux a pour corps
{"status":"ok"}. /readyzvérifie la base de données à chaque requête, et les requêtes simultanées partagent une seule vérification./api/v1/instance/healthrenvoie 200 et{"status":"ok","checked_at":"<RFC 3339>"}lorsque tout va bien, et 503 et{"status":"unavailable","checked_at":...}en cas d’échec (Cache-Control: no-store). Chaque processus ne touche la base de données qu’une fois par minute au plus, quelle que soit la fréquence à laquelle il est surveillé ou sollicité, et il ne regarde ni le jeton d’accès ni la limite de débit. Faites pointer les moniteurs de disponibilité vers ce point de terminaison, pas vers la sonde (/readyzou/health/ready). Pour la configuration par service, l’intervalle de surveillance et son coût, et le traitement de la maintenance, voir le guide de surveillance de la disponibilité.- Les trois écrivent au niveau Debug dans le journal d’accès et ne créent aucun span de trace.
- Lorsque la disponibilité n’est pas assurée, la réponse est un 503 avec un corps RFC 9457
application/problem+json. Sontitleest traduit selonAccept-Languageet ne contient aucun détail interne. La cause (une erreur de connexion, ou les noms des tables manquantes) va dans le journal. - Une vérification de disponibilité est interrompue au bout de 3 secondes.
- La disponibilité exige aussi que la base de données contienne les
hostetaccount_domainconfigurés, ou que le processus ait pu les enregistrer. - Schéma appliqué signifie que toutes les tables que déclarent avec
CREATE TABLEles fichiers de schéma de la base de données (schema/<NN>-<module>/<dialect>.sql) existent (SQLite est vérifié parsqlite_schema, PostgreSQL par lecurrent_schema()de la connexion).my schema applyapplique tout le schéma ; une table manquante signifie donc que le schéma n’est pas appliqué ou qu’il est plus ancien que le binaire. Les différences de colonnes et d’index ne sont pas vérifiées ;my schema apply -dry-runaffiche ce qui changerait.
Requêtes qui contournent le CDN
Section intitulée « Requêtes qui contournent le CDN »Lorsque le serveur est derrière un CDN et que sa propre adresse reste publique, définissez origin_secret et origin_secret_header afin qu’il refuse ce qui n’est pas passé par le CDN. Les contrôles de santé restent joignables. Consultez Refuser les requêtes qui ne sont pas passées par le CDN.
En-têtes de sécurité
Section intitulée « En-têtes de sécurité »Chaque réponse porte Strict-Transport-Security, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy: same-site et X-Frame-Options,
et, pour les réponses qui ne sont pas des documents, Content-Security-Policy: default-src 'none'; frame-ancestors 'none'; base-uri 'none'.
Un gestionnaire les remplace pour les réponses qui nécessitent d’autres valeurs, comme le JSON ActivityPub et les médias publics.
Permissions-Policy refuse la caméra, la géolocalisation, le paiement et l’USB. Il refuse aussi le microphone, sauf lorsque le chat vocal est activé (voice n’est pas off) :
il autorise alors le microphone uniquement pour les pages de l’origine propre du serveur (microphone=(self)), afin que les navigateurs puissent parler dans un appel.
Le HTML du client web reçoit une CSP de document qui n’utilise pas de nonce (script-src 'self', etc.).
Elle exige Trusted Types (require-trusted-types-for 'script') et limite les politiques pouvant être créées aux deux du client (trusted-types my-server-sanitized-html my-service-worker).
Client web
Section intitulée « Client web »Un processus dont le role est web ou all sert le client web intégré au binaire.
| Chemin | Contenu | Cache-Control |
|---|---|---|
Tout GET qu’aucune autre route ne reconnaît (/, /@alice, /@alice/status/{id}, /settings, etc.) |
La coquille HTML de la SPA. Les paramètres de l’instance sont transmis dans <script type="application/json" id="config"> |
public, max-age=60, stale-while-revalidate=300, ETag |
GET /assets/* |
Fichiers de construction avec des noms hachés | public, max-age=31536000, immutable, ETag |
GET /manifest.webmanifest |
Le manifeste de l’application web construit à partir des paramètres de l’instance | public, max-age=60, stale-while-revalidate=300, ETag |
GET /sw.js, /icon.svg et les autres fichiers directement sous la construction |
Servis tels quels | no-cache, ETag |
GET /licenses/* |
Les licences de ce que la construction embarque (avis des paquets npm, et LICENSE-Unicode.txt et OFL.txt pour les données non npm embarquées). Servis en text/plain; charset=utf-8 quelle que soit l’extension |
no-cache, ETag |
GET /robots.txt, /.well-known/tdmrep.json, /.well-known/security.txt |
Construits à partir des paramètres de l’instance (voir Moteurs de recherche et robots d’IA) | public, max-age=3600, ETag |
- Les chemins sous
/api,/oauth,/auth,/.well-known,/nodeinfo,/ap,/media,/uploads,/theme(la feuille de style du thème du serveur) et/licenses, ainsi que/robots.txt, ne renvoient jamais la coquille ; si aucune autre route ne correspond, ils renvoient un problème 404. - La coquille est servie après la négociation de contenu ActivityPub. Demander un chemin de coquille avec un
AcceptActivityPub renvoie 404 (les pages de publication redirigent, comme décrit ci-dessous). La coquille porte toujoursVary: Accept. Lorsque vous placez un CDN devant, incluez le type d’Accept(ActivityPub ou HTML) dans la clé de cache, ou excluez du cache la coquille,/ap/*et/@*. Ne servez par le CDN que/assets/*. - Les fichiers texte de la construction (scripts, feuilles de style, images SVG, avis de licence) sont intégrés compressés uniquement. Une requête qui accepte Brotli les reçoit avec
Content-Encoding: br, une qui accepte gzip avecContent-Encoding: gzip, et toute autre requête les reçoit décompressés, toujours avecVary: Accept-Encodinget un ETag pour chaque encodage. Un proxy placé devant n’a besoin d’aucune compression propre pour eux, et un CDN doit conserverVary: Accept-Encoding(ou l’encodage) dans sa clé de cache pour/assets/*. - La coquille et les écrans de connexion portent des en-têtes
Linkqui nomment les feuilles de style et le script d’entrée que la page charge en premier, à partir desquels un CDN comme Cloudflare (sa fonction Early Hints) peut produire ses propres indications précoces. Avecweb_early_hints=true, le serveur les envoie aussi en premier dans une réponse103 Early Hints, afin que le navigateur récupère les fichiers pendant que le serveur prépare la page. Il est désactivé par défaut, car un proxy qui ne sait pas transmettre un 103 peut faire échouer la requête :- Un Application Load Balancer externe de Google Cloud répond 502 ou 503 (
backend_interim_response_not_supported) : laissez-le désactivé derrière un tel répartiteur, comme le fait le déploiement Cloud Run. - nginx le transmet à partir de la 1.29.0, avec
early_hintsdéfini. - Le
reverse_proxyde Caddy le transmet ; une directiveencodel’abandonne dans les versions antérieures à la 2.8. - Les navigateurs n’utilisent un 103 que pour une page vers laquelle ils naviguent, et Chrome et Edge seulement via HTTP/2 et HTTP/3.
- Un Application Load Balancer externe de Google Cloud répond 502 ou 503 (
- Un binaire construit sans le client web (un simple
go build, sans construire d’abord le client) journalise un avertissement au démarrage et sert une coquille sans scripts.
Points de terminaison de fédération
Section intitulée « Points de terminaison de fédération »Un processus dont le role est web ou all répond à ces points de terminaison, que les autres serveurs du fédivers utilisent pour trouver et afficher vos comptes.
| Chemin | Contenu |
|---|---|
GET /.well-known/webfinger |
WebFinger (RFC 7033). resource est acct:alice@{account_domain} (acct:alice@{host} fonctionne aussi), un id d’Actor, ou l’URL /@alice. subject est toujours l’identifiant du côté account_domain |
GET /.well-known/host-meta, /.well-known/host-meta.json |
Le modèle d’URI WebFinger (XRD / JRD) |
GET /.well-known/nodeinfo, GET /nodeinfo/2.1 |
NodeInfo 2.1. metadata.sourceCode est le paramètre source_url, et software.repository est aussi défini pour une URL https: (consultez Publier le code source) |
GET /ap/actors/{uuid} |
L’Actor (publicKey est le #main-key RSA). Une requête qui préfère le HTML reçoit un 303 vers /@{username} |
GET /ap/actors/{uuid}/{outbox,followers,following,featured,featured-tags} |
Collections |
POST /ap/actors/{uuid}/inbox, POST /ap/inbox |
La boîte de réception de chaque acteur local et la boîte de réception partagée. Les requêtes doivent être signées en HTTP |
GET /@{username} |
Un 302 vers l’id de l’Actor pour un Accept ActivityPub ; sinon le HTML du client web (voir ci-dessous) |
GET /@{username}/status/{uuid} |
Pour un Accept ActivityPub, un 302 vers l’id (/ap/objects/{uuid}) de la publication si un visiteur non connecté peut la voir, et 404 sinon. Sinon le HTML du client web |
- L’identifiant de l’Actor du serveur est
{account_domain}@{account_domain}(la même forme que Mastodon). - Un compte qui n’existe pas ou ne peut pas être affiché (suspendu, désactivé, supprimé ou distant) reçoit toujours le même 404 (
Cache-Control: no-store). - Les réponses anonymes portent
Cache-Control: public, max-age=60. Les réponses qui varient selonAcceptportentVary: Accept. Pour un CDN qui ne gère pasVary: Accept, excluez/ap/*et/@*du cache.
Domaines distincts pour l’identifiant et la remise
Section intitulée « Domaines distincts pour l’identifiant et la remise »Lorsque account_domain diffère de host, les requêtes vers /.well-known/webfinger, /.well-known/host-meta et /.well-known/nodeinfo du côté account_domain sont redirigées vers host avec un 301 (avec Access-Control-Allow-Origin: *).
Si vous acheminez les requêtes de account_domain vers ce serveur, le serveur renvoie lui-même cette redirection.
Si un autre serveur ou reverse proxy répond à sa place, redirigez vers https://{host} en conservant le chemin et la chaîne de requête.
Pour les LLM et les agents de programmation :llms.txt,llms-full.txt, llms-small.txt