github.com/square/finch@v0.0.0-20240412205204-6530c03e2b96/docs/content/syntax/stage-file.md (about)

     1  ---
     2  weight: 1
     3  ---
     4  
     5  Stage files are YAML format.
     6  This is a quick reference with fake but syntactically valid values:
     7  
     8  ```yaml
     9  stage:
    10    disable: false
    11    name: "read-only"
    12    qps: "1,000"
    13    runtime: "60s"
    14    tps: "500"
    15    
    16    compute:
    17      disable-local: false
    18      instances: 0
    19  
    20    mysql:
    21      # Override mysql from _all.yaml
    22  
    23    params:
    24      # Override params from _all.yaml
    25  
    26    stats:
    27      # Override stats from _all.yaml
    28  
    29    trx:
    30      - name: "foo" ##########
    31        file: "trx/foo.sql"  #
    32        data:                #
    33          d:                 #
    34            generator: "int" #
    35                             #
    36    workload:                #
    37      - trx: ["foo"] #########
    38        clients: 1
    39        db: ""
    40        iter: "0"
    41        iter-clients: "0"
    42        iter-exec-group: "0"
    43        qps: "0"
    44        qps-clients: "0"
    45        qps-exec-group: "0"
    46        runtime: "0s"
    47        tps: "0"
    48        tps-clients: "0"
    49        tps-exec-group: "0"
    50  ```
    51  
    52  {{< toc >}}
    53  
    54  ## stage
    55  
    56  A stage file starts with a top-level `stage:` declaration.
    57  
    58  ### disable
    59  
    60  * Default: false
    61  * Value: boolean
    62  
    63  Disable the stage entirely if true.
    64  
    65  ### name
    66  
    67  * Default: base file name
    68  * Value: string
    69  
    70  The stage name.
    71  
    72  ### qps
    73  
    74  * Default: 0 (unlimited)
    75  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 0
    76  
    77  Queries per second (QPS) limit for all clients, all execution groups.
    78  
    79  ### runtime
    80  
    81  * Default: 0 (unlimited)
    82  * Value: [time duration]({{< relref "syntax/values#time-duration" >}}) &ge; 0
    83  
    84  How long to run the stage.
    85  If zero and there are no [data limits]({{< relref "data/limits" >}}), use CTRL-C to stop the stage and report stats.
    86  
    87  ### tps
    88  
    89  * Default: 0 (unlimited)
    90  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 0
    91  
    92  Transaction per second (TPS) limit for all clients, all execution groups.
    93  
    94  ---
    95  
    96  ## compute
    97  
    98  ### disable-local
    99  
   100  * Default: false
   101  * Value: boolean
   102  
   103  If true, the local Finch instances does not count as 1 compute.
   104  
   105  ### instances
   106  
   107  * Default: 1
   108  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 0
   109  
   110  The number of compute instances that Finch requires to run the benchmark.
   111  
   112  ---
   113  
   114  ## mysql
   115  
   116  See [`mysql` in _all.yaml_]({{< relref "syntax/all-file#mysql" >}}).
   117  
   118  ---
   119  
   120  ## params
   121  
   122  See [`params` in _all.yaml_]({{< relref "syntax/all-file#params" >}}).
   123  
   124  ---
   125  
   126  ## stats
   127  
   128  See [`stats` in _all.yaml_]({{< relref "syntax/all-file#stats" >}}).
   129  
   130  
   131  ---
   132  
   133  ## trx
   134  
   135  The `trx` section is a required _list_ of Finch [trx files]({{< relref "syntax/trx-file" >}}) to load.
   136  
   137  ```yaml
   138  stage:
   139    trx:
   140      - file: trx/A.sql
   141        name: foo
   142  
   143      - file: trx/B.sql
   144        # name defaults to B.sql
   145  ```
   146  
   147  ### file
   148  
   149  * Default: (none; must be set explicitly)
   150  * Value: file name
   151  
   152  Sets one Finch trx file to load.
   153  Paths are relative to the directory of the stage file.
   154  
   155  ### data
   156  
   157  * Default: (none; must be set explicitly)
   158  * Value: map keyed on data key name without `@` prefix
   159  
   160  Every [data key]({{< relref "data/keys" >}}) in a trx file must be defined in the stage file.
   161  
   162  ```yaml
   163  stage:
   164    trx:
   165      - file: foo.sql         # uses @d
   166        data:
   167          d:                  # key for @d
   168            generator: "int"  # __REQUIRED__
   169            scope: "trx"      # optional
   170            params:           # generator-specific
   171              max: "10,000"   #
   172  ```
   173  
   174  Only `generator` is required, but you usually need to specify `params` too.
   175  
   176  {{< hint type=note >}}
   177  Only @d ("d" in the stage file) is shown here, but every data key in a trx file must be defined in the `data` map.
   178  {{< /hint >}}
   179  
   180  #### d.data-type
   181  
   182  * Default: "n"
   183  * Value: "n" or "s"
   184  
   185  Indicates column type: "n" for a numeric value, or "s" for a string (quoted) value.
   186  
   187  #### d.generator
   188  
   189  * Default: (none; must be set explicitly)
   190  * Type: name of [data generator]({{< relref "data/generators" >}})
   191  
   192  Name of the data generator to use for the data key.
   193  
   194  #### d.params
   195  
   196  * Default: (none)
   197  * Value: key-value map of strings
   198  
   199  Generator-specific params.
   200  These are optional but usually needed.
   201  See [Data / Generators]({{< relref "data/generators" >}})
   202  
   203  #### d.scope
   204  
   205  * Default: statement
   206  * Value: "" or "statement", "trx", "client"
   207  
   208  Scope of data generator.
   209  If not specified (empty string), the default is "statement".
   210  See [Data / Scope]({{< relref "data/scope" >}}).
   211  
   212  ### name
   213  
   214  * Default: Base file name
   215  * Value: any string
   216  
   217  Set trx name used in [`workload.trx`](#trx-1) list.
   218  
   219  ## workload
   220  
   221  The `workload` section declares the [workload]({{< relref "benchmark/workload" >}}) that references the [`trx`](#trx) section.
   222  
   223  ### clients
   224  
   225  * Default: 1
   226  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 1
   227  
   228  Number of clients to run in client group.
   229  
   230  ### db
   231  
   232  * Default: (none)
   233  * Value: database name
   234  
   235  Deafult client group database.
   236  See [Operate / MySQL / Default Database]({{< relref "operate/mysql#default-database" >}})
   237  Makes clients in client group execute `USE db` on prepare.
   238  
   239  ### iter
   240  
   241  ### iter-clients
   242  
   243  ### iter-exec-group
   244  
   245  * Default: 0 (unlimited)
   246  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 1
   247  
   248  Maximum number of iterations to execute per client, client group, or execution group (respectively).
   249  
   250  ### qps
   251  
   252  ### qps-clients
   253  
   254  ### qps-exec-group
   255  
   256  * Default: 0 (unlimited)
   257  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 1
   258  
   259  Maximum rate of queries per second (QPS) per client, client group, or execution group (respectively).
   260  
   261  ### runtime
   262  
   263  * Default: 0 (forever)
   264  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 1
   265  
   266  Runtime limit
   267  
   268  ### tps
   269  
   270  ### tps-clients
   271  
   272  ### tps-exec-group
   273  
   274  * Default: 0 (unlimited)
   275  * Value: [string-int]({{< relref "syntax/values#string-int" >}}) &ge; 1
   276  
   277  Maximum rate of transaction per second (TPS) per client, client group, or execution group (respectively).
   278  
   279  ### trx
   280  
   281  * Default: none or auto
   282  * Value: list of [`trx.name`](#name-1)
   283  
   284  Trx assigned to all clients to execute.