CyberTrainРуководстваФоновая работа и эксплуатация

Фоновая работа и эксплуатация

Фоновая работа

Приложение, которому нужно сделать что-то вне запроса (отправить уведомление после того, как ответ ушёл, каждую ночь вычищать старые строки, повторить неудавшийся вызов), поручает это фреймворку, а тот выполняет работу в фоновых потоках обслуживающего процесса или отдельного процесса-обработчика. Задача — это класс в app/jobs/, как в Rails. Задачам и задачам по расписанию нужна строка require "cybertrain/jobs" в bin/<app>.rb и bin/db.rb; её добавляет cybertrain generate job (Подсистемы):

ruby
# 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
ruby
# в действии, после сохранения пользователя
WelcomeJob.perform_later("user_id" => @user.id)
WelcomeJob.perform_in(600, "user_id" => @user.id)   # или perform_at(time, args)
ruby
# 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): под Spinel rescue, называющий класс, которого программа не определяет, может проглотить любое исключение. 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:

ruby
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

ruby
# 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 делает то же самое на настроенной базе данных (он не запускает потоков):

sh
./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_ttl 30 с), и только её держатель выполняет наступившие задачи; другой перехватывает её, когда держатель перестаёт продлевать. Аренда продлевается перед каждой задачей, а не во время её выполнения, так что задача длиннее 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 или туда, где он используется:

ruby
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.

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: — источником.

sh
./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 отдельным процессом:

sh
# 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, пока оно не закончится.

ruby
# 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):

вывод — ./blog servertext
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") пишет одну строку:

вывод — одно событие, одна строкаtext
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 на строку, для сборщика логов:

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, открытое запросом, пока оно открыто.

ruby
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 добавляет теги к каждой строке, записанной в этом потоке во время блока, после собственных тегов запроса, и снимает их, когда блок заканчивается, в том числе когда он бросает исключение; возвращает значение блока. Блоки вкладываются. Формы без блока нет.

ruby
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:

ruby
require "cybertrain/error_reporter/sentry"   # bin/<app>.rb, после require "cybertrain/core"
ruby
# То, что приложение перехватило, вместе с тем, что оно знает:
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):

ruby
# 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. Исключение, которое вырвалось из цикла потока задач, или ошибка базы данных там имеют where job 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 без кавычек, второй отбрасывает класс, о котором приложение не хочет сообщать:

ruby
# 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:

sh
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.