За основу документа взят англоязычный Run Book Template. Это вольный перевод + адаптация под нужды собственных проектов. Так или иначе это может подойти тем, кто развертывает и сопровождает несколько программных сервисов на эжедневной основе.

В сопровождаемой системе такое описание пригодится для любого сервиса, даже очень старого или маленького, описание эксплуатации поможет более глобально анализировать точки отказа сервисов, а так же упростит скорость входа новых программистов в проект.

Краткое описание сервиса

Микросервис для гарантированной отправки email сообщений, работает 24/7

Какие проблемы закрывает сервис? Какую ценность он несет с точки зрения бизнеса? Какие ожидания с точки зрения доступности и гарантий ждет бизнес от этого сервиса?

Делаем возможность отправлять email сообщения легко и просто, избегаем попадения в папку spam и обеспечиваем около 100%-ую достовляемость десяткам тысяч клиентов

Какой тип сервиса? Монолит или микросервис? API backend или background tasks processing? Многофуонционален или выполняет одну задачу? Где хранит состояние?

Микросервис для отправки email сообщений, принимает сообщения через SQS и общается с внешними email-гейтами, формат сообщений определен через protobuf, хранит состояние в postgresql

Какую доступность и работоспобность должен гарантировать сервис?

Сервис должен работать 100% времени, при неуспешной отправке сообщения оно должно быть отправлено еще раз, rabbitmq должен обеспечить сохранность сообщений на время падения сервиса.

Из каких приложений, демонов, middlerware и баз данных состоит ваш сервис?

ruby приложение + sidekiq демон + rabbitmiq демон + postgresql@12 + elasticsearch@6 + statsd демон

Как данные попадают и обрабатываются в cистеме? Что вызывает обработку данных, какие триггеры или другие события влияют на работу системы?

прямые http запросы к api, сообщения от других сервисов в rabbitmq/sqs, everyday джобы которые выкачивают данные

Как система обрабатывает аварийные сценарии? Какие механизмы обеспечения доступности реализованы?

kubernetes кластер, master-slave postgresql кластер, эжедневные бэкапы в 21:00

Может ли сервис быть частично погашен? Можно ли скейлить сервис увеличивая кол-во нод в сети?

Сервис принимает сообщения асинхронно, а значит может не работать какое-то время, при этом одна нода обеспечивает обработку около 1500 сообщений в секунду.

Сколько одновременных коннектов/нагрузки может выдержить сервис? Что является узким местом в системе и что мешает скейлингу?

Скейлинг упрется на отметке в ~ 10 нод, так как боттлнеком станет код-во коннектов к базе данных.

В чем отличия production и staging окружений вашего сервиса? С какими вещами на staging'е нужно быть особенно аккуратным, чтобы не затронуть реальный мир?

В staging окружение письма не должны уходить в реальный мир.

Особенности конфигурации в разных окружениях

Конфигурация каждого окружение отдельно хранится в consule

Инструменты и форматы логирования

json логи пишутся в STDOUT, затем забираются в наш elasticsearch

лог должен начинаться с "app":"имя приложения"

Список самых важных метрик сервиса

• email_messages.sent
• email_messsages.failed

Любой метод для проверки работоспособности сервиса

Работоспосбность сервиса можно проверить по урлу /health, статус 200 говорит о том что сервис работает (принимает сообщение и успешно выполняет тестирующие запросы в базу данных)