lowkiq 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '058eb93d910f0a3a8ebc243c6c05df173d9e03555dcabc2f554f05f40df11306'
+  data.tar.gz: 5a6437e5896ced972de4722b84066ef93b30b36a1be33eb01656559c50848383
+SHA512:
+  metadata.gz: 540ceb803a0bc1e811f28a0c15a00f6ded92bf58302bd791cb2539beafbe71f13a878792889fbb438f8dfe77820e6148278472884c4d071faa7440c98df46687
+  data.tar.gz: 02a7bb2ab6e80c2e223a9d515a760aeae41d8db75562612830077e2e5e9a8e79b6446814c03ea130751c338d771c1a3a4b20a2445ed6429450b0864e226aa55b

data/.gitignore

@@ -0,0 +1,3 @@
+.rspec_status
+/assets
+/*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in lowkiq.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    lowkiq (1.0.0)
+      connection_pool (~> 2.2, >= 2.2.2)
+      rack (>= 1.5.0)
+      redis (>= 4.0.1, < 5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    connection_pool (2.2.2)
+    diff-lcs (1.3)
+    rack (2.0.5)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rake (10.5.0)
+    redis (4.1.3)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  lowkiq!
+  rack-test (~> 1.1)
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rspec-mocks (~> 3.8)
+
+BUNDLED WITH
+   1.16.4

data/LICENSE.md

@@ -0,0 +1,133 @@
+# Licence Agreement
+On granting a non-exclusive right to use open source software
+
+**BIA-Technologies  Limited Liability Company (OOO)**, registered and operating under the laws of the Russian Federation, state registration date November 6, 2014, under the main state registration number (OGRN) 1147847386906, registered in the Interdistrict FTSI (Federal Tax Service Inspectorate) of Russia No. 23 on Saint-Petersburg (TIN (taxpayer ID number) 7810385714, RRC (registration reason code) 781001001), hereinafter referred to as the **"Licensor"**, represented by the Director General Sergey Sergeevich Barykin, acting under the Charter, guided by paragraph 1 of Article 1286.1 of the Civil Code of RF (Russian Federation),  provides the user (hereinafter referred to as **"the Licensee"**) on the basis and under the terms of this licence agreement (hereinafter the “Agreement”) the non-exclusive right to use **the Lowkiq open source software**:
+
+## 1. SUBJECT OF AGREEMENT
+
+1.1. The Licensor provides the Licensee, in the manner and on the terms set forth in this Agreement, the right to use (license) **the Lowkiq open source software** (hereinafter - the "Software").
+
+1.2. The source code for the software is available on the website located in the Internet telecommunication network "Internet" at the address: https://github.com/bia-tech/lowkiq.
+
+1.3. Software characteristics, that individualize it as a unique result of intellectual activity:
+
+1.3.1. Functionality: Server for the  streamlined parallel processing of Ruby background tasks.
+
+1.3.2. Requirements for working with the software: Redis >= 3.2 is required to work with the Library
+
+1.4. The licensor guarantees, that it is the copyright holder of the exclusive right on the software, that is not alienated, not mortgaged and not challenged.
+
+1.5. The software is not registered with the federal executive authority for intellectual property.
+
+1.6. The right to use (license) granted to the Licensee under this Agreement is non-exclusive. The Licensor reserves the right to grant licenses to other parties.
+
+1.7. The right to use the software (license) is issued from the moment the Licensee joins the terms of this Agreement in electronic form.
+
+1.8. Under this Agreement, the use of the Software by the Licensee is allowed all over the world.
+
+## 2. RIGHTS ASSIGNED TO THE LICENSEE ON THIS AGREEMENT
+
+2.1. Under this Agreement, the Licensor grants the Licensee the right to use the software in the following ways:
+  * reproduction (full or partial), that is, the production of one or more copies of the software or its part in any tangible form, including, but not limited to, recording the software on an electronic media, including writing to the memory of the Licensee’s computer, without restrictions on the number of such computers;
+  * distribution by any means and in any ways of software copies through the Licensee’s internal LAN, on the Licensee’s computer, among the employees of the Licensee, related to it with labor and (or) civil - law relations.
+
+## 3. PROCEDURE FOR ASSIGNMENT OF AN INSTANCE AND NON-EXCLUSIVE RIGHTS TO THE SOFTWARE
+
+3.1. The assignment of a copy of the software to the Licensee is carried out by downloading a copy of the software by the Licensee fro the website, located in the Internet telecommunication network “Internet” at the address: https://github.com/bia-tech/lowkiq.
+
+## 4. RIGHTS AND OBLIGATIONS OF THE PARTIES UNDER THIS AGREEMENT
+
+4.1. The licensor undertakes:
+
+4.1.1. assign to the Licensee the software free of the rights of third parties, in the manner prescribed by this Agreement, in a condition that allows its use on the terms of this Agreement, no later than the day the Agreement is concluded;
+
+4.1.2. refrain from any action that could impede the Licensee from exercising the rights granted to him under this Agreement;
+
+4.1.3. comply with confidentiality in accordance with section 8 of this Agreement.
+
+4.2. Licensee undertakes:
+
+4.2.1. at the request of the Licensor, provide him with the opportunity to get acquainted with accounting and other documents containing information about the use of the software;
+
+4.2.2. at the request of the Licensor, provide a report on the use of the software in accordance with this Agreement in the time and manner specified in such a requirement;
+
+4.2.3. comply with confidentiality in accordance with section 8 of this Agreement.
+
+4.3. Licensee has the right:
+
+4.3.1. carry out actions, necessary for the functioning of the software (including during use in accordance with the purpose), including recording and storing in memory of an unlimited number of Licensee's computers;
+
+4.3.2. study, research, test the functioning of the software for the purpose of its use in accordance with this Agreement.
+
+Application of the provisions of clause 4.3. of this Agreement shall not contradict the normal use of the software and shall not infringe in any other way the rights and legitimate interests of the Licensor.
+
+## 5. REMUNERATION FOR THE ASSGNMENT  OF NON-EXCLUSIVE RIGHTS UNDER THIS AGREEMENT
+
+5.1. Compensation for using the software under this Agreement is not pad  by the Licenseeo the Licensor on the basis of paragraph 1 of clause 3 of Article 1286.1 of the Civil Code of RF.
+
+## 6. EXCLUSIVE SOFTWARE RIGHTS
+
+6.1. Exclusive rights to the software, all modules compiling the software, copied and / or included in all softwares, provided to the Licensee under this Agreement, or in its part, as well as all documentation related to the software, belong to the Licensor.
+
+6.2. The Licensee may not use the software not on its own behalf, and also may not use the software in ways not established by this Agreement.
+
+6.3. The Licensor confirms that at the time of signing this Agreement, he does not know anything about the rights of third parties, that could be violated by granting the Licensee a non-exclusive right to use the software under this Agreement.
+
+6.4. The Licensor will assist the Licensee in the consideration of claims of third parties related to the use of the software, in case of receipt of information about such claims from the Licensee. In the event of receipt of information on the filing of such a claim, the Licensee shall immediately inform the Licensor of all claims made by the plaintiff and provide all information that he has regarding such a dispute.
+
+## 7. RESPONSIBILITY OF THE PARTIES UNDER THIS AGREEMENT
+
+7.1. For failure to fulfill or improper fulfillment of obligations under this Agreement, the Parties are liable in accordance with the current legislation of the Russian Federation.
+
+7.2. The use by the Licensee of the software in a manner not provided for by this Agreement, or after the termination of the Agreement, or otherwise - beyond the rights, granted to the Licensee under the Agreement, shall entail liability for violation of exclusive rights to the result of intellectual activity, established by the current legislation of the Russian Federation.
+
+## 8. EMERGENCIES
+
+8.1. The parties are exempted from liability for full or partial failure to fulfill obligations under this Agreement,if such failure is the result of emergencies  (“force majeure circumstances”), which include riots, prohibitive actions of authorities, natural disasters, fires, catastrophes and other emergencies  that the Parties cannot influence. The parties will consider the document issued by the authorized body of state power and (or) the corresponding chamber of commerce to be proper evidence of the presence of  the emergencies.
+
+8.2. The parties are obliged to notify each other in writing about the existence of emergencies within 3 (three) days from the date of their discovery.
+
+## 9. DISPUTE RESOLUTION PROCEDURES
+
+9.1. All disputes and disagreements that may arise between the Parties on issues that have not been resolved in the text of this Agreement will be resolved through negotiations (in the complaint procedure) in accordance with the current legislation of the Russian Federation. The term for responding to a claim is 14 (fourteen) calendar days.
+
+9.2. If the dispute is not settled during the negotiations, the disputes are referred to the Court at the location of the Plaintiff
+
+## 10. VALIDITY AND PROCEDURE OF TERMINATION OF THIS AGREEMENT
+
+10.1. This Agreement is considered concluded and comes into force from the moment the Licensee joins its terms in electronic form (clause 2 of Article 434 of the Civil Code of the Russian Federation). The term of this Agreement may not exceed the term of the exclusive right to software.
+
+10.2. The non-exclusive right to use the software received by the Licensee shall terminate upon the early termination or termination of this Agreement.
+
+10.3. In case of violation by the Licensee of any obligation under this Agreement, the Licensor has the right to send a written notice to the Licensee demanding that this obligation be performed. In case of failure to fulfill or improper fulfillment of such an obligation within 3 (three) calendar days after the receipt by the Licensee of the written notice, this Agreement may be terminated by sending  a notice of unilateral cancellation of this Agreement from the  Licensor the Licensee . In this case, the Agreement shall be deemed to have expired upon the expiration of 3 (three) calendar days from the date a receipt of such notification.
+
+10.4. After the termination of this Agreement, the Licensee shall immediately cease using the software and continue to not use it. Within 5 (five) business days from the date of termination or denouncement of the Agreement, the Licensee must destroy all copies of the software received under this Agreement.
+
+10.5. Termination of the Agreement does not relieve the Licensee from the fulfillment of the obligation to pay fees in accordance with this Agreement
+
+## 11. FINAL PROVISIONS
+
+11.1. None of the Parties has the right to assign their rights and obligations under the Agreement to third parties without the written consent of the other Party.
+
+11.2. In all other aspects, which are not provided by this Agreement, the Parties will be guided by the current legislation of the Russian Federation.
+
+11.3. When activating and using the software, the Licensee agrees with all the terms of this Agreement, and also agrees to the transfer, receipt and processing of the  personal data.
+
+## 12. ADDRESS AND DETAILS OF THE LICENSOR:
+
+LICENSOR:
+
+OOO BIA- Technologies  (Limited Liability Company)
+
+Statutory Seat and  the postal address: 196084, Russian Federation,<br>
+g. Saint-Petersburg, pr. Moskovskiy, d.94, lit. A, pom. 12- H
+
+OGRN 1147847386906
+
+TIN/ 7810385714
+
+RRC/ 781001001
+
+Name and email address of the representative:<br>
+Pryalkin Andrey Yuryevich<br>
+Andrey.Pryalkin@bia-tech.ru<br>

data/README.md

@@ -0,0 +1,577 @@
+# Lowkiq
+
+Упорядоченная обработка фоновых задач.
+
+![dashboard](doc/dashboard.png)
+
+## Rationale
+
+При использовании Sidekiq мы столкнулись с проблемами при обработке сообщений от сторонней системы.
+
+Sidekiq не гарантирует строгого порядка сообщений, т.к. очередь обрабатывается в несколько потоков.
+Например, пришло 2 сообщения: M1 и M2.
+Sidekiq обработчики начинают обрабатывать их параллельно,
+при этом M2 может обработаться раньше M1.
+
+В очереди могут находиться сообщения касающиеся одной сущности.
+Параллельная обработка таких сообщений приводит к:
+
++ dead locks
++ затиранию новых данных старыми
+
+Lowkiq призван устранить эти проблемы, исключая параллельность обработки сообщений в рамках одной сущности.
+
+## Description
+
+Очереди надежны, т.е. задачи не теряются в случае внезапного падения процесса.
+Очереди хранятся в Redis и могут не успеть записаться на диск, в случае падения Redis.
+
+Каждая задача имеет идентификатор. Очереди гарантируют, что не может быть ситуации,
+когда несколько потоков обрабатывают задачи с одинаковыми идентификаторами.
+
+Каждая очередь разбивается на постоянный набор шардов.
+На основе идентификатора задачи выбирается шард, в который попадет задача.
+Таким образом задачи с одним идентификатором всегда попадают в один и тот же шард.
+Задачи шарда всегда обрабатываются одним и тем же потоком.
+Это гарантирует порядок обработки задач с одинаковым идентификатором и исключает возможность блокировок.
+
+Кроме идентификатора задача имеет полезную нагрузку или данные задачи (payload).
+Задачи в очереди группируются по идентификатору.
+Таким образом одновременно в обработку попадают все накопленные полезные нагрузки задачи.
+
+Если задачи содержат изменения сущности, то обработчик их все разом применит.
+Если задачи содержат снимки (версии) сущности, то обработчик может использовать только последнюю версию.
+
+Каждой очереди соответствует воркер, содержащий логику обработки задачи.
+Для обработки задач используется фиксированное количество тредов,
+таким образом, добавление или удаление очереди/воркера не приводит к изменению числа тредов.
+Нет смысла задавать кол-во шардов одного воркера больше, чем общее кол-во тредов.
+
+## Аналоги
+
+Lowkiq можно рассматривать, в некотором смысле, как замену sidekiq, работающему с плагинами:
+
++ [sidekiq-grouping](https://github.com/gzigzigzeo/sidekiq-grouping)
++ [sidekiq-unique-jobs](https://github.com/mhenrixon/sidekiq-unique-jobs)
++ [sidekiq-merger](https://github.com/dtaniwaki/sidekiq-merger)
+
+## Benchmark
+
+5 threads, 100_000 blank jobs
+
++ lowkiq: 214 sec
++ sidekiq: 29 sec
+
+Этот [бенчмарк](examples/benchmark) показывает накладные расходы на взаимодействие с redis.
+В реальных задачах разница будет не так заметна.
+
+## Очередь
+
+Каждая задача в очереди имеет аттрибуты:
+
++ `id` - идентификатор задачи (строка)
++ `payloads` - сортированное множество payload'ов (объекты) по их score (вещественное число)
++ `perform_in` - запланированное время начала иполнения задачи (unix timestamp, вещественное число)
++ `retry_count` - количество совершённых повторов задачи (вещественное число)
+
+`id` может быть, например, идентификатором реплицируемой сущности
+`payloads` - множество,
+получаемое в результате группировки полезной нагрузки задачи по `id` и отсортированное по ее `score`.
+`payload` может быть объектом, т.к. сериализуется с помощью `Marshal.dump`.
+`score` может быть датой (unix timestamp) создания `payload`
+или ее монотонно увеличивающимся номером версии.
+По умолчанию - текущий unix timestamp.
+По умолчанию `perform_in` - текущий unix timestamp.
+`retry_count` для новой необработанной задачи равен `-1`, для упавшей один раз - `0`,
+т.е. считаются не совершённые, а запланированные повторы.
+
+`score`, `perform_at` и `retry_count` вещественные из-за особенностей работы redis.
+
+> Redis sorted sets use a double 64-bit floating point number to represent the score. In all the architectures we support, this is represented as an IEEE 754 floating point number, that is able to represent precisely integer numbers between -(2^53) and +(2^53) included. In more practical terms, all the integers between -9007199254740992 and 9007199254740992 are perfectly representable. Larger integers, or fractions, are internally represented in exponential form, so it is possible that you get only an approximation of the decimal number, or of the very big integer, that you set as score.
+
+Выполнение задачи может закончиться неудачей.
+В этом случае ее `retry_count` инкрементируется и по заданной формуле вычисляется новый `perform_at`,
+и она ставится обратно в очередь.
+
+В случае, когда `retry_count` становится `>=` `max_retry_count`
+элемент payloads с наименьшим(старейшим) score перемещается в морг,
+а оставшиеся элементы помещаются обратно в очередь, при этом
+`retry_count` и `perform_at` сбрасываются в `-1` и `now()` соответственно.
+
+### Алгоритм расчета retry_count и perform_in
+
+0. задача выполнилась и упала
+1. `retry_count++`
+2. `perform_in = now + retry_in(try_count)`
+3. `if retry_count >= max_retry_count` задача перемещается в морг
+
+| тип         | `retry_count` | `perform_in` |
+| ---         | ---           | ---          |
+| новая не выполнялась | -1 | задан или `now()` |
+| новая упала | 0 | `now() + retry_in(0)` |
+| повтор упал | 1 | `now() + retry_in(1)` |
+
+Если `max_retry_count = 1`, то попытки прекращаются.
+
+### Правило слияния задач
+
+Когда применяется:
+
++ если в очереди была задача и добавляется еще одна с тем же id
++ если при обработке возникла ошибка, а в очередь успели добавили задачу с тем же id
++ если задачу из морга поставили в очередь, а в очереди уже есть задача с тем же id
+
+Алгоритм:
+
++ payloads объединяются, при этом выбирается минимальный score,
+  т.е. для одинаковых payload выигрывает самая старая
++ если объединяется новая и задача из очереди,
+  то `perform_at` и `retry_count` берутся из задачи из очереди
++ если объединяется упавшая задача и задача из очереди,
+  то `perform_at` и `retry_count` берутся из упавшей
++ если объединяется задача из морга и задача из очереди,
+  то `perform_at = now()`, `retry_count = -1`
+
+Пример:
+
+```
+# v1 - первая версия, v2 - вторая
+# #{"v1": 1} - сортированное множество одного элемента, payload - "v1", score - 1
+
+# задача в очереди
+{ id: "1", payloads: #{"v1": 1, "v2": 2}, retry_count: 0, perform_at: 1536323288 }
+# добавляемая задача
+{ id: "1", payloads: #{"v2": 3, "v3": 4}, retry_count: -1, perform_at: 1536323290 }
+
+# результат
+{ id: "1", payloads: #{"v1": 1, "v2": 3, "v3": 4}, retry_count: 0, perform_at: 1536323288 }
+```
+
+Морг - часть очереди. Задачи в морге не обрабатываются.
+Задача в морге имеет следующие атрибуты:
+
++ id - идентификатор задачи
++ payloads - список
+
+Задачи в морге можно отсортировать по дате изменения или id.
+
+Задачу из морга можно переместить в очередь. При этом для нее `retry_count = 0`, `perform_at = now()`.
+
+### Api
+
+```ruby
+module ATestWorker
+  extend Lowkiq::Worker
+
+  self.shards_count = 24
+  self.batch_size = 10
+  self.max_retry_count = 5
+
+  def self.retry_in(count)
+    10 * (count + 1) # (i.e. 10, 20, 30, 40, 50)
+  end
+
+  def self.perform(paylods_by_id)
+    # payloads_by_id - хеш
+    payloads_by_id.each do |id, payloads|
+      # id - идентификатор задачи
+      # payloads отсортированы по score, от старых к новым (от минимальных к максимальным)
+      payloads.each do |payload|
+        do_some_work(id, payload)
+      end
+    end
+  end
+end
+```
+
+Значения по умолчанию:
+
+```ruby
+self.shards_count = 5
+self.batch_size = 1
+self.max_retry_count = 25
+self.queue_name = self.name
+
+# i.e. 15, 16, 31, 96, 271, ... seconds + a random amount of time
+def retry_in(retry_count)
+  (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1))
+end
+```
+
+```ruby
+ATestWorker.perform_async [
+  { id: 0 },
+  { id: 1, payload: { attr: 'v1' } },
+  { id: 2, payload: { attr: 'v1' }, score: Time.now.to_i, perform_in: Time.now.to_i },
+]
+# payload по умолчанию равен ""
+# score и perform_in по умолчанию равны Time.now.to_i
+```
+
+Вы можете переопределить `perform_async` и вычислять `id`, `score` и `perform_in` в воркере:
+
+```ruby
+module ATestWorker
+  extend Lowkiq::Worker
+
+  def self.perform_async(jobs)
+    jobs.each do |job|
+      job.merge! id: job[:payload][:id]
+    end
+    super
+  end
+
+  def self.perform(payloads_by_id)
+    #...
+  end
+end
+
+ATestWorker.perform_async 1000.times.map { |id| { payload: {id: id} } }
+```
+
+### Max retry count
+
+Исходя из `retry_in` и `max_retry_count`,
+можно вычислить примерное время, которая задача проведет в очереди.
+
+Для `retry_in`, заданного по умолчанию получается следующая таблица:
+
+```ruby
+def retry_in(retry_count)
+  (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1))
+end
+```
+
+| `max_retry_count` | кол-во дней жизни задачи |
+| --- | --- |
+| 14 | 1 |
+| 16 | 2 |
+| 18 | 3 |
+| 19 | 5 |
+| 20 | 6 |
+| 21 | 8 |
+| 22 | 10 |
+| 23 | 13 |
+| 24 | 16 |
+| 25 | 20 |
+
+`(0...25).map{ |c| retry_in c }.sum / 60 / 60 / 24`
+
+## Ring app
+
+`Lowkiq::Web` - ring app.
+
++ `/` - dashboard
++ `/api/v1/stats` - длина очереди, длина морга, лаг для каждого воркера и суммарно
+
+## Настройка
+
+Опции и значения по умолчанию:
+
++ `Lowkiq.poll_interval = 1` - задержка в секундах между опросами очереди на предмет новых задач.
+  Используется только если на предыдущей итерации очередь оказалась пуста или случилась ошибка.
++ `Lowkiq.threads_per_node = 5` - кол-во тредов для каждой ноды.
++ `Lowkiq.redis = ->() { Redis.new url: ENV.fetch('REDIS_URL') }` - настройка redis.
++ `Lowkiq.client_pool_size = 5` - размер пула редиса для постановки задач в очередь.
++ `Lowkiq.pool_timeout = 5` - таймаут клиентского и серверного пула редиса
++ `Lowkiq.server_middlewares = []` - список middleware, оборачивающих воркер.
++ `Lowkiq.on_server_init = ->() {}` - выполнения кода при инициализации сервера.
++ `Lowkiq.build_scheduler = ->() { Lowkiq.build_lag_scheduler }` - планировщик.
++ `Lowkiq.build_splitter = ->() { Lowkiq.build_default_splitter }` - сплиттер.
++ `Lowkiq.last_words = ->(ex) {}` - обработчик исключений, потомков `StandardError`, вызвавших остановку процесса.
+
+```ruby
+$logger = Logger.new(STDOUT)
+
+Lowkiq.server_middlewares << -> (worker, batch, &block) do
+  $logger.info "Started job for #{worker} #{batch}"
+  block.call
+  $logger.info "Finished job for #{worker} #{batch}"
+end
+
+Lowkiq.server_middlewares << -> (worker, batch, &block) do
+  begin
+    block.call
+  rescue => e
+    $logger.error "#{e.message} #{worker} #{batch}"
+    raise e
+  end
+end
+```
+
+## Splitter
+
+У каждого воркера есть несколько шардов:
+
+```
+# worker: shard ids
+worker A: 0, 1, 2
+worker B: 0, 1, 2, 3
+worker C: 0
+worker D: 0, 1
+```
+
+Lowkiq использует фиксированное кол-во тредов для обработки задач, следовательно нужно распределить шарды
+между тредами. Этим занимается Splitter.
+
+Чтобы определить набор шардов, которые будет обрабатывать тред, поместим их в один список:
+
+```
+A0, A1, A2, B0, B1, B2, B3, C0, D0, D1
+```
+
+Рассмотрим Default splitter, который равномерно распределяет шарды по тредам единственной ноды.
+
+Если `threads_per_node` установлено в 3, то распределение будет таким:
+
+```
+# thread id: shards
+t0: A0, B0, B3, D1
+t1: A1, B1, C0
+t2: A2, B2, D0
+```
+
+Помимо Default есть ByNode splitter. Он позволяет распределить нагрузку по нескольким процессам (нодам).
+
+
+```
+Lowkiq.build_splitter = -> () do
+  Lowkiq.build_by_node_splitter(
+    ENV.fetch('LOWKIQ_NUMBER_OF_NODES').to_i,
+    ENV.fetch('LOWKIQ_NODE_NUMBER').to_i
+  )
+end
+```
+
+Таким образом, вместо одного процесса нужно запустить несколько и указать переменные окружения:
+
+```
+# process 0
+LOWKIQ_NUMBER_OF_NODES=2 LOWKIQ_NODE_NUMBER=0 bundle exec lowkiq -r ./lib/app.rb
+
+# process 1
+LOWKIQ_NUMBER_OF_NODES=2 LOWKIQ_NODE_NUMBER=1 bundle exec lowkiq -r ./lib/app.rb
+```
+
+Отмечу, что общее количество тредов будет равно произведению `ENV.fetch('LOWKIQ_NUMBER_OF_NODES')` и  `Lowkiq.threads_per_node`.
+
+Вы можете написать свой сплиттер, если ваше приложение требует особого распределения шардов между тредами или нодами.
+
+## Scheduler
+
+Каждый тред обрабатывает набор шардов. За выбор шарда для обработки отвечает планировщик.
+Каждый поток имеет свой собственный экземпляр планировщика.
+
+Lowkiq имеет 2 планировщика на выбор.
+Первый, `Seq` - последовательно перебирает шарды.
+Второй, `Lag` - выбирает шард с самой старой задачей, т.е. стремится минимизировать лаг.
+Используется по умолчанию.
+
+Планировщик задается через настройки:
+
+```
+Lowkiq.build_scheduler = ->() { Lowkiq.build_seq_scheduler }
+# или
+Lowkiq.build_scheduler = ->() { Lowkiq.build_lag_scheduler }
+```
+
+## Исключения
+
+`StandardError` выброшенные воркером обрабатываются с помощью middleware.
+Такие исключения не приводят к остановке процесса.
+
+Все прочие исключения приводят к остановке процесса.
+При этом Lowkiq дожидается выполнения задач другими тредами.
+
+`StandardError` выброшенные вне воркера передаются в `Lowkiq.last_words`.
+Например это происходит при потере соединения к Redis или при ошибке в коде Lowkiq.
+
+## Изменение количества шардов воркера
+
+Старайтесь не менять кол-во шардов.
+
+Если вы можете отключить добавление новых заданий,
+то дождитесь опустошения очередей и выкатите новую версию кода с измененным кол-вом шардов.
+
+Если такой возможности нет, воспользуйтесь следующим сценарием.
+
+Например, есть воркер:
+
+```ruby
+module ATestWorker
+  extend Lowkiq::Worker
+
+  self.shards_count = 5
+
+  def self.perform(payloads_by_id)
+    some_code
+  end
+end
+```
+
+Теперь нужно указать новое кол-во шардов и задать новое имя очереди:
+
+```ruby
+module ATestWorker
+  extend Lowkiq::Worker
+
+  self.shards_count = 10
+  self.queue_name = "#{self.name}_V2"
+
+  def self.perform(payloads_by_id)
+    some_code
+  end
+end
+```
+
+И добавить воркер, перекладывающий задачи из старой очереди в новую:
+
+```ruby
+module ATestMigrationWorker
+  extend Lowkiq::Worker
+
+  self.shards_count = 5
+  self.queue_name = "ATestWorker"
+
+  def self.perform(payloads_by_id)
+    jobs = payloads_by_id.each_with_object([]) do |(id, payloads), acc|
+      payloads.each do |payload|
+        acc << { id: id, payload: payload }
+      end
+    end
+
+    ATestWorker.perform_async jobs
+  end
+end
+```
+
+## Запуск
+
+`lowkiq -r ./path_to_app`
+
+`path_to_app.rb` должен загрузить приложение.
+Ленивая загрузка модулей воркеров недопустима.
+
+Redis версии >= 3.2.
+
+## Остановка
+
+Послать процессу TERM или INT(Ctrl-C).
+Процесс будет ждать завершения всех задач.
+Обратите внимание, если очередь пуста, то на время завершения влияет величина `poll_interval`.
+
+## Development
+
+```
+docker-compose run --rm --service-port app bash
+bundler
+rspec
+cd examples/dummy ; bundle exec ../../exe/lowkiq -r ./lib/app.rb
+```
+
+## Debug
+
+Получить trace всех тредов приложения:
+
+```
+kill -TTIN <pid>
+cat /tmp/lowkiq_ttin.txt
+```
+
+## Rails integration
+
+```ruby
+# config/routes.rb
+
+Rails.application.routes.draw do
+ # ...
+ mount Lowkiq::Web => '/lowkiq'
+ # ...
+end
+```
+
+```ruby
+# config/initializers/lowkiq.rb
+
+# загружаем все lowkiq воркеры
+Dir["#{Rails.root}/app/lowkiq_workers/**/*.rb"].each { |file| require_dependency file }
+
+# конфигурация:
+# Lowkiq.redis = -> { Redis.new url: ENV.fetch('LOWKIQ_REDIS_URL') }
+# Lowkiq.threads_per_node = ENV.fetch('LOWKIQ_THREADS_PER_NODE').to_i
+# Lowkiq.client_pool_size = ENV.fetch('LOWKIQ_CLIENT_POOL_SIZE').to_i
+# ...
+
+Lowkiq.server_middlewares << -> (worker, batch, &block) do
+  logger = Rails.logger
+  tag = "#{worker}-#{Thread.current.object_id}"
+
+  logger.tagged(tag) do
+    time_start = Time.now
+    logger.info "#{time_start} Started job, batch: #{batch}"
+    begin
+      block.call
+    rescue => e
+      logger.error e.message
+      raise e
+    ensure
+      time_end = Time.now
+      logger.info "#{time_end} Finished job, duration: #{time_end - time_start} sec"
+    end
+  end
+end
+
+# Sentry integration
+Lowkiq.server_middlewares << -> (worker, batch, &block) do
+  opts = {
+    extra: {
+      lowkiq: {
+        worker: worker.name,
+        batch: batch,
+      }
+    }
+  }
+
+  Raven.capture opts do
+    block.call
+  end
+end
+
+# NewRelic integration
+if defined? NewRelic
+  class NewRelicLowkiqMiddleware
+    include NewRelic::Agent::Instrumentation::ControllerInstrumentation
+
+    def call(worker, batch, &block)
+      opts = {
+        category: 'OtherTransaction/LowkiqJob',
+        class_name: worker.name,
+        name: :perform,
+      }
+
+      perform_action_with_newrelic_trace opts do
+        block.call
+      end
+    end
+  end
+
+  Lowkiq.server_middlewares << NewRelicLowkiqMiddleware.new
+end
+
+# Rails reloader, в том числе отвечает за высвобождение ActiveRecord коннектов
+Lowkiq.server_middlewares << -> (worker, batch, &block) do
+  Rails.application.reloader.wrap do
+    block.call
+  end
+end
+
+Lowkiq.on_server_init = ->() do
+  [[ActiveRecord::Base, ActiveRecord::Base.configurations[Rails.env]]].each do |(klass, init_config)|
+    klass.connection_pool.disconnect!
+    config = init_config.merge 'pool' => Lowkiq.threads_per_node
+    klass.establish_connection(config)
+  end
+end
+```
+
+Запуск: `bundle exec lowkiq -r ./config/environment.rb`