Фоновая работа
Приложение, которому нужно сделать что-то вне запроса (отправить уведомление
после того, как ответ ушёл, каждую ночь вычищать старые строки, повторить
неудавшийся вызов), поручает это фреймворку, а тот выполняет работу в фоновых
потоках обслуживающего процесса или отдельного процесса-обработчика. Задача —
это класс в app/jobs/, как в Rails. Задачам и задачам по расписанию нужна
строка require "cybertrain/jobs" в bin/<app>.rb и bin/db.rb; её
добавляет cybertrain generate job (Подсистемы):
# 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
# в действии, после сохранения пользователя
WelcomeJob.perform_later("user_id" => @user.id)
WelcomeJob.perform_in(600, "user_id" => @user.id) # или perform_at(time, args)
# config/app.rb (или файл, который bin/<app>.rb подключает до Cybertrain::Main.run)
Cybertrain::Scheduler.cron("0 4 * * *", "nightly digest", job: "DigestJob")
Cybertrain::Scheduler.every(300, "refresh rates") { Rates.refresh }
- Где это выполняется. Задачи выполняются в
job_threadsпотоках задач (3,CYBERTRAIN_JOB_THREADS); задачи по расписанию — в собственном потоке планировщика, так что долгая задача никогда не задерживает задачу по расписанию. И те, и другие запускаются, когда бинарный файл обслуживает запросы (./<app>,./<app> server) или работает как обработчик (./<app> worker, см. Роли процессов), после того как при запуске подключена база данных и заданSPINEL_WORKERS; командыmigrate,db ...,jobs ...,consoleиMain.commandникогда их не запускают, как иCybertrain::Test::Client. Если задачи подключены, их потоки запускаются в каждом таком процессе, даже в приложении без единого класса задачи: фреймворк регистрирует собственную задачу отправки почты (Mailer.deliver_later, Отправка электронной почты). - Таблица. Задачи — это строки
cybertrain_jobs, таблицы, которую фреймворк создаёт сам (CREATE TABLE IF NOT EXISTS, при первом использовании) и не включает вdb/schema.rb. ВнутриDB.transactionстрока фиксируется или откатывается вместе с остальным. Каждый поток задач забирает самую старую наступившую строку в короткой транзакцииBEGIN IMMEDIATE, выполняет её вне транзакции и ищет следующую; когда ничего не наступило, он ждётjob_poll_intervalсекунд (1), так что задача, поставленная запросом, начинается примерно через секунду. Строка находится в состоянииqueued,running,done,failed(повторы исчерпаны; она остаётся, чтобы вы её изучили) илиdiscarded(её остановилdiscard_on).
Классы задач
spin run gen читает каждый файл в app/jobs/ (и во вложенных каталогах:
Admin::ReportJob в app/jobs/admin/report_job.rb) и записывает в
gen/jobs.rb вторую половину каждого класса, среди предков которого есть
Cybertrain::Job::Base: perform_later, perform_at, perform_in,
perform_now, job_kind и код, который её выполняет, — и регистрирует
класс. cybertrain generate job send_digest --retry
Cybertrain::Mailer::TimeoutError:60:5 пишет файл класса и тест к нему.
args— это Hash, переданный вperform_later, сохранённый как JSON и прочитанный обратно какHash<String, Object>: сужайте его значения черезCybertrain::Cast.int(args["user_id"]),Cast.str,Cast.hash,Cast.array. Задача принимает только этот один Hash; передавайте id, а не записи (так советует и Rails).perform_laterвозбуждаетArgumentErrorдля всего, что не Hash, а без аргумента отправляет{}.- Постановка в очередь.
perform_later(args),perform_at(time, args)иperform_in(seconds, args)возвращают id строки; вид строки — имя класса ("WelcomeJob","Admin::ReportJob").perform_now(args)выполняетperformв вызывающем потоке, без очереди, без политики повторов и без rescue, и возвращаетnil: как раз то, что нужно тесту. - Тело класса. Каждый класс задачи определяет
perform(args)(генератор отвергает класс, который его не определяет и не наследует).retry_on,discard_onиlimits_concurrencyчитаются как текст, по одному на строку, с литеральными значениями (Integer или:polynomially_longerдляwait:, Integer дляattempts:иto:, String в кавычках дляkey:); блок, лямбда,5.minutes, запись через=>или комментарий в конце строки останавливаютspin run genс указанием файла, строки и того, что написать вместо этого. -
Какие классы исключений.
retry_onилиdiscard_onназывает класс, который программа определяет до задачи: класс ядра (ArgumentError,KeyError, ...), любой класс исключения фреймворка, как бы он ни назывался (Cybertrain::RecordNotFound,Cybertrain::RecordInvalid,Cybertrain::DB::Error, ...; список —Gen::JobScan::FRAMEWORK_ERRORS, и генератор добавляет require, нужный классу вне ядра), или класс приложения, определённый вapp/models/, вapp/jobs/application_job.rbили выше строки в файле самой задачи. Всё остальное, включая классы тестовой обвязки, останавливаетspin run gen, напримерPATH:LINE: Cybertrain::Test::AssertionFailed is not a class this program defines (spikes/NOTES.md rule 89): под Spinelrescue, называющий класс, которого программа не определяет, может проглотить любое исключение.NotifyCommentJobиз examples/blog отбрасывает задачу, чей комментарий удалён, и повторяет всё остальное: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 endВетви пробуются в порядке записи, и побеждает первая подходящая, поэтому более узкий класс пишется первым; Rails проверяет сначала обработчик, объявленный последним, так что в приложении Rails эти две строки идут в обратном порядке. Отбрасывание пишется в лог как
job 12 (NotifyCommentJob) discarded: Cybertrain::RecordNotFound: Couldn't find Comment with id=7. ApplicationJob. КлассApplicationJob < Cybertrain::Job::Baseвapp/jobs/application_job.rbсам задачей не является: его строкиretry_onиdiscard_onприменяются к каждой унаследованной от него задаче после её собственных, а егоlimits_concurrency— к задаче, которая своего не объявляет. Любой другой класс задачи может быть родителем; тогда он сам по себе тоже задача.-
Job.handle, короткая форма. Блоку, зарегистрированному под видом-String, не нужны ни класс, ни генератор; он получает полезную нагрузку String и политику по умолчанию, описанную ниже:ruby # config/app.rb Cybertrain::Job.handle("notify", concurrency: 1) { |payload| Notifier.post(payload) } # где угодно, позже Cybertrain::Job.enqueue("notify", JSON.generate({ "text" => "Deployed" }), run_at: Time.now + 60)Классы задач и виды
Job.handleделят одно пространство имён, так чтоJob.enqueue("WelcomeJob", json)добавляет ту же строку, что иperform_later.Job.enqueueотвергает незарегистрированный вид.
Повторы и отбрасывание
- Политика по умолчанию. Исключение, которому не соответствует ни одна
строка класса (и любое исключение блока
Job.handle), повторяется через 1, 5, 15, а затем через 60 минут, сClass: message(до 1000 символов) вlast_error, пока не будут исчерпаныjob_max_attempts(5) попыток; тогда строка становитсяfailed.NotImplementedError(ещё не написанный хелпер),SystemStackErrorили другойScriptErrorиз кода задачи следуют этой же политике, хотя ни один из них неStandardError; любое другое исключение внеStandardErrorпишется в лог (ERROR Job thread N: ...) и попадает в отчёт об ошибках, поток задач продолжает работу, а строка остаётсяrunning, пока её не заберёт восстановление (ниже). retry_on Klass, wait: 60, attempts: 5.wait:— это секунды (3, если не указано, — умолчание Rails) или:polynomially_longer(attempts ** 4 + 2секунды: 3, 18, 83, 258, ...);attempts:(5, если не указано) считает каждую попытку, включая первую. Строк может быть несколько: побеждает первая, чей класс соответствует исключению (подкласс тоже соответствует), поэтому пишите более узкий класс первым.retry_on StandardErrorпередdiscard_on ArgumentErrorповторяетArgumentError.discard_on Klassостанавливает сразу: строка становитсяdiscarded, с ошибкой вlast_error, и никогда не повторяется. Лог пишетERROR [<Kind> <id>] [<request id>] job <id> (<Kind>) discarded: <Class>: <message>(с идентификатором запроса, если задачу поставил запрос), а об отбрасывании сообщается один раз, сjob.max_attempts, равнымjob.attempt.def retries_exhausted(error)выполняется, когда попытки строкиretry_onисчерпаны, после того как строка действительно сталаfailed(никогда — для попытки, которую забрал другой обработчик: её выполнение ещё может удаться). Это блокretry_on ... do |job, error|из Rails; возбуждённое в нём исключение пишется в лог.- Восстановление (ниже) тоже следует классу: строка класса с
attempts: 20, чей процесс умер на 5-й попытке, снова ставится в очередь, а не помечается неудачной.
Параллелизм по виду и по ключу
limits_concurrency to: 1, key: "account_id" позволяет одновременно
выполнять не больше to: задач этого класса во всех процессах, разделяющих
базу данных, считая отдельно для каждого значения args["account_id"]
(to: без ключа считает для всего класса; для блока то же делает
Job.handle(kind, concurrency: n)). Другие виды и другие ключи тем временем
продолжают выполняться. Постановка в очередь задачи с ключом, у которой в
args нет этого ключа, возбуждает ArgumentError. Ограничение считает
строки running, поэтому держится, пока держатся сердцебиения: задача, всё
ещё выполняющаяся после того, как её сердцебиение устарело, пересекается
со следующим выполнением восстановленной строки (см. ниже); работе, которая
никогда не должна пересекаться, нужна собственная защита.
Задачи по расписанию
Scheduler.every(seconds, name) { ... } выполняет блок каждые seconds;
Scheduler.cron(expr, name, ...) — в минуты, которым соответствует
пятипольное выражение cron:
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 }
- Выражение. Минута, час, день месяца, месяц, день недели, с
*,*/n,a-b,a,b,a-b/nи именамиjan–decиsun–sat(дни недели0и7— воскресенье);@hourlyи подобные не принимаются. Выражение, которое не разбирается или никогда не совпадает, возбуждаетArgumentErrorс именем задачи при загрузкеconfig/app.rb, так что запуск останавливается. - Часовые пояса.
tz:называет пояс IANA (Часовые пояса); без него задача читается вscheduler_tz(CYBERTRAIN_SCHEDULER_TZ, который, если не задан, следуетtime_zoneприложения). Время на часах, которое перепрыгивает переход на летнее время, в этот день не выполняется. В повторяющемся часе осеннего перехода выражение, чьё поле часов начинается с*, выполняется в обоих вхождениях, а выражение с фиксированным часом — один раз, как в Vixie cron. job:называет вид задачи (имя класса строкой или видJob.handle), аargs:— её аргументы: тогда задача по расписанию только ставит её в очередь, что и должна делать задача с настоящей работой. Неизвестный вид останавливает запуск со списком зарегистрированных.- Расписание хранится в базе данных (
cybertrain_schedules, не входит вdb/schema.rb): когда каждая задача выполнялась в последний раз и когда выполнится в следующий. Перезапуск или другой процесс, ставший ведущим, продолжают с него. Задачаevery, чьё время прошло, пока ничего не работало, выполняется один раз при запуске; слотcron, пропущенный, пока ничего не работало, пропускается (правило cron), если только задача не указываетcatch_up: true— тогда он выполняется один раз при запуске. Слот, наступивший, пока процессы работали, но ни один ведущий его не выполнил (аренда переходила из рук в руки), выполняется один раз при перехвате. Задача, которую вы переименовали или удалили, сохраняет свою строку до следующего запуска. Задача, которая ещё ни разу не выполнялась, следует своему текущему расписанию, когда оно наступает раньше, чем следующий запуск, сохранённый прежним релизом (еженедельная задача, ставшая ежечасной до первого запуска, выполнится в течение часа). - Как выполняется задача по расписанию. Блок выполняется в потоке
планировщика, по одной задаче за раз; каждое выполнение обёрнуто в rescue,
который пишет в лог
ERROR [schedule:name] Scheduled task "name" failed: ...и сообщает об ошибке, и цикл продолжается. Блок не принимает аргументов (в Spinel нетinstance_eval). Вызов SQLite держит свой рабочий поток ОС, пока не вернётся: приSPINEL_WORKERS=1(по умолчанию) долгий запрос к базе останавливает все запросы и все остальные потоки на всё это время. Отдавайте задаче по расписанию с настоящей работой задачу из очереди (job:илиJob.enqueueиз блока) и дробите большую работу (тысяча строк за выполнение, одна задача на элемент).Cybertrain::Scheduler.last_tick— секунда эпохи последнего такта, для вашей собственной проверки работоспособности.
Страница задач и команда jobs
# config/routes.rb
Cybertrain::Routes.draw do
jobs_page "/admin/jobs", before_action: :require_admin, skip_before_action: :require_authentication
end
jobs_page монтирует страницу, на которой видны число строк в каждом
состоянии, число строк в очереди и ближайший срок, строки failed и
discarded (вид, аргументы, ошибка, попытки, время) и строки running (кто
их забрал, насколько старо их сердцебиение), по jobs_page_per_page (50,
CYBERTRAIN_JOBS_PAGE_PER_PAGE) строк в списке. Неудавшуюся строку можно
повторить (сразу снова в очередь, попытки обнулены), отбросить или удалить,
отброшенную — повторить или удалить, а все неудавшиеся строки — повторить или
отбросить разом; каждое действие трогает только строки failed и
discarded, так что строка, которую обработчик только что забрал, остаётся
нетронутой.
- Сгенерированный контроллер наследует
ApplicationController, так что действуют макет, хелперы и защита CSRF приложения, аbefore_action:называет один из его методов: чтобы отказать, метод должен отрисовать ответ или перенаправить.cybertrain generate authenticationрисует строку выше сrequire_adminсвоего concern (404, если не вошёл администратор; Администраторы). Безbefore_action:страница открыта любому посетителю, иspin run genпечатает об этом предупреждение. skip_before_action:называет один унаследованный before-колбэк, который страница не выполняет. С:require_authenticationпосетителю отвечает толькоrequire_admin— 404 вместо перенаправления на вход. gen отвергает его безbefore_action:и когда он называет самbefore_action:.- Её кнопки — формы с токеном CSRF. Не включайте путь страницы в
csrf_exempt_prefixes: под исключённым префиксом эти формы принимались бы с любого сайта.
Из оболочки ./<app> jobs делает то же самое на настроенной базе данных (он
не запускает потоков):
./blog jobs list # неудавшиеся строки, новые первыми (1000 новейших); или: list queued|running|done|discarded
./blog jobs retry 42 # или: retry --all (все неудавшиеся строки)
./blog jobs discard 42
./blog jobs delete 42
./blog jobs prune --before 30 # удаляет строки failed и discarded старше 30 дней (по умолчанию 7)
Строки done остаются, пока их что-нибудь не удалит: Job.prune_done(before_epoch)
из задачи по расписанию (Cybertrain::Scheduler.cron("0 3 * * *", "prune
done jobs") { Cybertrain::Job.prune_done(Time.now.to_i - 7 * 86_400) }).
Job.state_count("failed") пригодится для собственной страницы состояния.
Несколько обработчиков, хотя бы один раз, остановка
- Несколько обработчиков на базу. Каждый процесс, выполняющий задачи,
каждые
job_heartbeat_interval(30 с) пишет сердцебиение для задач, которые выполняет. Строкуrunning, чьё сердцебиение старшеjob_heartbeat_stale(процесс упал или был остановлен посреди задачи), снова ставит в очередь тот процесс, который посмотрит следующим, — при своём запуске, а затем раз в минуту, — если только эта попытка не была последней (большее изjob_max_attemptsи наибольшегоattempts:класса): тогда строка остаётсяfailed, сprocess stopped (heartbeat stale)вlast_error, чтобы задача, убивающая свой процесс, не повторялась вечно. Задачи по расписанию выполняются одновременно только в одном процессе: процессы делят аренду в базе данных (cybertrain_leases, продлевается на каждом такте,scheduler_lease_ttl30 с), и только её держатель выполняет наступившие задачи; другой перехватывает её, когда держатель перестаёт продлевать. Аренда продлевается перед каждой задачей, а не во время её выполнения, так что задача длиннее ttl может пересечься с задачей следующего держателя: делайте задачи по расписанию короткими и безопасными для повтора. Поэтому два процессаworkerили сервер и обработчик могут делить один файл SQLite;CYBERTRAIN_WORKER=0отключает задачи, задачи по расписанию и фиды в процессеserver, который должен только обслуживать HTTP. - Хотя бы один раз. Задача может выполниться дважды: процесс, который
убили или который завис дольше
job_heartbeat_stale(300 с), может всё ещё выполнять задачу, когда другой процесс забирает строку обратно. Учитывается только результат той заявки, которая держит строку (запоздавший результат прежней заявки отбрасывается), но побочные эффекты задачи случились дважды, поэтому пишите задачи, которые безопасно выполнить повторно (проверьте, не ушло ли уже письмо, делайте upsert, а не insert), как с любой очередью задач. Задача по расписанию может по той же причине выполниться дважды при смене ведущего. - Остановка. По
SIGTERMпотоки задач перестают забирать новые задачи, а процесс ждёт выполняющиеся задачи доjob_drain_timeout(10 с). Задача, которая к этому времени ещё выполняется, оставляет свою строкуrunning; её сердцебиение остановилось, так что другой процесс выполнит её снова, когда оно устареет. - Тесты.
WelcomeJob.perform_now(args)выполняет задачу,Cybertrain::Scheduler.run_due(now)— один такт, аCybertrain::Job.work_one(now)— одну задачу из очереди, с выбранным вами временем эпохи, так что тест никогда не спит; Тестирование задач описывает утверждения.
Обновление с 0.4
cybertrain_jobsполучает столбецconcurrency_keyи состояниеdiscarded; столбец добавляет первый процесс, который касается таблицы. Код, перечисляющий состояния (панель на основеJob.state_count), добавляетdiscarded.Job.prune_doneпо-прежнему удаляет только строкиdone.- Задачи
everyпосле перезапуска продолжают по расписанию из базы, а не начинают заново: интервал, прошедший, пока процесс не работал, выполняется один раз при запуске. - Если существующему виду даётся ключ (
limits_concurrency ... key:): остановите все старые процессы до запуска первого нового, как при любом обновлении (Роли процессов). Первый новый процесс проставляет ключ строкамqueued, поставленным в очередь раньше (он пишет в лог id строк, в полезной нагрузке которых нет этого поля), а строкаrunning, оставленная старым процессом, получает ключ при восстановлении. jobsтеперь встроенная команда: команду приложения с именемjobsнужно переименовать.
Не построено: приоритет задач, имена очередей и уникальность, встроенный
режим выполнения задач для тестов (тесты покрываются perform_now и
perform_enqueued_jobs). Проектное решение: docs/design.md D28 и D51–D53.
Роли процессов
Один бинарный файл работает в трёх ролях. По умолчанию ./<app> server
делает всё, как rails server с Solid Queue внутри Puma; две другие роли
позволяют развёртыванию разделить работу между процессами или
контейнерами — все из одного образа и с одной базой:
| Команда | Выполняет | Слушает порт |
|---|---|---|
./<app> server [PORT] |
HTTP, точку входа потоков, а если не задан CYBERTRAIN_WORKER=0, то задачи по расписанию, потоки задач и фиды WebSocket |
да |
./<app> worker |
задачи по расписанию (в одном процессе за раз, благодаря аренде), потоки задач, пульс и восстановление | нет |
./<app> feeds [NAME...] |
фиды WebSocket, все или названные | нет |
workerиfeedsпечатают баннер (=> worker: 3 job threads, 2 scheduled tasks), работают доSIGTERMилиSIGINT(Ctrl-C), а затем останавливаются так же, как сервер. Свою работу они выполняют всегда:CYBERTRAIN_WORKER=0, заданный для веб-роли, их не выключает.feedsс именами запускает только эти подписки (по контейнеру на фид), а неизвестное имя останавливает запуск со списком зарегистрированных. Если фиды работают в своём процессе, задайте серверамCYBERTRAIN_WORKER=0, иначе каждый процесс получал бы каждый фид.- Процесс
feedsперезапускает фид, чей поток умер, и завершается со статусом 1, когда один и тот же фид продолжает умирать (feed_restart_limitперезапусков заfeed_restart_window), поэтому запускайте его под политикой перезапуска (restart: unless-stoppedв Docker,Restart=alwaysв systemd); подробности — в Потреблении потоков WebSocket../<app> feeds statusпечатает последнее сообщённое состояние каждого фида. - Типичное разделение:
serverсCYBERTRAIN_WORKER=0за прокси, один или несколькоworkerиfeeds, если есть подписки.cybertrain newпишет вconfig/deploy.ymlролиwebиworker(и закомментированнуюfeeds); юниты systemd — в docs/deploy.en.md, часть 7, «Splitting the roles». - Обновление с версии без пульса: остановите все старые процессы, прежде чем запускать первый новый. Новый обработчик принял бы задачи, которые старый ещё выполняет, за брошенные: старый процесс не пишет пульс.
Cybertrain::Main.worker?(ARGV)иMain.feeds?(ARGV), как иMain.server?(ARGV), сообщаютbin/<app>.rb, какую роль он запускает.workerтребуетrequire "cybertrain/jobs"вbin/<app>.rb, аfeeds—require "cybertrain/feeds"(её загружаетcybertrain/websocket); без неё бинарник называет недостающую строку и завершается с кодом 1.
Хранилище кэша
Cybertrain::Cache хранит ответы какое-то время в собственной базе данных
приложения, чтобы следующий запрос не спрашивал медленный API снова.
require "cybertrain" его загружает; приложение на cybertrain/core
добавляет require "cybertrain/cache" в bin/<app>.rb и bin/db.rb или
туда, где он используется:
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, если записано
- Значения — это String.
fetch(key, expires_in:, race_condition_ttl:) { String }возвращает живое значение или выполняет блок и сохраняет то, что он вернул;fetch_hash,fetch_arrayиfetch_intхранят текст JSON или Integer и разбирают его на выходе, так что испорченная ячейка читается как{},[]или0, пока не истечёт и блок не выполнится снова (в Spinel нетMarshal, а один метод возвращает один тип). Остальное —read(key)(String или nil),write(key, value, expires_in:, unless_exist:),delete,exist?,increment(key, by: 1, expires_in:)(одна инструкция; истёкший счётчик начинается заново сby, аexpires_in:задаёт срок только при запуске счётчика, так что счётчик на минуту считает именно эту минуту) иclear. - Срок жизни.
expires_in:задаётся в секундах;0, значение по умолчанию, никогда не истекает (отрицательное значение тоже).race_condition_ttl: n: когда строка истекла, первый вызывающий продлевает её наnсекунд и вычисляет новое значение, а остальные тем временем продолжают читать старое, как в Rails; без этого каждый, кто обращается к истёкшему ключу, вычисляет сам. Блок, возбудивший исключение, ничего не записывает. - Хранение. Строки лежат в
cybertrain_cache, которую фреймворк создаёт при первом использовании и не включает вdb/schema.rb. В памяти ничего не хранится: каждое чтение — это SELECT, на который SQLite отвечает из своего кэша страниц. Каждая запись берёт блокировку записи базы данных, которую ждут запросы, пишущие свои строки: кэшируйте то, что производят задачи, или значения, которые читаются гораздо чаще, чем меняются, а не пишите в нагруженном пути запроса. - Очистка. Если задачи загружены, подключение файла регистрирует задачу
по расписанию
"cybertrain cache prune", которая удаляет истёкшие строки каждыеcache_prune_intervalсекунд (300,CYBERTRAIN_CACHE_PRUNE_INTERVAL), по тысяче за инструкцию. Без задач кэш чистит себя сам: первая запись процесса и первая запись после каждогоcache_prune_intervalудаляют до тысячи истёкших строк. Интервал читается при подключении файла: задайте переменную илиc.cache_prune_intervalв блокеCybertrain.configure, который выполняется до require.Cache.prune(now)— точка входа для тестов.
Не построено: отдельный файл базы данных для кэша, ограничение размера,
хранилище в памяти. Проектное решение: docs/design.md D54.
Консоль
./<app> console — это приглашение для работы с моделями приложения. В
Spinel нет eval, поэтому Ruby она не выполняет: она вычисляет те
выражения, которые вычисляет <%= %> шаблона (язык
шаблонов, без блоков), плюс имена
моделей. В разработке запускайте её через
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
- Имя модели — это её relation (
Article) с методамиwhere,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_sqlиcreate. У записи есть её атрибуты и методы,update,save,destroy,reload,valid?,errorsиattributes.helpперечисляет их все. x = exprсохраняет значение для следующих строк, а_— последнее значение.sql "..."выполняет SQL и печатает строки таблицей, экранируя управляющие символы в ячейках (\e,\n), так что данные не могут ни послать терминалу escape-последовательность, ни сломать таблицу (значение TEXT с байтом NUL обрезается на NUL при чтении, как при любом чтении сырым SQL; BLOB сохраняет все байты);tablesперечисляет таблицы;exit,quitили Ctrl-D — выход.- Строка, которая не разбирается, печатает свою ошибку, строка, возбудившая
исключение, печатает
Class: message, и приглашение возвращается. Двоичное значение печатается как<N bytes>. - Записи настоящие. В продакшене консоль сначала предупреждает об этом баннером.
./<app> dbconsole открывает оболочку sqlite3 для настроенной базы
(CYBERTRAIN_DATABASE), как dbconsole в Rails; нужна установленная
команда sqlite3, её код выхода передаётся дальше. Ни одна из этих команд
не запускает планировщик, задачи или фиды.
Эксплуатация: резервные копии, VACUUM, проверка работоспособности
Данные развёрнутого приложения — это один файл SQLite, поэтому бинарный файл
содержит три инструмента эксплуатации, нужные такому приложению. Приложение с
загрузкой файлов также хранит их байты в своём корне загрузок (upload_root,
по умолчанию storage/uploads/): создавайте резервную копию этого каталога и
восстанавливайте его вместе с базой данных, иначе восстановленные записи будут
указывать на отсутствующие файлы (Добавление загрузки файла).
Резервные копии. ./<app> db backup PATH записывает согласованную копию
настроенной базы данных (CYBERTRAIN_DATABASE), пока сервер продолжает работать:
VACUUM INTO SQLite (3.27 или новее; бинарный файл это проверяет) читает один
снимок, а при WAL записи сервера тем временем продолжаются. Копия пишется во
временный файл рядом с PATH, создаваемый эксклюзивно с режимом 0600 (в файле
хранятся дайджесты паролей и токены сессий), сбрасывается на диск через fsync и
только затем переименовывается в PATH, поэтому неудачное или прерванное
копирование никогда не оставляет неполный файл под настоящим именем (временный
удаляется). Существующий PATH отвергается, если не передан --force; сама база
данных никогда не бывает целью, а база данных :memory: — источником.
./blog db backup /srv/blog/backups/before-upgrade.sqlite3
./blog db backup /srv/blog/backups/ --keep 14 # blog-20261025T031500Z.sqlite3, хранятся 14 самых новых
Цель, оканчивающаяся на / (или существующий каталог), получает имя с датой,
<app>-<YYYYmmddTHHMMSSZ>.sqlite3 в UTC, в каталоге, который создаётся с
режимом 0700, если его нет; затем --keep N удаляет самые старые файлы ровно
такого вида сверх N и больше ничего там не трогает. Восстановление — это
копирование резервной копии поверх файла базы данных при остановленном сервере
(и удаление лежащих рядом -wal и -shm этого файла).
VACUUM. Удаление строк оставляет в файле свободные страницы. ./<app> db vacuum
выполняет VACUUM, а затем PRAGMA wal_checkpoint(TRUNCATE), поэтому
перестроенные страницы попадают в файл базы данных, файл обрезается до нового
размера, а WAL опустошается; команда выводит размер на диске (база данных плюс
WAL) до и после. VACUUM переписывает весь файл и всё это время держит
блокировку записи, поэтому запускайте его, когда приложение не нагружено. Если
читатель не даёт контрольной точке завершиться, команда об этом сообщает, и WAL
уменьшится на одной из следующих контрольных точек.
Делайте резервные копии вне сервера. Вызов SQLite удерживает свой рабочий
поток ОС до возврата, поэтому большой VACUUM INTO в задаче Scheduler
задерживал бы запросы (при SPINEL_WORKERS=1 — все) на всё время копирования.
Вместо этого запускайте команду из cron или таймера systemd отдельным процессом:
# crontab пользователя приложения: каждую ночь в 03:15, хранить две недели
15 3 * * * cd /srv/blog/current && ./blog db backup /srv/blog/backups/ --keep 14
Приложение, которое хочет само делать резервные копии, может из задачи по
расписанию запустить собственный бинарный файл дочерним процессом, вместо того
чтобы выполнять SQL в своём потоке: system ждёт дочерний процесс только в
потоке планировщика, а запросы тем временем продолжают обслуживаться
(используйте system со списком аргументов, никогда — со строкой, содержащей
данные запроса). Копирование, которое длится дольше health_worker_stale,
заставляет проверку работоспособности отвечать worker stale, пока оно не
закончится.
# config/app.rb, в обслуживающем бинарном файле, запущенном из своего каталога (dist/)
Cybertrain::Scheduler.every(86_400, "nightly backup") do
system("./blog", "db", "backup", "storage/backups/", "--keep", "14")
end
Проверка работоспособности. Пока проверка работоспособности включена (по
умолчанию она включена; пустой config.health_path её отключает),
обслуживающее приложение отвечает на GET /up (и HEAD) до статических
файлов, сессии, CSRF и маршрутизатора: контроллер не участвует, никакой
before_action входа не может сделать редирект, и cookie не устанавливается.
Она выполняет SELECT count(*) FROM sqlite_master, которому приходится
прочитать страницу схемы из файла (голый SELECT 1 его никогда не трогает), и
отвечает в text/plain с Cache-Control: no-store:
| Статус | Тело | Когда |
|---|---|---|
| 200 | ok |
запрос выполнен успешно |
| 503 | database unavailable |
он возбудил Cybertrain::DB::Error (файл отсутствует или не читается, пул закрыт) |
| 503 | worker stale |
фоновый Scheduler работает, и его последний такт старше health_worker_stale секунд (300): задача зависла или выполняется слишком долго |
| 503 | feed stale |
фид WebSocket в этом или другом процессе не сообщал своё состояние или ничего не получал (даже pong) в течение health_feed_stale секунд (180); см. Состояние фидов |
Опрос пишется в лог, как любой запрос (две строки). Путь —
config.health_path (CYBERTRAIN_HEALTH_PATH, по умолчанию /up; пустое
значение отключает проверку, и тогда путь, как и раньше, уходит в public/ и
маршрутизатор). Её может опрашивать балансировщик нагрузки, kamal-proxy или
скрипт развёртывания; public/up.html, который пишет cybertrain new и
который по-прежнему опрашивает его конфигурация Kamal, показывает лишь то, что
процесс отвечает по HTTP.
Журнал
Фреймворк и приложение пишут в лог через Cybertrain.logger: одна строка на
сообщение в стандартный вывод, со сбросом после каждой строки, как в
приложении по двенадцати факторам (её собирают журнал systemd, Kamal и
Docker):
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
Строка — это время в UTC с миллисекундами (в тесте оно следует за
travel_to), уровень заглавными буквами, теги в квадратных скобках и
сообщение. У Cybertrain.logger есть debug, info, warn, error и
fatal, каждый принимает одну String. Строки нескольких потоков никогда не
перемешиваются: каждая строка собирается целиком и пишется одним write под
блокировкой, которая держится только на эту запись. Запись, которая не
удалась (закрытый канал), отбрасывает строку; запись в лог никогда не бросает
исключение в вызывающий код. Читатель, который перестал читать стандартный
вывод (переполненный канал), блокирует все пишущие в лог потоки, пока не
начнёт читать снова, поэтому держите сборщик логов запущенным.
Одно событие — одна строка. Перевод строки в сообщении или в теге
пишется двумя символами \n, возврат каретки — \r, так что многострочное
или поддельное сообщение не может начать свою строку:
Cybertrain.logger.info("ok\n2026-11-11T12:00:00.000Z ERROR fake") пишет
одну строку:
2026-11-14T09:30:00.120Z INFO ok\n2026-11-11T12:00:00.000Z ERROR fake
Единственный перевод строки в самом конце сообщения — это конец самой
строки, и он не экранируется (info("done\n") пишет done); второй
экранируется. Больше ничего не экранируется: обратная косая черта остаётся
собой, а табуляции, другие управляющие байты и некорректный UTF-8 пишутся
как есть. Строки JSON экранируются как прежде.
Уровень. c.log_level в config/app.rb или CYBERTRAIN_LOG_LEVEL
(debug, info, warn, error, fatal или none, в любом регистре) —
наименее важный записываемый уровень; по умолчанию :info. :none также
выключает журнал запросов, но строки ошибок пишет. Присваивание в
config/app.rb важнее переменной. Любое другое значение останавливает
загрузку:
error: log_level must be :debug, :info, :warn, :error, :fatal or :none (got :verbose).
Строки JSON. c.log_format = :json (или CYBERTRAIN_LOG_FORMAT=json)
вместо этого пишет по одному объекту JSON на строку, для сборщика логов:
{"time":"2026-11-14T09:30:00.132Z","level":"INFO","request_id":"3f2a9c1e-6c1d-4f0b-9a52-0d1e2f3a4b5c","tags":[],"message":"Completed 200 in 12ms"}
request_id есть только тогда, когда у строки он есть (внутри запроса или в
задаче, которую запрос поставил в очередь) и log_tags его показывает; tags
содержит остальные теги по порядку. Когда сообщение (или тег) не является
корректным UTF-8, каждый его байт начиная с 0x80, включая байты корректных
символов, пишется в JSON как экранирование \ufffd, так что один плохой байт
превращает весь не-ASCII текст сообщения в символы замены; корректное
сообщение пишется как есть, а текстовая строка сохраняет байты такими, какими
их записали. Формат, отличный от :text и :json, останавливает загрузку:
error: log_format must be :text or :json (got :xml). Первая строка самой
загрузки (предупреждение о mail_delivery_method :test вне тестов) следует
формату; предупреждения о настройке приложения с неверным значением
(setting_int, setting_bool возвращаются к значению по умолчанию) пишутся, пока выполняется config/app.rb, до того как формат
известен, и всегда текстовые.
Уровень и формат действуют для ./<app> server, worker и feeds, а также
для зарегистрированных команд, jobs и console, которые отклоняют
неизвестное значение тем же сообщением и статусом выхода 1 до открытия базы.
migrate, db и dbconsole их не применяют: их строки — текст уровня
info.
Идентификаторы запросов
Каждый запрос получает идентификатор, UUID версии 4, который действие читает
как request.request_id, а ответ возвращает в X-Request-Id, в том числе в
403 проверки хоста, в https-редиректе force_ssl, на страницах ошибок, на
диагностической странице режима разработки и в собственном 500 сервера. 400
и 413 сервера для запроса, который он не может прочитать, отданные до того,
как его увидит приложение, идентификатора не несут. Каждая строка, записанная
во время запроса, несёт идентификатор как тег (первый при log_tags по
умолчанию), включая собственные
строки приложения Cybertrain.logger.info, и так же потоковое тело
(stream do ... end, Server-Sent Events) или соединение WebSocket, открытое
запросом, пока оно открыто.
Cybertrain.logger.info("export #{report.id} for #{request.request_id}")
Идентификатор прокси берётся только от прокси, которому приложение доверяет:
когда соединение приходит от доверенного прокси (CYBERTRAIN_TRUSTED_PROXY
или CYBERTRAIN_TRUSTED_PROXIES, та же проверка, что делает
request.client_ip;
Адрес клиента за прокси) и
его X-Request-Id — от 1 до 255 латинских букв ASCII, цифр и дефисов, запрос
берёт этот идентификатор, так что лог прокси и лог приложения его разделяют.
Любой другой X-Request-Id, включая заголовок, отправленный дважды,
отбрасывается и создаётся новый идентификатор; он никогда не изменяется.
c.log_tags выбирает теги запроса по порядку: [:request_id] по умолчанию,
[:request_id, :remote_ip], чтобы добавить request.client_ip (выключено
по умолчанию: адрес — персональные данные), [] — ни одного (заголовок всё
равно отправляется). Любое другое значение останавливает загрузку:
error: log_tags may hold :request_id and :remote_ip (got :user_agent).
Теги
Cybertrain.logger.tagged добавляет теги к каждой строке, записанной в этом
потоке во время блока, после собственных тегов запроса, и снимает их, когда
блок заканчивается, в том числе когда он бросает исключение; возвращает
значение блока. Блоки вкладываются. Формы без блока нет.
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
Теги принадлежат потоку: поток, который вы запускаете, начинает без тегов, какие бы ни были у запустившего его потока. Фреймворк так же помечает свою работу:
- Задачи. Строки каждой попытки несут
[<JobClass> <id>](для блочной задачи изJob.handle— её вид), затем идентификатор запроса, который поставил её в очередь:INFO [WelcomeJob 7] [3f2a9c1e-...] welcome 1. Идентификатор записывается в строку задачи (cybertrain_jobs.request_id) при любыхlog_tagsи показывается, когдаlog_tagsсодержит:request_id. Задача, поставленная задачей, записывает идентификатор родителя; поставленная задачей по расписанию, фидом или командой не записывает никакого. - Задачи по расписанию.
[schedule:<name>], пока задача выполняется, включая строку о сбое. - Фиды.
[feed:<name>]на каждой строке, которую пишет поток фида, включая его колбэки. Строки супервизора о перезапуске и отказе, записанные в его собственном потоке, тегов не несут.
Отчёты об ошибках
Cybertrain.error собирает исключения, которые завершают запрос, попытку
задачи, задачу по расписанию или фид, а также те, о которых приложение
сообщает само, и передаёт каждое подписчикам, которых добавляет приложение,
и в Sentry (или GlitchTip), когда задан DSN. Он в ядре; отправка в Sentry —
отдельная строка, которую загружает require "cybertrain", а приложение на
cybertrain/core добавляет в bin/<app>.rb (не в bin/db.rb;
Подсистемы). cybertrain new пишет строки этого
раздела закомментированными: переменные в .env.example, подписчика в
config/app.rb, DSN в config/deploy.yml и .kamal/secrets и эту строку в
комментарии bin/<app>.rb:
require "cybertrain/error_reporter/sentry" # bin/<app>.rb, после require "cybertrain/core"
# То, что приложение перехватило, вместе с тем, что оно знает:
begin
charge(order)
rescue PaymentError => e
Cybertrain.error.report(e, context: { "order_id" => order.id })
end
# Выполнить блок, сообщить о том, что он бросил, продолжить с nil:
price = Cybertrain.error.handle(context: { "feed" => "prices" }) do
parse_price(text)
end
report(e, handled: true, context: {}) сразу возвращает nil: отчёт
доставляется в собственном потоке репортёра. Ключи и значения контекста
становятся String и накладываются поверх контекста, который добавляет
фреймворк (идентификатор и попытка задачи). handle(context: {}) { }
возвращает значение блока или nil после отчёта о StandardError (или
JSON::ParserError, JSON::NestingError), брошенной блоком; break v в его
блоке заставляет handle вернуть v, а return выходит из окружающего
метода. Исключение вне этих классов, брошенное в блоке handle, доходит до
вызывающего кода. Сам отчёт никогда не бросает исключение в вызывающий код:
если он не удался, в лог на уровне error пишется
error report failed: <Class>: <message>.
Подписчики. Подписчик — это класс приложения, подкласс
Cybertrain::ErrorSubscriber, который определяет report(event):
# config/app.rb, выше строки, которая его подписывает (bin/<app>.rb загружает
# config/app до app/, поэтому класс из app/ здесь ещё не загружен)
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)
Каждый подписчик получает каждый отчёт в потоке репортёра, а не в запросе или
задаче, которые упали. Подписчик, бросивший исключение, пишется в лог на
уровне error, error subscriber AuditSubscriber failed: <Class>: <message>, и
сам никогда не попадает в отчёт; остальные всё равно получают событие.
Событие — это значение из String:
| Метод чтения | Что |
|---|---|
error_class |
имя класса исключения с пространством имён ("Cybertrain::DB::Error") |
error_message |
его сообщение |
error_where |
"ArticlesController#create", "request" (ни одно действие не выполнялось), класс или вид задачи, "cybertrain mail", "job thread", "schedule:<name>", "feed:<name>" или "" |
error_request_id, error_request_method, error_request_path |
значения запроса, путь без строки запроса и отфильтрованный так же, как его фильтрует журнал запросов; в задаче — идентификатор запроса, который её поставил; "" вне запроса |
error_environment, error_release |
Cybertrain.config.env и c.release |
error_handled |
true для report и handle, false для того, о чём сообщил фреймворк |
error_context |
Hash{String => String}: контекст приложения, а в задаче job.id, job.attempt, job.max_attempts |
error_backtrace |
Array<String>, пустой в бинарнике из cybertrain build (ниже) |
error_occurred_at |
Time, из часов |
О чём сообщается без единой вашей строки:
- О запросе, который закончился 500, один раз: об исключении, которое
Cybertrain::ClientError.status_forсопоставляет с 500 или выше. Никогда о 4xx (неверный параметр, сбой CSRF, 404), никогда о том, что обработалrescue_from. Если затем отдача страницы ошибки бросит новое исключение (нечитаемыйpublic/500.html), о нём тоже сообщается: два отчёта, каждый о настоящем сбое. - О неудачных попытках задачи (
where— её класс или вид; в контекстеjob.attemptиjob.max_attempts) при политике по умолчанию,retry_onилиdiscard_on. Внутри задачи ключ устранения дублей содержит и идентификатор задачи (Доставка, ниже): две задачи одного вида, упавшие одинаково, — это два отчёта, а попытка задачи, упавшая с теми же классом и сообщением, что и её собственная попытка, о которой сообщили меньше минуты назад, пишется в лог, но в отчёт снова не попадает (при политике по умолчанию первый повтор ждёт минуту, поэтому сообщается о каждой попытке; сretry_on ..., wait: 30попытка через 30 секунд после той, о которой сообщили, в отчёт не попадает). Об отбрасывании сообщается один раз.job.max_attempts— этоjob_max_attemptsпри политике по умолчанию,attempts:политики приretry_onи попытка, на которой она закончилась, приdiscard_on. Неудачное письмоdeliver_laterотносится к задачеcybertrain mail. Исключение, которое вырвалось из цикла потока задач, или ошибка базы данных там имеютwherejob thread. - О задаче по расписанию, чей блок бросил исключение, или о задаче
cronбез следующего запуска в пределах пяти лет (schedule:<name>). - Об
on_open,on_messageилиon_tickфида, бросившем исключение, о погибшем потоке фида и о супервизоре, отказавшемся от фида (Cybertrain::Background::FeedFailed, имя без класса за ним, с сообщениемfeed <name> restarted <n> times in <w> s; exiting), всёfeed:<name>.
Об исключении, брошенном во время записи потокового тела (stream do ...
end, Server-Sent Events) или соединения WebSocket после апгрейда,
сообщается один раз, после строки сервера
stream error: <Class>: <message>, с идентификатором, методом и путём запроса и where
ArticlesController#index (stream) (request (stream), если ни одно
действие не выполнялось). Ушедший клиент (EOFError, IOError,
Errno::ECONNRESET, Errno::EPIPE из писателя) пишется в лог этой строкой,
но в отчёт не попадает. Не сообщается: задача, у вида которой нет
обработчика, и, в режиме разработки, исключение, которое бросает сама
диагностическая страница, показывая уже отправленное в отчёт исключение.
Каждая строка лога, которую фреймворк писал раньше, остаётся как была; отчёт
идёт в дополнение.
Что никогда не отправляется. Параметры, заголовки, cookies, сессия, адрес
клиента и строка запроса в событие не входят; путь запроса фильтруется так
же, как его фильтрует журнал запросов. Добавляется только то, что приложение
кладёт в context:. Сообщения исключений отправляются как есть, если их не
меняет фильтр: сообщению с персональными данными (отказ SMTP-сервера,
называющий получателя) он нужен.
Фильтры. Фильтр — это подкласс Cybertrain::ErrorReporter::Filter,
который определяет filter_event(event) и отвечает true, чтобы оставить
событие, и false, чтобы отбросить его. Он может менять сообщение
(event.error_message =) и контекст (event.set_error_context(key, value),
event.delete_error_context(key)). Первый из этих фильтров маскирует
простые адреса электронной почты ASCII без кавычек, второй отбрасывает класс, о котором приложение не
хочет сообщать:
# 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)
Шаблон в MaskAddresses пропускает два вида адресов. Адрес с символами вне
ASCII, например alice@例え.テスト: в Ruby \w совпадает с латинскими
буквами, цифрами ASCII и _, если не запрошено свойство Unicode. И адрес с
локальной частью в кавычках, например "alice smith"@example.com: шаблону нужна
буква, цифра, ., +, - или _ прямо перед @, после закрывающей
кавычки её нет, и он ничего в нём не находит, так что адрес целиком
остаётся в сообщении. Напишите шаблон для ожидаемых адресов
или отбросьте событие.
Фильтры выполняются в потоке репортёра, в порядке добавления, до
подписчиков и отправителя; следующий фильтр, подписчики и Sentry видят то,
что фильтр изменил. Как только один отбрасывает событие, следующие не
выполняются и никто его не получает (оно не считается среди отбрасываний
очереди). Фильтр, бросивший исключение, отбрасывает событие, ведь фильтр
существует, чтобы что-то не ушло наружу, и пишет в лог на уровне error
error filter failed: <Filter class>: <Class>: <message>; в отчёт это не
попадает. Устранение дублей решается до фильтров, по нефильтрованным
классу, сообщению и where: переписывание фильтром не меняет, какие отчёты
сливаются, а событие, отброшенное фильтром, всё равно занимает своё место на
минуту. Собственная строка ERROR фреймворка пишется до того, как событие
появилось, и не фильтруется. Один фильтр не ставит отчёты в очередь (нужен
подписчик или DSN). Фильтры, добавленные в config/app.rb, остаются для
каждого теста; добавленный в тесте убирается перед следующим.
Доставка. Отчёты попадают в очередь на 100 и доставляются одним потоком.
Одинаковые класс, сообщение и where (а внутри задачи и её идентификатор)
попадают в очередь не чаще раза в
минуту, так что страница, которая падает у каждого посетителя с одним и тем
же сообщением, даёт один отчёт в минуту (сообщение с идентификатором,
Couldn't find Article with id=5, даёт по одному на каждое отдельное
сообщение); когда очередь полна, отчёт отбрасывается и считается, а
error reports dropped: <n> пишется на уровне warn не чаще раза в минуту.
Пока нет ни подписчика, ни DSN, ничего не ставится в очередь и поток не
запускается. Неудачная доставка пишется в лог,
error delivery failed: <Class>: <message>, и следующий отчёт запускает
новый поток, если старый завершился. Когда сервер, воркер или процесс feeds
останавливается, он после остановки своих служб ждёт отчёты из очереди до 2
секунд; оставшееся теряется. Пересборка в режиме разработки тоже ждёт, как
и зарегистрированная команда, ./<app> jobs и ./<app> console перед тем,
как закрыть базу и завершиться.
Отправка в Sentry или GlitchTip. Со строкой в bin/<app>.rb установка
CYBERTRAIN_SENTRY_DSN (или c.sentry_dsn) в DSN проекта отправляет каждый
отчёт как событие Sentry:
export CYBERTRAIN_SENTRY_DSN=https://PUBLIC_KEY@o1.ingest.sentry.io/42
export CYBERTRAIN_RELEASE=2026.11.14-3f2a9c1 # необязательно: отправляется как release события
export CYBERTRAIN_ERROR_SAMPLE_RATE=0.25 # необязательно: отправлять четверть
- DSN имеет вид
http[s]://<public key>[:<secret>]@<host>[:<port>][/<path>]/<project id>(secret, старая вторая половина Sentry, игнорируется); события уходят на<scheme>://<host>[:<port>][/<path>]/api/<project id>/envelope/, что принимают и Sentry, и GlitchTip. В нём ключ: храните его в секретах развёртывания, а не в файле под версионным контролем. Нечитаемый DSN останавливает загрузку, называя часть и никогда ключ:error: sentry_dsn must look like https://<public key>@<host>/<project id>: the project id must be digits. - DSN, заданный в программе, которая не связывает отправитель, останавливает
загрузку и приводит к отказу зарегистрированной команды,
jobsиconsoleдо открытия базы (статус выхода 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. Ваш собственный класс отправителя (подклассCybertrain::ErrorReporter::Sender) определяетsender_name, который возвращает непустое имя, иначе он получает тот же отказ. CYBERTRAIN_ERROR_SAMPLE_RATE(c.error_sample_rate, 1.0) — доля отправляемых отчётов, от 0.0 до 1.0; подписчики по-прежнему видят каждый отчёт. Переменная должна быть цифрами с необязательной.цифрами, иначе загрузка останавливается:error: error_sample_rate must be a number from 0.0 to 1.0 (got "x").CYBERTRAIN_RELEASE(c.release, по умолчанию пусто) называет версию или коммит; не проверяется.- Каждая отправка ждёт не более 5 секунд после разрешения имени хоста
(разрешение имени блокирует поток доставки, и срок не может его прервать,
так что зависший резолвер может задержать отправку дольше) и никогда не
повторяется. Отказ
пишется на уровне warn,
error report not sent: Sentry answered 429, как и сбой соединения,error report not sent: <Class>: <message>. - Событие несёт класс и сообщение,
whereкак transaction, окружение, release, идентификатор запроса как тег, метод и путь запроса, контекст какextraи обратную трассировку как кадры, если она есть. - Вызов идёт через
Cybertrain::HttpClientи его защиту от частных адресов (Исходящий HTTP): GlitchTip в частной сети или на той же машине требуетCYBERTRAIN_HTTP_ALLOW_PRIVATE=1, что снимает защиту для каждого исходящего вызова приложения.
Обратные трассировки. Бинарник из cybertrain build — это релизная
сборка Spinel, исключения которой не несут обратной трассировки: её отчёты
содержат класс, сообщение и where. В сборке --debug и под CRuby кадры
прикладываются.
cybertrain test ничего не отправляет в Sentry: он опустошает
экспортированный CYBERTRAIN_SENTRY_DSN, если config/app.rb его не
присваивает, а тест вместо этого направляет DSN на Test::SentryReceiver
(Тестирование журнала и отчётов об ошибках).
Проект: docs/design.md D86 и D88.
Обновление журнала и отчётов об ошибках с 0.4
- Каждая строка лога меняет форму: уровень в квадратных скобках в начале
(
[INFO]) уступает место времени, уровню и тегам,2026-11-14T09:30:00.132Z INFO [<request id>] Completed 200 in 3ms. То, что читает лог (grep по[ERROR]в скрипте, оповещение), меняется вместе с ним; тест, который искал строку целиком, ищет уровень и сообщение по отдельности (" ERROR "и сообщение; Обновление с 0.4). - Каждый ответ приложения несёт
X-Request-Id(кроме 400 и 413 сервера для запроса, который он не может прочитать). Прокси, который его ставил, видит своё значение использованным, только если прокси доверенный. cybertrain_jobsполучает столбецrequest_id; его добавляет первый процесс, обратившийся к таблице.- Текстовая строка лога больше не продолжается на следующих строках:
перевод строки или возврат каретки в сообщении или теге пишется как
\nили\r. То, что читало многострочное сообщение по нескольким строкам, читает экранирование. - Столбец модели с именем
handleтеперь читается какhandle_column: приложение со столбцомusers.handleменяет вызовыuser.handleнаuser.handle_column(запросы сохраняют имя SQL). Столбцыrequest_idилиrelease, которые не текстовые, gen отклоняет (Имена столбцов). cybertrain testигнорирует экспортированныеCYBERTRAIN_LOG_FORMATиCYBERTRAIN_SENTRY_DSN(тесты читают текстовые строки и ничего не отправляют), еслиconfig/app.rbих не задаёт. Тесты паролей, которые пишетgenerate authentication, выключают строки JSON внутри своегоwith_config; приложение, сгенерированное раньше, чьи тесты идут сlog_format :json, перезапускает генератор или переносит это изменение.require "cybertrain"теперь связываетHttpClientи слой TLS через отправитель Sentry.