| .. _admin-plugins-generator: |
| |
| Generator Plugin |
| **************** |
| |
| .. Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| The `Generator` allows testing of synthetic workloads by generating |
| HTTP responses of various sizes and receiving POST bodies. The size |
| and cacheability of the response is specified by the first two components |
| of the requested URL path. This plugin supports the ``GET``, ``HEAD``, |
| and ``POST`` HTTP methods. |
| |
| +---------------+----------------------------------------------------------------+ |
| |Path component | Description | |
| +===============+================================================================+ |
| |1 | ``cache`` or ``nocache``. If ``cache`` is specified, the | |
| | | `Generator` plugin will respond with ``Cache-Control`` headers | |
| | | marking the response as cacheable. | |
| +---------------+----------------------------------------------------------------+ |
| |2 | Integral number of bytes to return in the response. | |
| +---------------+----------------------------------------------------------------+ |
| |
| Path components after the first 2 are ignored. This means that the |
| trailing path components can be manipulated to create unique URLs |
| following any convenient convention. |
| |
| The `Generator` plugin inspects the following HTTP client request headers: |
| |
| +-----------------------+--------------------------------------------------------+ |
| |Header | Description | |
| +=======================+========================================================+ |
| | ``Generator-Delay`` | The number of milliseconds to wait before sending a | |
| | | response. The default is to not wait. | |
| +-----------------------+--------------------------------------------------------+ |
| | ``Generator-MaxAge`` | The number of seconds that a response should be cached | |
| | | for. This is used in the ``max-age`` field of the | |
| | | response's ``Cache-Control`` header. | |
| +-----------------------+--------------------------------------------------------+ |
| |
| The `Generator` plugin publishes the following metrics: |
| |
| generator.response_bytes: |
| The total number of bytes emitted |
| generator.response_count: |
| The number of HTTP responses generated by the plugin |
| |
| Examples: |
| --------- |
| |
| The most common way to use the `Generator` plugin is to configure |
| it as a remap plugin in :file:`remap.config`:: |
| |
| map http://workload.example.com/ http://127.0.0.1/ \ |
| @plugin=generator.so |
| |
| Notice that although the remap target is never contacted because |
| the `Generator` plugin intercepts the request and acts as the origin |
| server, it must be syntactically valid and resolvable in DNS. |
| |
| A 10 byte, cacheable object can then be generated:: |
| |
| $ curl -o /dev/null -x 127.0.0.1:8080 http://workload.example.com/cache/10/caf1fc92332b3a3c8cb8b3826b6a1658 |
| |
| The `Generator` plugin can return responses as large as you like:: |
| |
| $ curl -o /dev/null -x 127.0.0.1:8080 http://workload.example.com/cache/$((10 * 1024 * 1024))/$RANDOM |
| |
| The `Generator` plugin can also receive POST requests:: |
| |
| $ curl -o /dev/null -x 127.0.0.1:8080 -d @/etc/hosts http://workload.example.com/ |
