best practices docs

c9076e553518069bcce72a6c3daa17b322f8614c
yandex · Mar 15, 2024 · a6530df · a6530df
1 parent 7642d2d
commit a6530df
Show file tree

Hide file tree

Showing 16 changed files with 222 additions and 42 deletions.
diff --git a/.mapping.json b/.mapping.json
@@ -249,6 +249,7 @@
   "debian/rules":"load/projects/pandora/debian/rules",
   "debian/source/format":"load/projects/pandora/debian/source/format",
   "docs/eng/architecture.md":"load/projects/pandora/docs/eng/architecture.md",
+  "docs/eng/best_practices/rps_per_instance.md":"load/projects/pandora/docs/eng/best_practices/rps_per_instance.md",
   "docs/eng/config.md":"load/projects/pandora/docs/eng/config.md",
   "docs/eng/custom.md":"load/projects/pandora/docs/eng/custom.md",
   "docs/eng/grpc-generator.md":"load/projects/pandora/docs/eng/grpc-generator.md",
@@ -273,6 +274,8 @@
   "docs/images/scn_cases.png":"load/projects/pandora/docs/images/scn_cases.png",
   "docs/index.md":"load/projects/pandora/docs/index.md",
   "docs/rus/architecture.md":"load/projects/pandora/docs/rus/architecture.md",
+  "docs/rus/best_practices.md":"load/projects/pandora/docs/rus/best_practices.md",
+  "docs/rus/best_practices/rps_per_instance.md":"load/projects/pandora/docs/rus/best_practices/rps_per_instance.md",
   "docs/rus/config.md":"load/projects/pandora/docs/rus/config.md",
   "docs/rus/custom.md":"load/projects/pandora/docs/rus/custom.md",
   "docs/rus/grpc-generator.md":"load/projects/pandora/docs/rus/grpc-generator.md",

diff --git a/docs/eng/best_practices/rps_per_instance.md b/docs/eng/best_practices/rps_per_instance.md
@@ -0,0 +1,40 @@
+# RPS per instance
+
+Usually in tests, when we increase the speed of requests submitted to the target service by specifying the `line`, `const`, `step` scheme in the rps section,
+then in the `startup` section we specify the `once` scheme, because we want all instances to be available from the very beginning of the test in order to generate the load we need.
+
+In tests with scenario load, when we have each instance describing virtual user behavior, then in the `startup` section we can specify a smooth growth of the number of users, for example, with the scheme `instance_step`, increasing their number step by step, or `const`, increasing the number of users at a constant rate.
+The `rps-per-instance` instance pool setting can be used for this purpose. It is useful for the script generator when we want to limit the speed of each user in rps.
+
+For example we specify `const` and enable `rps-per-instance`, then by increasing users via `instance_step` we simulate the real user load.
+
+
+Example:
+
+```yaml
+pools:
+  - id: "scenario"
+    ammo:
+      type: http/scenario
+      file: http_payload.hcl
+    result:
+      type: discard
+    gun:
+      target: localhost:443
+      type: http/scenario
+      answlog:
+        enabled: false
+    rps-per-instance: true
+    rps:
+      - type: const
+        duration: 1m
+        ops: 4
+    startup:
+      type: instance_step
+      from: 10
+      to: 100
+      step: 10
+      stepduration: 10s
+log:
+  level: error
+```
diff --git a/docs/eng/config.md b/docs/eng/config.md
@@ -26,6 +26,8 @@ pools:
       type: phout                    # report format (phout is compatible with Yandex.Tank)
       destination: ./phout.log       # report file name
 
+    rps-per-instance: false          # rps section is counted for each instance or for the whole test. false - for the whole test
+
     rps:                             # shooting schedule
       type: line                     # linear growth
       from: 1                        # from 1 response per second

diff --git a/docs/eng/load-profile.md b/docs/eng/load-profile.md
@@ -6,24 +6,36 @@
 
 To determine what load to create on the server, use a load profile. It sets how the load will be changed and maintained.
 
-## line
+## const
 
-Linearly increases the load in a given range over a certain period of time.
+Maintains the specified load for a certain time.
 
 Example:
 
-```
-{duration: 180s, type: line, from: 1, to: 10000} # the load increases from 1 to 10000 requests per second over 180 seconds
+generates 10000 requests per second for 300 seconds
+
+```yaml
+rps:
+    type: const
+    duration: 300s
+    from: 1
+    ops: 10000
 ```
 
-## const
+## line
 
-Maintains the specified load for a certain time.
+Linearly increases the load in a given range over a certain period of time.
 
 Example:
 
-```
-{duration: 300s, type: const, ops: 10000} # generates 10000 requests per second for 300 seconds
+the load increases from 1 to 10000 requests per second over 180 seconds
+
+```yaml
+rps:
+    type: line
+    duration: 180s
+    from: 1
+    to: 10000
 ```
 
 ## step
@@ -32,8 +44,15 @@ Increases the load with the specified increment size from one value to another f
 
 Example:
 
-```
-{duration: 30s, type: step, from: 10, to: 100, step: 5} # the load increases from 10 to 100 requests per second in increments of 5 and with a step duration of 30 seconds
+the load increases from 10 to 100 requests per second in increments of 5 and with a step duration of 30 seconds
+
+```yaml
+rps:
+    type: step
+    duration: 30s
+    from: 10
+    to: 100
+    step: 5
 ```
 
 ## once
@@ -42,8 +61,12 @@ Sends the specified number of requests once and completes the test. There are no
 
 Example:
 
-```
-{type: once, times: 133} # sends 133 requests at the start of this test section and completes the test
+sends 133 requests at the start of this test section and completes the test
+
+```yaml
+rps:
+    type: once
+    times: 133
 ```
 
 ## unlimited
@@ -52,8 +75,12 @@ Sends as many requests as the target can accept within the established connectio
 
 Example:
 
-```
-{type: unlimited, duration: 30s} # unlimited load for 30 seconds
+unlimited load for 30 seconds
+
+```yaml
+rps:
+    type: unlimited
+    duration: 30s
 ```
 
 ---

diff --git a/docs/eng/scenario-grpc-generator.md b/docs/eng/scenario-grpc-generator.md
@@ -21,6 +21,7 @@
             - [assert/response](#assertresponse)
     - [Scenarios](#scenarios)
     - [Sources](#sources)
+- [References](#references)
 
 ## Configuration
 
@@ -284,6 +285,12 @@ More - [scenario in HTTP generator](./scenario-http-generator.md#scenarios)
 
 Follow - [Variable sources](scenario/variable_source.md)
 
+# References
+
+- [HTTP generator](http-generator.md)
+- Best practices
+    - [RPS per instance](best_practices/rps-per-instance.md)
+
 ---
 
 [Home](../index.md)
diff --git a/docs/eng/scenario-http-generator.md b/docs/eng/scenario-http-generator.md
@@ -23,6 +23,7 @@
             - [assert/response](#assertresponse)
     - [Scenarios](#scenarios)
     - [Sources](#sources)
+- [References](#references)
 
 ## Configuration
 
@@ -403,6 +404,12 @@ scenario "scenario_second" {
 
 Follow - [Variable sources](scenario/variable_source.md)
 
+# References
+
+- [HTTP generator](http-generator.md)
+- Best practices
+    - [RPS per instance](best_practices/rps-per-instance.md)
+
 ---
 
 [Home](../index.md)
diff --git a/docs/eng/startup.md b/docs/eng/startup.md
@@ -6,6 +6,8 @@
 
 You can control the profile of instance starts.
 
+This section can be thought of as how many instances you need, and how quickly they will be available to you.
+
 Types of Instance startup profile:
 
 - [once](#once)

diff --git a/docs/index.md b/docs/index.md
@@ -16,6 +16,7 @@ write your own load scenarios in Go, compiling them just before your test.
 - [gRPC generators](eng/grpc-generator.md)
 - [Scenario generator / gRPC](eng/scenario-grpc-generator.md)
 - [Custom guns](eng/custom.md)
+- [Best practices](eng/best_practices.md)
 - [Pandora’s performance](eng/performance.md)
 - [Architectural overview](eng/architecture.md)
 

diff --git a/docs/rus/best_practices.md b/docs/rus/best_practices.md
@@ -0,0 +1,3 @@
+# Практики использования
+
+- [RPS per instance](./best_practices/rps_per_instance.md)
diff --git a/docs/rus/best_practices/rps_per_instance.md b/docs/rus/best_practices/rps_per_instance.md
@@ -0,0 +1,39 @@
+# RPS на инстанс
+
+Обычно в тестах, когда мы увеличиваем скорость запросов, подаваемых на тестируемый севис, указывая схему `line`, `const`, `step` в секции rps,
+то в секции `startup` мы указываем схему `once`, т.к. хотим, чтобы с самого начала теста нам были доступны все инстансы для того, чтобы сгенерить нужную нам нагрузку.
+
+В тестах со сценарной нагрузкой, когда у нас каждый инстанс описыает поведение пользователя, то в секции `startup` можно указывать плавный рост количества пользователей, например схемой `instance_step`, увеличивая ступенчато их кол-во, или `const`, увеличивая пользователей с постоянной скоростью.
+Для этого можно использовать настройку пула инстансов `rps-per-instance`. Она полезна для сценарного генератора, когда мы хотим ограничить скорость каждого пользователя в rps.
+
+Например укажем `const` и включим `rps-per-instance`, то потом увеличивая пользователей через `instance_step`, мы имитируем реальную пользовательскую нагрузку.
+
+Пример:
+
+```yaml
+pools:
+  - id: "scenario"
+    ammo:
+      type: http/scenario
+      file: http_payload.hcl
+    result:
+      type: discard
+    gun:
+      target: localhost:443
+      type: http/scenario
+      answlog:
+        enabled: false
+    rps-per-instance: true
+    rps:
+      - type: const
+        duration: 1m
+        ops: 4
+    startup:
+      type: instance_step
+      from: 10
+      to: 100
+      step: 10
+      stepduration: 10s
+log:
+  level: error
+```
diff --git a/docs/rus/config.md b/docs/rus/config.md
@@ -15,26 +15,28 @@ Pandora поддерживает файлы конфигурации в форм
 
 ```yaml
 pools:
-  - id: HTTP pool                    # pool name (for your choice)
+  - id: HTTP pool                    # идентификатор инстанс пула
     gun:
-      type: http                     # gun type
-      target: example.com:80         # gun target
+      type: http                     # тип генератора
+      target: example.com:80         # ... далее идут настройки генератора. Зависят от его типа
     ammo:
-      type: uri                      # ammo format
-      file: ./ammo.uri               # ammo File
+      type: uri                      # тип провайдера
+      file: ./ammo.uri               # ... далее идут настройки провайдера. Зависят от его типа
     result:
-      type: phout                    # report format (phout is compatible with Yandex.Tank)
+      type: phout                    # тип агрегатора (phout - совместим Yandex.Tank)
       destination: ./phout.log       # report file name
 
-    rps:                             # shooting schedule
-      type: line                     # linear growth
-      from: 1                        # from 1 response per second
-      to: 5                          # to 5 responses per second
-      duration: 60s                  # for 60 seconds
+    rps-per-instance: false          # секция rps считается для каждого инстанса или для всего теста. false - для всего теста
 
-    startup:                         # instances startup schedule
-      type: once                     # start 10 instances
-      times: 10
+    rps:                             # планировщик нагрузки
+      type: line                     # тип планировщика
+      from: 1                        # ... далее идут настройки планировщика. Зависят от его типа
+      to: 5
+      duration: 60s
+
+    startup:                         # запуск инстансов
+      type: once                     # тип профиля запуска инстансов
+      times: 10                      # ... далее идут настройки планировщика. Зависят от его типа
 ```
 
 ## Мониторинг и логирование

diff --git a/docs/rus/index.md b/docs/rus/index.md
@@ -15,6 +15,7 @@ Pandora - это высокопроизводительный генератор
 - [gRPC генератор](grpc-generator.md)
 - [Сценарный генератор / gRPC](scenario-grpc-generator.md)
 - [Custom](custom.md)
+- [Практики использования](best_practices.md)
 - [Производительность Pandora](performance.md)
 - [Архитектура](architecture.md)