Tâches de fond
Une application qui doit faire quelque chose en dehors d’une requête (envoyer
une notification une fois la réponse partie, purger les anciennes lignes
chaque nuit, réessayer un appel qui a échoué) le confie au framework, qui
l’exécute sur des threads d’arrière-plan du processus qui sert, ou d’un
processus worker séparé. Un job est une classe dans app/jobs/, comme dans
Rails. Les jobs et les tâches planifiées demandent require "cybertrain/jobs"
dans bin/<app>.rb et bin/db.rb, que cybertrain generate job ajoute
(Sous-systèmes) :
# app/jobs/welcome_job.rb
class WelcomeJob < Cybertrain::Job::Base
retry_on Cybertrain::Mailer::TimeoutError, wait: 60, attempts: 5
discard_on ArgumentError
def perform(args)
user = User.find(Cybertrain::Cast.int(args["user_id"]))
Cybertrain::Mailer.deliver(to: user.email, subject: "Welcome", body: "Hello!\n")
end
end
# dans une action, après l’enregistrement de l’utilisateur
WelcomeJob.perform_later("user_id" => @user.id)
WelcomeJob.perform_in(600, "user_id" => @user.id) # ou perform_at(time, args)
# config/app.rb (ou un fichier que bin/<app>.rb requiert avant Cybertrain::Main.run)
Cybertrain::Scheduler.cron("0 4 * * *", "nightly digest", job: "DigestJob")
Cybertrain::Scheduler.every(300, "refresh rates") { Rates.refresh }
- Où cela s’exécute. Les jobs s’exécutent sur
job_threadsthreads de jobs (3,CYBERTRAIN_JOB_THREADS) ; les tâches planifiées sur un thread de scheduler bien à elles, si bien qu’un long job ne retarde jamais une tâche. Les deux démarrent quand le binaire sert (./<app>,./<app> server) ou tourne comme worker (./<app> worker, voir Rôles des processus), après que le démarrage a connecté la base de données et définiSPINEL_WORKERS; les commandesmigrate,db ...,jobs ...,consoleetMain.commandne les démarrent jamais, pas plus queCybertrain::Test::Client. Avec les jobs requis, les threads de jobs démarrent dans chacun de ces processus, même dans une application sans classe de job : le framework enregistre son propre job de mail (Mailer.deliver_later, Envoyer des e-mails). - La table. Les jobs sont des lignes de
cybertrain_jobs, que le framework crée lui-même (CREATE TABLE IF NOT EXISTS, à la première utilisation) et laisse hors dedb/schema.rb. Dans uneDB.transaction, la ligne est validée ou annulée avec le reste. Chaque thread de jobs réserve la ligne échue la plus ancienne dans une courte transactionBEGIN IMMEDIATE, l’exécute hors de celle-ci et cherche la suivante ; quand rien n’est échu, il attendjob_poll_intervalsecondes (1), si bien qu’un job mis en file par une requête démarre en une seconde environ. Une ligne estqueued,running,done,failed(ses nouvelles tentatives sont épuisées ; elle reste là pour que vous l’examiniez) oudiscarded(undiscard_onl’a arrêtée).
Les classes de job
spin run gen lit chaque fichier sous app/jobs/ (y compris les
sous-répertoires : Admin::ReportJob dans
app/jobs/admin/report_job.rb) et écrit dans gen/jobs.rb l’autre moitié de
chaque classe qui a Cybertrain::Job::Base pour ancêtre :
perform_later, perform_at, perform_in, perform_now, job_kind et le
code qui l’exécute, puis enregistre la classe. cybertrain generate job
send_digest --retry Cybertrain::Mailer::TimeoutError:60:5 écrit un fichier
de classe et un test pour elle.
argsest le Hash donné àperform_later, stocké en JSON et relu comme unHash<String, Object>: affinez ses valeurs avecCybertrain::Cast.int(args["user_id"]),Cast.str,Cast.hash,Cast.array. Un job prend ce seul Hash ; passez des ids, pas des enregistrements (c’est aussi le conseil de Rails).perform_laterlèveArgumentErrorpour tout ce qui n’est pas un Hash, et sans argument envoie{}.- Mise en file.
perform_later(args),perform_at(time, args)etperform_in(seconds, args)renvoient l’id de la ligne ; le kind de la ligne est le nom de la classe ("WelcomeJob","Admin::ReportJob").perform_now(args)exécuteperformsur le thread appelant, sans file, sans politique de nouvelle tentative et sans rescue, et renvoienil: la forme qu’attend un test. - Le corps de la classe. Chaque classe de job définit
perform(args)(le générateur refuse une classe qui ne le définit ni n’en hérite).retry_on,discard_onetlimits_concurrencysont lus comme du texte, un par ligne avec des valeurs littérales (un Integer ou:polynomially_longerpourwait:, un Integer pourattempts:etto:, une String entre guillemets pourkey:) ; un bloc, une lambda,5.minutes, une flèche=>ou un commentaire en fin de ligne arrêtespin run genavec le fichier, la ligne et ce qu’il faut écrire à la place. -
Quelles classes d’exception. Un
retry_onou undiscard_onnomme une classe que le programme définit avant le job : une classe du cœur de Ruby (ArgumentError,KeyError, ...), toute classe d’exception du framework, quel que soit son nom (Cybertrain::RecordNotFound,Cybertrain::RecordInvalid,Cybertrain::DB::Error, ... ; la liste estGen::JobScan::FRAMEWORK_ERRORS, et le générateur ajoute le require dont a besoin une classe hors du cœur), ou une classe de l’application définie dansapp/models/, dansapp/jobs/application_job.rbou au-dessus de la ligne dans le fichier du job lui-même. Tout le reste, une classe du harnais de test comprise, arrêtespin run gen, commePATH:LINE: Cybertrain::Test::AssertionFailed is not a class this program defines (spikes/NOTES.md rule 89): sous Spinel, unrescuequi nomme une classe que le programme ne définit pas peut avaler toutes les exceptions. LeNotifyCommentJobd’examples/blog abandonne un job dont le commentaire a été supprimé et retente tout le reste :ruby class NotifyCommentJob < Cybertrain::Job::Base discard_on Cybertrain::RecordNotFound retry_on StandardError, wait: 30, attempts: 3 def perform(args) comment = Comment.find(Cybertrain::Cast.int(args["comment_id"])) # ... end endLes bras sont essayés dans l’ordre écrit et le premier qui correspond l’emporte, donc la classe la plus étroite vient d’abord ; Rails examine d’abord le gestionnaire déclaré en dernier, si bien que dans une application Rails ces deux lignes vont dans l’autre sens. L’abandon est journalisé
job 12 (NotifyCommentJob) discarded: Cybertrain::RecordNotFound: Couldn't find Comment with id=7. ApplicationJob. Une classeApplicationJob < Cybertrain::Job::Basedansapp/jobs/application_job.rbn’est pas un job à part entière : ses lignesretry_onetdiscard_ons’appliquent à chaque job qui en hérite, après celles du job, et sonlimits_concurrencyà un job qui n’en déclare aucun. Toute autre classe de job peut être un parent ; c’est alors un job à part entière.-
Job.handle, la forme courte. Un bloc enregistré sous un kind String ne demande ni classe ni générateur ; il reçoit la charge utile String et la politique par défaut ci-dessous :ruby # config/app.rb Cybertrain::Job.handle("notify", concurrency: 1) { |payload| Notifier.post(payload) } # n’importe où, plus tard Cybertrain::Job.enqueue("notify", JSON.generate({ "text" => "Deployed" }), run_at: Time.now + 60)Les classes de job et les kinds de
Job.handlepartagent un seul espace de noms, si bien queJob.enqueue("WelcomeJob", json)ajoute la même ligne queperform_later.Job.enqueuerefuse un kind non enregistré.
Nouvelles tentatives et abandons
- La politique par défaut. Une exception qu’aucune ligne de la classe ne
reconnaît (et toute exception d’un bloc
Job.handle) est réessayée 1, 5, 15 puis 60 minutes plus tard, avecClass: message(jusqu’à 1000 caractères) danslast_error, jusqu’à ce quejob_max_attempts(5) tentatives aient échoué ; la ligne passe alors àfailed. UnNotImplementedError(un helper pas encore écrit), unSystemStackErrorou un autreScriptErrorlevé par le code du job suit cette politique aussi, bien qu’aucun ne soit unStandardError; toute autre exception hors deStandardErrorest journalisée (ERROR Job thread N: ...) et signalée, le thread de jobs continue, et la ligne resterunningjusqu’à ce que la reprise (ci-dessous) la prenne. retry_on Klass, wait: 60, attempts: 5.wait:est un nombre de secondes (3 s’il est omis, la valeur par défaut de Rails) ou:polynomially_longer(attempts ** 4 + 2secondes : 3, 18, 83, 258, ...) ;attempts:(5 s’il est omis) compte chaque tentative, la première comprise. Plusieurs lignes sont permises : la première dont la classe reconnaît l’exception (une sous-classe est reconnue) l’emporte, donc écrivez la classe la plus étroite d’abord.retry_on StandardErroravantdiscard_on ArgumentErrorréessaie l’ArgumentError.discard_on Klassarrête tout de suite : la ligne passe àdiscarded, avec l’erreur danslast_error, et n’est jamais réessayée. Le journal ditERROR [<Kind> <id>] [<request id>] job <id> (<Kind>) discarded: <Class>: <message>(l’identifiant de requête quand une requête a mis le job en file), et l’abandon est signalé une fois, avecjob.max_attemptségal àjob.attempt.def retries_exhausted(error)s’exécute quand les tentatives d’une ligneretry_onsont épuisées, une fois la ligne réellementfailed(jamais pour une tentative qu’un autre worker a reprise et dont l’exécution peut encore réussir). C’est le blocretry_on ... do |job, error|de Rails ; une exception qu’il lève est journalisée.- La reprise (ci-dessous) suit elle aussi la classe : une ligne d’une
classe avec
attempts: 20dont le processus est mort à la tentative 5 est remise en file, pas marquée en échec.
Concurrence par kind et par clé
limits_concurrency to: 1, key: "account_id" laisse au plus to: jobs de la
classe s’exécuter en même temps dans tous les processus qui partagent la
base, comptés par valeur de args["account_id"] (to: seul compte pour
toute la classe ; Job.handle(kind, concurrency: n) fait de même pour un
bloc). Les autres kinds, et les autres clés, continuent de s’exécuter
pendant ce temps. Mettre en file un job à clé dont les args n’ont pas la
clé lève ArgumentError. La limite compte les lignes running, elle tient
donc tant que les battements de cœur tiennent : un job qui tourne encore
après que son battement de cœur est devenu périmé est chevauché par la
prochaine exécution de la ligne reprise (ci-dessous) ; un travail qui ne
doit jamais se chevaucher a besoin de sa propre garde.
Les tâches planifiées
Scheduler.every(seconds, name) { ... } exécute un bloc toutes les
seconds ; Scheduler.cron(expr, name, ...) s’exécute aux minutes que
désigne une expression cron à cinq champs :
Cybertrain::Scheduler.cron("12 * * * *", "collect prices") { Prices.collect }
Cybertrain::Scheduler.cron("0 9 * * 1-5", "morning report", tz: "Asia/Tokyo",
job: "MorningReportJob", args: { "scope" => "all" })
Cybertrain::Scheduler.cron("*/5 * * * *", "poll feeds", catch_up: true) { Feeds.poll }
- L’expression. Minute, heure, jour du mois, mois, jour de la semaine,
avec
*,*/n,a-b,a,b,a-b/net les nomsjan-decetsun-sat(les jours0et7sont le dimanche) ;@hourlyet ses semblables ne sont pas acceptés. Une expression illisible, ou qui ne correspond jamais, lèveArgumentErroren nommant la tâche au chargement deconfig/app.rb, ce qui arrête le démarrage. - Fuseaux horaires.
tz:nomme un fuseau IANA (Fuseaux horaires) ; sans lui, la tâche litscheduler_tz(CYBERTRAIN_SCHEDULER_TZ, qui suit letime_zonede l’application quand il n’est pas réglé). Une heure murale que le passage à l’heure d’été saute ne s’exécute pas ce jour-là. Dans l’heure répétée du changement d’automne, une expression dont le champ des heures commence par*s’exécute aux deux occurrences et une expression à heure fixe une seule fois, comme le fait Vixie cron. job:nomme un kind de job (un nom de classe en String, ou un kind deJob.handle) etargs:ses arguments : la tâche ne fait alors que le mettre en file, ce que devrait faire une tâche qui a du vrai travail. Un kind inconnu arrête le démarrage avec la liste des kinds enregistrés.- Le calendrier est conservé dans la base (
cybertrain_schedules, hors dedb/schema.rb) : quand chaque tâche s’est exécutée pour la dernière fois et quand elle s’exécutera ensuite. Un redémarrage, ou un autre processus qui prend la tête, reprend à partir de lui. Une tâcheeverydont l’heure est passée pendant que rien ne tournait s’exécute une fois au démarrage ; un créneaucronmanqué pendant que rien ne tournait est sauté (la règle de cron), sauf si la tâche indiquecatch_up: true, qui l’exécute une fois au démarrage. Un créneau échu pendant que des processus tournaient sans qu’aucun leader l’exécute (un bail qui change de mains) s’exécute une fois lors de la reprise. Une tâche que vous renommez ou supprimez garde sa ligne jusqu’au démarrage suivant. Une tâche qui n’a pas encore tourné suit son horaire actuel quand celui-ci tombe plus tôt que la prochaine exécution qu’une version précédente a enregistrée (une tâche hebdomadaire rendue horaire avant sa première exécution tourne dans l’heure). - Comment une tâche s’exécute. Un bloc s’exécute sur le thread du
scheduler, une tâche à la fois ; chaque exécution est enveloppée dans
un rescue qui journalise
ERROR [schedule:name] Scheduled task "name" failed: ...et le signale, et la boucle continue. Le bloc ne prend pas d’argument (Spinel n’a pas d’instance_eval). Un appel SQLite garde son worker système jusqu’à son retour : avecSPINEL_WORKERS=1(la valeur par défaut), une longue requête bloque toutes les requêtes HTTP, et tous les autres threads, aussi longtemps. Confiez à un job une tâche qui a du vrai travail (job:, ouJob.enqueuedepuis le bloc), et découpez les gros travaux (mille lignes par exécution, un job par élément).Cybertrain::Scheduler.last_tickest la seconde epoch du dernier tick, pour un contrôle de santé de votre cru.
La page des jobs et la commande jobs
# config/routes.rb
Cybertrain::Routes.draw do
jobs_page "/admin/jobs", before_action: :require_admin, skip_before_action: :require_authentication
end
jobs_page monte une page qui liste le nombre de lignes par état, le nombre
de lignes en file et la prochaine échéance, les lignes failed et
discarded (kind, arguments, erreur, tentatives, dates) et les lignes
running (qui les a réservées, l’âge de leur battement de cœur), à raison de
jobs_page_per_page (50, CYBERTRAIN_JOBS_PAGE_PER_PAGE) lignes par liste.
Une ligne en échec peut être réessayée (remise en file tout de suite,
tentatives remises à zéro), abandonnée ou supprimée, une ligne abandonnée
réessayée ou supprimée, et toutes les lignes en échec réessayées ou
abandonnées d’un coup ; chaque action ne touche que les lignes failed
et discarded, si bien qu’une ligne qu’un worker vient de réserver est
laissée tranquille.
- Le contrôleur généré hérite d’
ApplicationController, si bien que le layout, les helpers et la protection CSRF de l’application s’appliquent, etbefore_action:nomme l’une de ses méthodes : elle doit rendre une réponse ou rediriger pour refuser.cybertrain generate authenticationdessine la ligne ci-dessus, avec lerequire_adminde son concern (404 sauf si un administrateur est connecté ; Administrateurs). Sansbefore_action:, la page est ouverte à tous les visiteurs, etspin run genaffiche un avertissement qui le dit. skip_before_action:nomme un before callback hérité que la page n’exécute pas. Avec:require_authentication,require_adminrépond seul à un visiteur, par un 404 plutôt qu’une redirection vers la connexion. gen le refuse sansbefore_action:, et quand il nomme lebefore_action:lui-même.- Ses boutons sont des formulaires avec le jeton CSRF. Gardez le chemin de
la page hors de
csrf_exempt_prefixes: sous un préfixe exempté, ces formulaires seraient acceptés depuis n’importe quel site.
Depuis un shell, ./<app> jobs fait de même sur la base configurée (il ne
démarre aucun thread) :
./blog jobs list # lignes en échec, les plus récentes d’abord (les 1000 plus récentes) ; ou : list queued|running|done|discarded
./blog jobs retry 42 # ou : retry --all (toutes les lignes en échec)
./blog jobs discard 42
./blog jobs delete 42
./blog jobs prune --before 30 # supprime les lignes failed et discarded de plus de 30 jours (7 par défaut)
Les lignes done restent jusqu’à ce que quelque chose les supprime :
Job.prune_done(before_epoch) depuis une tâche
(Cybertrain::Scheduler.cron("0 3 * * *", "prune done jobs") {
Cybertrain::Job.prune_done(Time.now.to_i - 7 * 86_400) }).
Job.state_count("failed") sert une page de santé de votre cru.
Plusieurs workers, au moins une fois, arrêt
- Plusieurs workers par base. Chaque processus qui exécute des jobs écrit
un battement de cœur pour les jobs qu’il exécute toutes les
job_heartbeat_interval(30 s). Une lignerunningdont le battement de cœur est plus ancien quejob_heartbeat_stale(un processus qui a planté ou a été arrêté en plein job) est remise en file par le premier processus qui regarde, à son démarrage puis une fois par minute, sauf si cette tentative était sa dernière (la plus grande dejob_max_attemptset de la plus grande valeurattempts:de la classe) : la ligne reste alorsfailed, avecprocess stopped (heartbeat stale)danslast_error, si bien qu’un job qui tue son processus n’est pas réessayé indéfiniment. Les tâches planifiées s’exécutent dans un seul processus à la fois : les processus partagent un bail dans la base (cybertrain_leases, renouvelé à chaque tick,scheduler_lease_ttl30 s), et seul son détenteur exécute les tâches échues ; un autre prend le relais quand il cesse de le renouveler. Le bail est renouvelé avant chaque tâche, pas pendant qu’elle s’exécute, si bien qu’une tâche plus longue que le ttl peut chevaucher celle du détenteur suivant : gardez les tâches courtes et sûres à répéter. Ainsi deux processusworker, ou un serveur et un worker, peuvent partager un même fichier SQLite ;CYBERTRAIN_WORKER=0désactive les jobs, les tâches et les flux dans un processusserverqui ne doit servir que le HTTP. - Au moins une fois. Un job peut s’exécuter deux fois : un processus
tué, ou bloqué plus longtemps que
job_heartbeat_stale(300 s), peut être encore en train d’exécuter un job quand un autre processus reprend la ligne. Seul compte le résultat de la réservation qui détient la ligne (le résultat d’un réservataire précédent, qui finit en retard, est écarté), mais les effets de bord du job ont eu lieu deux fois ; écrivez donc des jobs qui peuvent sans danger s’exécuter à nouveau (vérifier si le mail est déjà parti, faire un upsert plutôt qu’un insert), comme avec toute file de jobs. Une tâche planifiée peut s’exécuter deux fois autour d’un changement de leader pour la même raison. - Arrêt. Sur
SIGTERM, les threads de jobs cessent de réserver de nouveaux jobs, et le processus attend jusqu’àjob_drain_timeout(10 s) les jobs en cours. Un job encore en cours garde alors sa lignerunning; son battement de cœur s’est arrêté, si bien qu’un autre processus l’exécute à nouveau une fois périmé. - Tests.
WelcomeJob.perform_now(args)exécute un job,Cybertrain::Scheduler.run_due(now)un tick etCybertrain::Job.work_one(now)un job en file, avec un temps epoch de votre choix, si bien qu’un test ne dort jamais ; Tester les jobs donne les assertions.
Mise à jour depuis 0.4
cybertrain_jobsgagne la colonneconcurrency_keyet l’étatdiscarded; le premier processus qui touche la table ajoute la colonne. Le code qui liste les états (un tableau de bord surJob.state_count) ajoutediscarded.Job.prune_donene purge toujours que les lignesdone.- Les tâches
everyreprennent à partir du calendrier après un redémarrage au lieu de repartir de zéro : un intervalle écoulé pendant que le processus était arrêté s’exécute une fois au démarrage. - Donner une clé à un kind existant (
limits_concurrency ... key:) : arrêtez tous les anciens processus avant que le premier nouveau démarre, comme pour toute mise à jour (Rôles des processus). Le premier nouveau processus attribue leur clé aux lignesqueuedmises en file auparavant (il journalise les ids des lignes dont la charge utile n’a pas ce champ), et une lignerunninglaissée par un ancien processus reçoit sa clé quand elle est reprise. jobsest désormais une commande intégrée : une commande de l’application nomméejobsdoit être renommée.
Non construit : la priorité des jobs, les noms de file et l’unicité, un
mode de job en ligne pour les tests (perform_now et
perform_enqueued_jobs couvrent les tests). La conception :
docs/design.md D28 et D51 à D53.
Rôles des processus
Un seul binaire tourne dans trois rôles. Par défaut, ./<app> server fait
tout, comme rails server avec Solid Queue dans Puma ; les deux autres
permettent à un déploiement de répartir le travail entre des processus ou
des conteneurs, tous à partir de la même image et de la même base :
| Commande | Exécute | Écoute |
|---|---|---|
./<app> server [PORT] |
le HTTP, le point d’entrée des flux, et sauf avec CYBERTRAIN_WORKER=0 les tâches planifiées, les threads de jobs et les flux WebSocket |
oui |
./<app> worker |
les tâches planifiées (un processus à la fois, grâce au bail), les threads de jobs, les battements de cœur et la reprise | non |
./<app> feeds [NAME...] |
les flux WebSocket, tous ou ceux nommés | non |
workeretfeedsaffichent une bannière (=> worker: 3 job threads, 2 scheduled tasks), tournent jusqu’àSIGTERMouSIGINT(Ctrl-C) puis s’arrêtent comme le fait un serveur. Ils exécutent toujours leur travail :CYBERTRAIN_WORKER=0, réglé pour le rôle web, ne les désactive pas.feedsavec des noms n’exécute que ces abonnements (un conteneur par flux), et un nom inconnu arrête le démarrage avec la liste des noms enregistrés. Avec les flux dans leur propre processus, réglezCYBERTRAIN_WORKER=0sur les serveurs, sinon chaque processus recevrait chaque flux.- Un processus
feedsredémarre un flux dont le thread est mort, et se termine avec le statut 1 quand un même flux continue de mourir (feed_restart_limitredémarrages dansfeed_restart_window) ; lancez-le donc sous une politique de redémarrage (restart: unless-stoppedde Docker,Restart=alwaysde systemd) ; Consommer des flux WebSocket donne les détails../<app> feeds statusaffiche le dernier état signalé par chaque flux. - Un découpage typique :
serveravecCYBERTRAIN_WORKER=0derrière le proxy, un ou plusieursworker, etfeedss’il y a des abonnements.cybertrain newécrit un rôlewebet un rôleworkerdansconfig/deploy.yml(et unfeedsen commentaire) ; docs/deploy.en.md, partie 7, « Splitting the roles », donne les unités systemd. - Mise à jour depuis une version sans battements de cœur : arrêtez tous les anciens processus avant de démarrer le premier nouveau. Un nouveau worker prendrait pour abandonnés les jobs qu’un ancien exécute encore, puisqu’un ancien processus n’écrit aucun battement de cœur.
Cybertrain::Main.worker?(ARGV)etMain.feeds?(ARGV), commeMain.server?(ARGV), indiquent àbin/<app>.rbquel rôle il démarre.workerdemanderequire "cybertrain/jobs"dansbin/<app>.rb, etfeedsrequire "cybertrain/feeds"(quecybertrain/websocketcharge) ; sans elle, le binaire dit quelle ligne manque et sort avec 1.
Le cache
Cybertrain::Cache garde des réponses un certain temps dans la base de
l’application elle-même, pour que la requête suivante ne réinterroge pas
l’API lente. require "cybertrain" le charge ; une application sur
cybertrain/core ajoute require "cybertrain/cache" à bin/<app>.rb et
bin/db.rb, ou là où il sert :
require "cybertrain/cache"
text = Cybertrain::Cache.fetch("defillama/tvl", expires_in: 21_600, race_condition_ttl: 30) do
client.get("https://api.llama.fi/tvl").body
end
data = Cybertrain::Cache.fetch_hash("prices/#{sym}", expires_in: 60) { { "usd" => price } }
count = Cybertrain::Cache.fetch_int("articles/count", expires_in: 60) { Article.count }
Cybertrain::Cache.write("import-lock", "1", expires_in: 300, unless_exist: true) # true quand écrit
- Les valeurs sont des Strings.
fetch(key, expires_in:, race_condition_ttl:) { String }renvoie la valeur vivante, ou exécute le bloc et stocke ce qu’il renvoie ;fetch_hash,fetch_arrayetfetch_intstockent du texte JSON ou Integer et le relisent en sortie, si bien qu’une cellule corrompue se lit{},[]ou0jusqu’à ce qu’elle expire et que le bloc s’exécute à nouveau (Spinel n’a pas deMarshal, et une méthode renvoie un seul type).read(key)(une String, ou nil),write(key, value, expires_in:, unless_exist:),delete,exist?,increment(key, by: 1, expires_in:)(une seule instruction ; un compteur expiré repart deby, etexpires_in:ne fixe l’expiration qu’au départ du compteur, si bien qu’un compteur d’une minute compte cette minute) etclearcomplètent l’ensemble. - Expiration.
expires_in:est en secondes ;0, la valeur par défaut, n’expire jamais (une valeur négative non plus).race_condition_ttl: n: quand une ligne a expiré, le premier appelant la prolonge densecondes et calcule la nouvelle valeur pendant que les autres continuent de lire l’ancienne, comme dans Rails ; sans lui, chaque appelant d’une clé expirée calcule. Un bloc qui lève une exception n’écrit rien. - Stockage. Les lignes vivent dans
cybertrain_cache, que le framework crée à la première utilisation et laisse hors dedb/schema.rb. Rien n’est gardé en mémoire : chaque lecture est un SELECT, auquel SQLite répond depuis son cache de pages. Chaque écriture prend le verrou d’écriture de la base, qu’attendent les requêtes qui écrivent leurs propres lignes : mettez en cache ce que produisent les jobs, ou des valeurs lues bien plus souvent qu’elles ne changent, plutôt que d’écrire dans un chemin de requête chargé. - Purge. Avec les jobs chargés, requérir le fichier enregistre la tâche
planifiée
"cybertrain cache prune", qui supprime les lignes expirées toutes lescache_prune_intervalsecondes (300,CYBERTRAIN_CACHE_PRUNE_INTERVAL), mille par instruction. Sans les jobs, le cache se purge lui-même : la première écriture d’un processus, puis la première après chaquecache_prune_interval, supprime jusqu’à mille lignes expirées. L’intervalle est lu quand le fichier est requis : réglez la variable, ouc.cache_prune_intervaldans un blocCybertrain.configureexécuté avant le require.Cache.prune(now)est le point d’entrée des tests.
Non construit : un fichier de base séparé pour le cache, une taille
maximale, un stockage en mémoire. La conception : docs/design.md D54.
La console
./<app> console est une invite sur les modèles de l’application. Spinel
n’a pas d’eval, donc elle n’exécute pas de Ruby : elle évalue les
expressions qu’évalue le <%= %> d’un template (le langage de
templates, sans blocs), plus les noms de
modèles. En développement, lancez-la avec
cybertrain spin run <app> -- console.
./blog console
Cybertrain console (production). Type help for commands, exit to quit.
>> Article.where(title: "Hello").count
1
>> a = Article.find(1)
#<Article id: 1, title: "Hello", body: "First post", created_at: 2026-11-05 10:00:00 UTC, updated_at: 2026-11-05 10:00:00 UTC>
>> a.update(title: "Hello again")
true
- Un nom de modèle est sa relation (
Article), avecwhere,where_like,order,limit,offset,page,first,last,find,find_by,to_a,count,exists?,pluck_str/pluck_int/pluck_float,sum_int,count_by,delete_all,to_sqletcreate. Un enregistrement a ses attributs et ses méthodes,update,save,destroy,reload,valid?,errorsetattributes.helples liste tous. x = exprgarde une valeur pour les lignes suivantes, et_est la dernière valeur.sql "..."exécute du SQL et affiche les lignes en tableau, les caractères de contrôle d’une cellule échappés (\e,\n) : les données ne peuvent ni envoyer une séquence d’échappement au terminal ni casser le tableau (une valeur TEXT contenant un octet NUL est coupée au NUL à la lecture, comme dans toute lecture en SQL brut ; un BLOB garde tous ses octets) ;tablesliste les tables ;exit,quitou Ctrl-D quitte.- Une ligne qui ne s’analyse pas affiche son erreur, une ligne qui lève une
exception affiche
Class: message, et l’invite revient. Une valeur binaire s’affiche comme<N bytes>. - Les écritures sont réelles. En production, la console le signale d’abord dans une bannière.
./<app> dbconsole ouvre le shell sqlite3 sur la base configurée
(CYBERTRAIN_DATABASE), comme le dbconsole de Rails ; il faut que la
commande sqlite3 soit installée, et son code de sortie est transmis. Aucune
de ces deux commandes ne démarre le scheduler, les jobs ou les flux.
Exploitation : sauvegardes, VACUUM, contrôle de santé
Les données d’une application déployée tiennent dans un seul fichier SQLite,
donc le binaire embarque les trois outils d’exploitation dont une telle
application a besoin. Une application avec des envois de fichiers garde aussi
leurs octets sous sa racine d’envoi (upload_root, storage/uploads/ par
défaut) : sauvegardez ce répertoire et restaurez-le en même temps que la
base de données, sinon les enregistrements restaurés pointent vers des fichiers
absents (Ajouter un envoi de fichier).
Sauvegardes. ./<app> db backup PATH écrit une copie cohérente de la base
de données configurée (CYBERTRAIN_DATABASE) pendant que le serveur continue de
tourner : le VACUUM INTO de SQLite (3.27 ou plus récent ; le binaire
le vérifie) lit un seul instantané, et sous WAL les écritures du serveur se
poursuivent pendant ce temps. La copie est écrite dans un fichier temporaire à
côté de PATH, créé de façon exclusive avec le mode 0600 (le fichier contient
des condensats de mots de passe et des jetons de session), synchronisé sur
disque (fsync), et seulement ensuite renommé en PATH, de sorte qu’une copie
échouée ou interrompue ne laisse jamais de fichier partiel sous le vrai nom (le
fichier temporaire est supprimé). Un PATH existant est refusé sauf si vous
passez --force ; la base de données elle-même n’est jamais une cible, et
une base :memory: n’est jamais une source.
./blog db backup /srv/blog/backups/before-upgrade.sqlite3
./blog db backup /srv/blog/backups/ --keep 14 # blog-20261025T031500Z.sqlite3, les 14 plus récents sont conservés
Une cible qui se termine par / (ou un répertoire existant) reçoit un nom
daté, <app>-<YYYYmmddTHHMMSSZ>.sqlite3 en UTC, dans un répertoire créé avec le
mode 0700 s’il n’existe pas ; --keep N supprime alors les fichiers les
plus anciens ayant exactement cette forme au-delà de N et ne touche à rien
d’autre à cet endroit. Restaurer consiste à copier une sauvegarde par-dessus le
fichier de la base de données, serveur arrêté (et à supprimer les fichiers
-wal et -shm qui l’accompagnent).
VACUUM. Supprimer des lignes laisse des pages libres dans le fichier.
./<app> db vacuum lance VACUUM puis PRAGMA wal_checkpoint(TRUNCATE), de
sorte que les pages reconstruites atteignent le fichier de la base de données,
que le fichier est ramené à sa nouvelle taille et que le WAL est vidé ; il
affiche la taille sur disque (base de données plus WAL) avant et après.
VACUUM réécrit tout le fichier et détient le verrou d’écriture pendant ce
temps : lancez-le donc quand l’application est calme. Si un lecteur
empêche le checkpoint de se terminer, la commande le signale, et le WAL
diminue lors d’un checkpoint ultérieur.
Lancez les sauvegardes hors du serveur. Un appel SQLite occupe son worker
OS jusqu’à ce qu’il rende la main, donc un gros VACUUM INTO dans une tâche
Scheduler bloquerait les requêtes (avec SPINEL_WORKERS=1, toutes) pendant
toute la durée de la copie. Lancez plutôt la commande depuis cron ou un timer
systemd, dans un processus séparé :
# crontab de l’utilisateur de l’application : chaque nuit à 03:15, conserver deux semaines
15 3 * * * cd /srv/blog/current && ./blog db backup /srv/blog/backups/ --keep 14
Une application qui veut faire ses sauvegardes elle-même peut lancer son propre
binaire comme processus enfant depuis une tâche planifiée, plutôt que
d’exécuter le SQL sur son propre thread : system n’attend l’enfant que
sur le thread du scheduler, et les requêtes continuent d’être servies pendant
ce temps (utilisez system avec une liste d’arguments, jamais une chaîne
contenant des données de la requête). Une copie qui dure plus
longtemps que health_worker_stale fait répondre worker stale au contrôle de
santé jusqu’à ce qu’elle soit terminée.
# config/app.rb, dans un binaire servi lancé depuis son propre répertoire (dist/)
Cybertrain::Scheduler.every(86_400, "nightly backup") do
system("./blog", "db", "backup", "storage/backups/", "--keep", "14")
end
Contrôle de santé. Tant que le contrôle de santé est activé (il l’est par
défaut ; un config.health_path vide le désactive), l’application servie
répond à GET /up (et HEAD) avant les fichiers statiques, la session, le
CSRF et le routeur : aucun contrôleur n’intervient, aucun before_action
de connexion ne peut le rediriger, et il ne définit aucun cookie. Il exécute
SELECT count(*) FROM sqlite_master, qui doit lire la page du schéma dans le
fichier (un simple SELECT 1 n’y touche jamais), et répond en text/plain avec
Cache-Control: no-store :
| Statut | Corps | Quand |
|---|---|---|
| 200 | ok |
la requête a réussi |
| 503 | database unavailable |
elle a levé Cybertrain::DB::Error (le fichier est absent ou illisible, le pool est fermé) |
| 503 | worker stale |
le Scheduler d’arrière-plan tourne et son dernier tick est plus ancien que health_worker_stale secondes (300) : une tâche est bloquée, ou dure bien trop longtemps |
| 503 | feed stale |
un flux WebSocket, dans ce processus ou un autre, n’a pas signalé son état, ou n’a rien reçu (pas même un pong), depuis health_feed_stale secondes (180) ; voir Santé des flux |
Une interrogation est journalisée comme toute requête (deux lignes). Le chemin
est config.health_path (CYBERTRAIN_HEALTH_PATH, /up par défaut ; une
valeur vide désactive le contrôle, et le chemin passe alors à public/ et au
routeur comme avant). Un répartiteur de charge, kamal-proxy ou un script de
déploiement peut l’interroger ; public/up.html, qu’écrit
cybertrain new et que sa configuration Kamal interroge toujours, montre
seulement que le processus répond en HTTP.
Journaux
Le framework et l’application journalisent par Cybertrain.logger, une ligne
par message sur la sortie standard, vidée après chaque ligne, comme le fait une
application douze facteurs (le journal de systemd, Kamal et Docker la
recueillent) :
2026-11-14T09:30:00.120Z INFO [3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c] Started GET "/articles" for 127.0.0.1
2026-11-14T09:30:00.132Z INFO [3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c] Completed 200 in 12ms
2026-11-14T09:30:01.002Z ERROR [WelcomeJob 42] [3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c] job 42 (WelcomeJob) attempt 1 of 5 failed: RuntimeError: smtp down; retrying in 60 s
2026-11-14T09:30:02.410Z WARN [feed:prices] WebSocket "prices" silent for 60s; reconnecting
Une ligne est l’heure UTC à la milliseconde (dans un test, elle suit
travel_to), le niveau en majuscules, les étiquettes entre crochets et le
message. Cybertrain.logger a debug, info, warn, error et fatal,
qui prennent chacun une String. Les lignes de plusieurs threads ne se mêlent
jamais : chaque ligne est construite entière, puis écrite en un seul
write sous un verrou tenu pour cette écriture seulement. Une écriture qui
échoue (un tube fermé) abandonne la ligne ; journaliser ne lève jamais
d’exception chez l’appelant. Un lecteur qui cesse de lire la sortie standard
(un tube plein) bloque tous les threads qui journalisent jusqu’à ce qu’il
lise de nouveau : gardez le collecteur en marche.
Un événement, une ligne. Un saut de ligne dans un message ou dans une
étiquette s’écrit comme les deux caractères \n, un retour chariot comme
\r, si bien qu’un message de plusieurs lignes, ou un faux, ne peut pas
commencer une ligne à lui :
Cybertrain.logger.info("ok\n2026-11-11T12:00:00.000Z ERROR fake") écrit
une ligne :
2026-11-14T09:30:00.120Z INFO ok\n2026-11-11T12:00:00.000Z ERROR fake
Le seul saut de ligne tout à la fin d’un message est la fin de la ligne
elle-même et n’est pas échappé (info("done\n") écrit done) ; un
second l’est. Rien d’autre n’est échappé : une barre oblique inverse
reste telle quelle, et les tabulations, les autres octets de contrôle et
l’UTF-8 invalide sont écrits tels quels. Les lignes JSON échappent comme
avant.
Le niveau. c.log_level dans config/app.rb, ou CYBERTRAIN_LOG_LEVEL
(debug, info, warn, error, fatal ou none, en majuscules ou
minuscules), est le niveau le moins important écrit ; :info par
défaut. :none coupe aussi le journal des requêtes, et écrit toujours les
lignes d’erreur. Une affectation dans config/app.rb l’emporte sur la
variable. Toute autre valeur arrête le démarrage :
error: log_level must be :debug, :info, :warn, :error, :fatal or :none (got :verbose).
Lignes JSON. c.log_format = :json (ou CYBERTRAIN_LOG_FORMAT=json)
écrit plutôt un objet JSON par ligne, pour un collecteur de journaux :
{"time":"2026-11-14T09:30:00.132Z","level":"INFO","request_id":"3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c","tags":[],"message":"Completed 200 in 12ms"}
request_id n’y est que lorsque la ligne en a un (dans une requête, ou dans
un job qu’une requête a mis en file) et que log_tags le montre ; tags
contient les autres étiquettes dans l’ordre. Quand un message (ou une
étiquette) n’est pas de l’UTF-8 valide, chacun de ses octets à partir de
0x80, ceux des caractères valides compris, est écrit comme l’échappement
\ufffd en JSON, si bien qu’un seul mauvais octet change tout le texte non
ASCII du message en caractères de remplacement ; un message valide est
écrit tel quel, et une ligne de texte garde les octets tels qu’ils ont été
journalisés. Un format autre que :text ou
:json arrête le démarrage :
error: log_format must be :text or :json (got :xml). La première ligne du
démarrage lui-même (l’avertissement sur mail_delivery_method :test hors
des tests) suit le format ; les avertissements sur un réglage
d’application dont la valeur est invalide (setting_int, setting_bool qui
reviennent à la valeur par défaut) sont journalisés
pendant que config/app.rb s’exécute, avant que le format soit connu, et sont
toujours des lignes de texte.
Le niveau et le format s’appliquent à ./<app> server, worker et feeds,
ainsi qu’aux commandes enregistrées, à jobs et à console, qui refusent une
valeur inconnue avec le même message et le statut de sortie 1 avant d’ouvrir
la base. migrate, db et dbconsole ne les appliquent pas : leurs
lignes sont du texte au niveau info.
Identifiants de requête
Chaque requête reçoit un identifiant, un UUID de version 4, que l’action lit
dans request.request_id et que la réponse renvoie dans X-Request-Id, y
compris sur le 403 du contrôle des hôtes, la redirection https de
force_ssl, les pages d’erreur, la page de diagnostic du développement et le
500 du serveur lui-même. Les 400 et 413 du serveur pour une requête qu’il ne
peut pas lire, qu’il renvoie avant que l’application ne la voie, n’en portent
pas. Chaque ligne journalisée pendant la requête porte l’identifiant comme
étiquette (la première, avec les log_tags par défaut), y compris les propres lignes Cybertrain.logger.info de
l’application, de même qu’un corps diffusé (stream do ... end, Server-Sent
Events) ou une connexion WebSocket ouverte par la requête, tant qu’elle reste
ouverte.
Cybertrain.logger.info("export #{report.id} for #{request.request_id}")
L’identifiant d’un proxy n’est pris que d’un proxy de confiance : quand
la connexion vient d’un proxy de confiance (CYBERTRAIN_TRUSTED_PROXY ou
CYBERTRAIN_TRUSTED_PROXIES, le contrôle que fait request.client_ip ;
L’adresse du client derrière un proxy)
et que son X-Request-Id fait de 1 à 255 lettres ASCII, chiffres et traits
d’union, la requête prend cet identifiant, si bien que le journal du proxy et
celui de l’application le partagent. Tout autre X-Request-Id, un en-tête
envoyé deux fois compris, est écarté et un nouvel identifiant créé ; il
n’est jamais modifié.
c.log_tags choisit les étiquettes de la requête, dans l’ordre :
[:request_id] par défaut, [:request_id, :remote_ip] pour ajouter
request.client_ip (désactivé par défaut : une adresse est une donnée
personnelle), [] pour aucune (l’en-tête est toujours envoyé). Toute autre
valeur arrête le démarrage :
error: log_tags may hold :request_id and :remote_ip (got :user_agent).
Étiquettes
Cybertrain.logger.tagged ajoute des étiquettes à chaque ligne journalisée
sur ce thread pendant le bloc, après celles de la requête, et les retire quand
le bloc se termine, y compris quand il lève ; il renvoie la valeur du
bloc. Les blocs s’imbriquent. Il n’existe pas de forme sans bloc.
Cybertrain.logger.tagged("billing", "order #{order.id}") do
Cybertrain.logger.info("charged 300")
# 2026-11-14T09:30:00.140Z INFO [3f2a9c1e-...] [billing] [order 7] charged 300
end
Les étiquettes appartiennent au thread : un thread que vous lancez commence sans, quelles que soient celles du thread qui l’a lancé. Le framework étiquette son propre travail de la même façon :
- Jobs. Les lignes de chaque tentative portent
[<JobClass> <id>](pour un job de bloc deJob.handle, son type), puis l’identifiant de la requête qui l’a mis en file :INFO [WelcomeJob 7] [3f2a9c1e-...] welcome 1. L’identifiant est enregistré dans la ligne du job (cybertrain_jobs.request_id) quoi que diselog_tags, et montré quandlog_tagscontient:request_id. Un job mis en file par un job enregistre l’identifiant de son parent ; un job mis en file par une tâche planifiée, un flux ou une commande n’en enregistre aucun. - Tâches planifiées.
[schedule:<name>]pendant qu’une tâche s’exécute, sa ligne d’échec comprise. - Flux.
[feed:<name>]sur chaque ligne que journalise le thread d’un flux, celles de ses callbacks comprises. Les lignes de redémarrage et d’abandon du superviseur, journalisées sur son propre thread, n’ont pas d’étiquette.
Signalement des erreurs
Cybertrain.error recueille les exceptions qui mettent fin à une requête, à
une tentative de job, à une tâche planifiée ou à un flux, ainsi que celles que
l’application signale elle-même, et remet chacune aux abonnés que
l’application ajoute et à Sentry (ou GlitchTip) quand un DSN est défini. Il est
dans le cœur ; l’envoi à Sentry est une ligne à part, que charge
require "cybertrain" et qu’une application sur cybertrain/core ajoute à
bin/<app>.rb (pas à bin/db.rb ;
Sous-systèmes). cybertrain new écrit les
lignes de cette section en commentaire : les variables dans
.env.example, un abonné dans config/app.rb, le DSN dans
config/deploy.yml et .kamal/secrets, et cette ligne dans le commentaire
de bin/<app>.rb :
require "cybertrain/error_reporter/sentry" # bin/<app>.rb, après require "cybertrain/core"
# Une exception que l'application a rattrapée, avec ce qu'elle sait :
begin
charge(order)
rescue PaymentError => e
Cybertrain.error.report(e, context: { "order_id" => order.id })
end
# Exécuter un bloc, signaler ce qu'il lève, continuer avec nil :
price = Cybertrain.error.handle(context: { "feed" => "prices" }) do
parse_price(text)
end
report(e, handled: true, context: {}) renvoie nil aussitôt : le
rapport est livré sur le thread propre du rapporteur. Les clés et les valeurs
du contexte deviennent des Strings, par-dessus le contexte qu’ajoute le
framework (l’identifiant et la tentative d’un job). handle(context: {}) { }
renvoie la valeur du bloc, ou nil après avoir signalé une StandardError (ou
JSON::ParserError, JSON::NestingError) levée par le bloc ; break v
dans son bloc fait renvoyer v à handle, et return sort de la méthode qui
l’entoure. Une exception hors de ces classes levée dans le bloc de handle
va jusqu’à l’appelant. Le signalement lui-même ne lève jamais d’exception
chez l’appelant : si le signalement échoue, le journal dit
error report failed: <Class>: <message> au niveau error.
Abonnés. Un abonné est une classe de l’application, une sous-classe de
Cybertrain::ErrorSubscriber qui définit report(event) :
# config/app.rb, au-dessus de la ligne qui l'abonne (bin/<app>.rb charge
# config/app avant app/, donc une classe sous app/ n'est pas encore chargée ici)
class AuditSubscriber < Cybertrain::ErrorSubscriber
def report(event)
Cybertrain.logger.warn("reported #{event.error_class}: #{event.error_message} at #{event.error_where}")
end
end
Cybertrain.error.subscribe(AuditSubscriber.new)
Chaque abonné reçoit chaque rapport, sur le thread du rapporteur, pas dans la
requête ou le job qui a échoué. Un abonné qui lève est journalisé au niveau
error, error subscriber AuditSubscriber failed: <Class>: <message>, et n’est
jamais signalé lui-même ; les autres reçoivent quand même l’événement.
L’événement est une valeur faite de Strings :
| Lecteur | Contenu |
|---|---|
error_class |
le nom de classe de l’exception, avec son espace de noms ("Cybertrain::DB::Error") |
error_message |
son message |
error_where |
"ArticlesController#create", "request" (aucune action n’a tourné), la classe ou le type d’un job, "cybertrain mail", "job thread", "schedule:<name>", "feed:<name>", ou "" |
error_request_id, error_request_method, error_request_path |
ceux de la requête, le chemin sans sa chaîne de requête et filtré comme le filtre le journal des requêtes ; dans un job, l’identifiant de la requête qui l’a mis en file ; "" hors d’une requête |
error_environment, error_release |
Cybertrain.config.env et c.release |
error_handled |
vrai pour report et handle, faux pour ce que le framework a signalé |
error_context |
un Hash{String => String} : le contexte de l’application, et job.id, job.attempt, job.max_attempts dans un job |
error_backtrace |
un Array<String>, vide dans un binaire de cybertrain build (ci-dessous) |
error_occurred_at |
un Time, tiré de l’horloge |
Ce qui est signalé sans une ligne de votre part :
- Une requête qui se termine en 500, une fois : une exception que
Cybertrain::ClientError.status_forassocie à 500 ou plus. Jamais un 4xx (un paramètre invalide, un échec CSRF, un 404), jamais ce querescue_froma traité. Si servir la page d’erreur lève ensuite une nouvelle exception (unpublic/500.htmlillisible), celle-ci est signalée aussi : deux rapports, chacun un vrai échec. - Les tentatives échouées d’un job (
wheresa classe ou son type ;job.attemptetjob.max_attemptsdans le contexte), sous la politique par défaut,retry_onoudiscard_on. Dans un job, la clé de dédoublonnage contient aussi l’identifiant du job (Livraison, ci-dessous) : deux jobs d’un même type qui échouent pareil font deux rapports, et une tentative d’un job qui échoue avec la classe et le message de sa propre tentative signalée moins d’une minute avant est journalisée mais pas signalée de nouveau (sous la politique par défaut la première reprise attend une minute, donc chaque tentative est signalée ; avecretry_on ..., wait: 30la tentative qui suit de 30 secondes une tentative signalée ne l’est pas). Un abandon est signalé une fois.job.max_attemptsvautjob_max_attemptssous la politique par défaut, leattempts:de la politique sousretry_on, et la tentative à laquelle il s’est arrêté sousdiscard_on. Un courrieldeliver_laterqui échoue relève du jobcybertrain mail. Une exception qui s’échappe de la boucle d’un thread de jobs, ou une erreur de base de données à cet endroit, a pourwherejob thread. - Une tâche planifiée dont le bloc lève, ou une tâche
cronsans exécution suivante dans les cinq ans (schedule:<name>). - Un
on_open,on_messageouon_tickde flux qui lève, un thread de flux qui meurt, et le superviseur qui abandonne un flux (Cybertrain::Background::FeedFailed, un nom sans classe derrière, avec le messagefeed <name> restarted <n> times in <w> s; exiting), tousfeed:<name>.
Une exception levée pendant l’écriture d’un corps diffusé (stream do ...
end, Server-Sent Events) ou d’une connexion WebSocket mise à niveau est
signalée une fois, après la ligne stream error: <Class>: <message> du
serveur, avec l’identifiant, la méthode et le chemin de la requête et le
where ArticlesController#index (stream) (request (stream) quand
aucune action n’a tourné). Un client parti (EOFError, IOError,
Errno::ECONNRESET, Errno::EPIPE sortis de l’écrivain) est journalisé
par cette ligne et non signalé. Non signalés : un job dont le type n’a
pas de handler, et, en développement, une exception que la page de
diagnostic lève elle-même en montrant une exception déjà signalée. Chaque
ligne de journal que le framework écrivait auparavant reste telle
quelle ; le rapport vient en plus.
Ce qui n’est jamais envoyé. Les paramètres, les en-têtes, les cookies,
la session, l’adresse du client et la chaîne de requête ne sont pas dans un
événement ; le chemin d’une requête est filtré comme le filtre le
journal des requêtes. Seul ce que l’application met dans context: est
ajouté. Les messages d’exception sont envoyés tels quels, sauf si un filtre
les change : un message qui contient des données personnelles (le refus
d’un serveur SMTP qui nomme le destinataire) en demande un.
Filtres. Un filtre est une sous-classe de
Cybertrain::ErrorReporter::Filter qui définit filter_event(event), et
renvoie vrai pour garder l’événement, faux pour l’abandonner. Il peut
changer le message (event.error_message =) et le contexte
(event.set_error_context(key, value), event.delete_error_context(key)).
Celui-ci masque les adresses électroniques ASCII simples, sans guillemets, et l’autre abandonne une classe
que l’application ne veut pas signaler :
# config/app.rb
class MaskAddresses < Cybertrain::ErrorReporter::Filter
def filter_event(event)
event.error_message = event.error_message.gsub(/[\w.+-]+@[\w-]+(\.[\w-]+)+/, "[email]")
event.delete_error_context("email")
true
end
end
class DropDeclinedCards < Cybertrain::ErrorReporter::Filter
def filter_event(event)
event.error_class != "PaymentGateway::Declined"
end
end
Cybertrain.error.add_filter(MaskAddresses.new)
Cybertrain.error.add_filter(DropDeclinedCards.new)
Le motif de MaskAddresses laisse passer deux sortes d’adresses. Celles qui
ont des caractères hors ASCII, comme alice@例え.テスト : le \w de
Ruby ne correspond qu’aux lettres, chiffres ASCII et à _ sans propriété
Unicode demandée. Et celles dont la partie locale est entre guillemets, comme
"alice smith"@example.com : le motif veut une lettre, un chiffre, ., +, -
ou _ juste avant le @, n’en trouve pas après le guillemet fermant et ne
correspond à rien dedans, si bien que l’adresse entière reste dans le
message. Écrivez un motif pour les adresses
que vous attendez, ou abandonnez plutôt l’événement.
Les filtres tournent sur le thread du rapporteur, dans l’ordre d’ajout, avant
les abonnés et l’envoyeur ; le filtre suivant, les abonnés et Sentry
voient ce qu’un filtre a changé. Dès qu’un filtre abandonne l’événement, les
suivants ne tournent pas et personne ne le reçoit (il n’est pas compté parmi
les abandons de la file). Un filtre qui lève abandonne l’événement, car un
filtre existe pour empêcher quelque chose de sortir, et journalise
error filter failed: <Filter class>: <Class>: <message> au niveau
error ; il n’est jamais signalé. Le dédoublonnage est décidé avant les
filtres, sur la classe, le message et le where non filtrés : une
réécriture par un filtre ne change pas les rapports regroupés, et un
événement qu’un filtre abandonne garde sa place pour la minute. La ligne de
journal ERROR du framework est écrite avant que l’événement existe et
n’est pas filtrée. Un filtre seul ne met pas les rapports en file (il faut un
abonné ou un DSN). Les filtres ajoutés dans config/app.rb restent pour
chaque test ; un filtre ajouté dans un test est retiré avant le suivant.
Livraison. Les rapports vont dans une file de 100 et un thread les livre.
Une même classe, un même message et un même where (et, dans un job,
l’identifiant du job) sont mis en file au plus
une fois par minute, si bien qu’une page qui échoue pour chaque visiteur avec le
même message fait un rapport par minute (un message qui porte un
identifiant, Couldn't find Article with id=5, en fait un par message
distinct) ; quand la file est pleine, un rapport est
abandonné et compté, et error reports dropped: <n> est journalisé au niveau
warn au plus une fois par minute. Tant qu’il n’y a ni abonné ni DSN, rien
n’est mis en file et aucun thread ne démarre. Une livraison qui échoue est
journalisée, error delivery failed: <Class>: <message>, et le rapport
suivant démarre un nouveau thread si l’ancien s’est terminé. Quand le
serveur, un worker ou un processus feeds s’arrête, il attend jusqu’à 2
secondes les rapports en file après l’arrêt de ses services ; ce qui
reste est perdu. Une reconstruction en développement attend aussi, de même
qu’une commande enregistrée, ./<app> jobs et ./<app> console avant de
fermer la base et de se terminer.
Envoyer à Sentry ou GlitchTip. Avec la ligne dans bin/<app>.rb, définir
CYBERTRAIN_SENTRY_DSN (ou c.sentry_dsn) au DSN du projet envoie chaque
rapport comme un événement Sentry :
export CYBERTRAIN_SENTRY_DSN=https://PUBLIC_KEY@o1.ingest.sentry.io/42
export CYBERTRAIN_RELEASE=2026.11.14-3f2a9c1 # facultatif : envoyé comme release de l'événement
export CYBERTRAIN_ERROR_SAMPLE_RATE=0.25 # facultatif : en envoyer un quart
- Le DSN s’écrit
http[s]://<public key>[:<secret>]@<host>[:<port>][/<path>]/<project id>(le secret, l’ancienne seconde moitié de Sentry, est ignoré) ; les événements vont à<scheme>://<host>[:<port>][/<path>]/api/<project id>/envelope/, que Sentry et GlitchTip acceptent tous deux. Il contient une clé : gardez-le dans les secrets du déploiement, pas dans un fichier versionné. Un DSN illisible arrête le démarrage, en nommant la partie et jamais la clé :error: sentry_dsn must look like https://<public key>@<host>/<project id>: the project id must be digits. - Un DSN défini dans un programme qui ne lie pas l’envoyeur arrête le
démarrage, et fait refuser une commande enregistrée,
jobsetconsoleavant qu’ils n’ouvrent la base (statut de sortie 1) :error: CYBERTRAIN_SENTRY_DSN is set, but this program does not link the Sentry sender: add require "cybertrain/error_reporter/sentry" to bin/<app>.rb. Une classe d’envoyeur à vous (une sous-classe deCybertrain::ErrorReporter::Sender) définitsender_namepour renvoyer un nom non vide, ou elle se heurte au même refus. CYBERTRAIN_ERROR_SAMPLE_RATE(c.error_sample_rate, 1.0) est la part des rapports envoyés, de 0.0 à 1.0 ; les abonnés voient toujours chaque rapport. La variable doit être des chiffres avec un.chiffresfacultatif, sinon le démarrage s’arrête :error: error_sample_rate must be a number from 0.0 to 1.0 (got "x").CYBERTRAIN_RELEASE(c.release, vide par défaut) nomme la version ou le commit ; il n’est pas vérifié.- Chaque envoi attend au plus 5 secondes une fois le nom de l’hôte résolu (la
résolution bloque le thread de livraison et l’échéance ne peut pas
l’interrompre, si bien qu’un résolveur bloqué peut retenir un envoi plus
longtemps), et n’est jamais retenté. Un refus est
journalisé au niveau warn,
error report not sent: Sentry answered 429, de même qu’un échec de connexion,error report not sent: <Class>: <message>. - L’événement porte la classe et le message,
wherecomme transaction, l’environnement, la release, l’identifiant de requête comme étiquette, la méthode et le chemin de la requête, le contexte commeextra, et la pile d’appels comme frames quand il y en a une. - L’appel passe par
Cybertrain::HttpClientet sa garde contre les adresses privées (HTTP sortant) : un GlitchTip sur un réseau privé ou sur la même machine demandeCYBERTRAIN_HTTP_ALLOW_PRIVATE=1, qui lève la garde pour chaque appel sortant de l’application.
Piles d’appels. Un binaire de cybertrain build est une version release
de Spinel, dont les exceptions n’ont pas de pile d’appels : ses rapports
ont la classe, le message et where. Dans une version --debug, et sous
CRuby, les frames sont jointes.
cybertrain test n’envoie rien à Sentry : il vide un
CYBERTRAIN_SENTRY_DSN exporté sauf si config/app.rb en affecte un, et un
test pointe plutôt le DSN vers un Test::SentryReceiver
(Tester les journaux et les rapports d’erreur).
La conception : docs/design.md D86 et D88.
Mettre à jour les journaux et les rapports d’erreur depuis 0.4
- Chaque ligne de journal change de forme : le niveau entre crochets au
début (
[INFO]) cède la place à l’heure, au niveau et aux étiquettes,2026-11-14T09:30:00.132Z INFO [<request id>] Completed 200 in 3ms. Ce qui lit le journal (un grep de[ERROR]dans un script, une alerte) change avec elle ; un test qui cherchait une ligne entière cherche le niveau et le message séparément (" ERROR "et le message ; Mettre à jour depuis 0.4). - Chaque réponse de l’application porte
X-Request-Id(pas les 400 et 413 du serveur pour une requête qu’il ne peut pas lire). Un proxy qui en posait un voit le sien utilisé seulement s’il est de confiance. cybertrain_jobsgagne la colonnerequest_id; le premier processus qui touche la table l’ajoute.- Une ligne de journal en texte ne continue plus sur les lignes
suivantes : un saut de ligne ou un retour chariot dans un message ou
une étiquette s’écrit
\nou\r. Ce qui lisait un message sur plusieurs lignes lit les échappements. - Une colonne de modèle nommée
handlese lit maintenanthandle_column: une application qui a une colonneusers.handlechange ses appelsuser.handleenuser.handle_column(les requêtes gardent le nom SQL). Les colonnesrequest_idoureleasequi ne sont pas du texte sont refusées par gen (Noms de colonnes). cybertrain testignore unCYBERTRAIN_LOG_FORMATet unCYBERTRAIN_SENTRY_DSNexportés (les tests lisent des lignes de texte et n’envoient rien) sauf siconfig/app.rbles fixe. Les tests de mot de passe qu’écritgenerate authenticationcoupent les lignes JSON dans leurwith_config; une application générée plus tôt dont les tests tournent aveclog_format :jsonrelance le générateur ou recopie ce changement.require "cybertrain"lie maintenantHttpClientet la couche TLS, à travers l’envoyeur Sentry.