From 77ef492b567f3d5fbfab46c5b374148cc0a6c9a3 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Thu, 23 Sep 2021 14:55:49 +0530 Subject: [PATCH 1/7] add Nighthawk build and usage docs Signed-off-by: Navendu Pottekkat --- docs/_data/docs.yml | 6 +- docs/_data/footer.yml | 2 +- docs/collections/_docs/building-nighthawk.md | 398 ++++++++++++++++++ docs/collections/_docs/section2.md | 7 - docs/collections/_docs/using-getnighthawk.md | 6 - .../collections/_docs/what-is-getnighthawk.md | 19 + ...g-getnighthawk.md => what-is-nighthawk.md} | 4 +- 7 files changed, 423 insertions(+), 19 deletions(-) create mode 100644 docs/collections/_docs/building-nighthawk.md delete mode 100644 docs/collections/_docs/section2.md delete mode 100644 docs/collections/_docs/using-getnighthawk.md create mode 100644 docs/collections/_docs/what-is-getnighthawk.md rename docs/collections/_docs/{really-using-getnighthawk.md => what-is-nighthawk.md} (99%) diff --git a/docs/_data/docs.yml b/docs/_data/docs.yml index 21434114..dd0918db 100644 --- a/docs/_data/docs.yml +++ b/docs/_data/docs.yml @@ -1,6 +1,6 @@ -- name: Section 1 +- name: Overview number: One -- name: Section 2 +- name: Getting Started number: Two -- name: Section 3 +- name: Performance Benchmarking with Nighthawk number: Three \ No newline at end of file diff --git a/docs/_data/footer.yml b/docs/_data/footer.yml index e90e3f95..c43b2d7a 100644 --- a/docs/_data/footer.yml +++ b/docs/_data/footer.yml @@ -3,7 +3,7 @@ - name: Features link: /features - name: Run GetNighthawk - link: /docs/really-using-getnighthawk + link: /docs/what-is-getnighthawk new_window: false - name: Docs link: /docs diff --git a/docs/collections/_docs/building-nighthawk.md b/docs/collections/_docs/building-nighthawk.md new file mode 100644 index 00000000..1275660f --- /dev/null +++ b/docs/collections/_docs/building-nighthawk.md @@ -0,0 +1,398 @@ +--- +layout: docs +title: Building and Using Nighthawk +section: "Getting Started" +--- + +# Building Nighthawk + +Although GetNighthawk would provide all of the features available in Nighthawk, you can also build Nighthawk and run it from source. + +## Clone the Nighthawk repo + +Using GitHub CLI: + +``` +gh repo clone envoyproxy/nighthawk +``` + +Using HTTPS: + +``` +git clone https://github.com/envoyproxy/nighthawk.git +``` + +## Install Dependencies + +On Ubuntu, run the following: + +```console +sudo apt-get install \ + autoconf \ + automake \ + cmake \ + curl \ + libtool \ + make \ + ninja-build \ + patch \ + python3-pip \ + unzip \ + virtualenv +``` + +Install [Golang](https://golang.org/) on your machine. This is required as part of building [BoringSSL](https://boringssl.googlesource.com/boringssl/+/HEAD/BUILDING.md) and also for [Buildifer](https://github.com/bazelbuild/buildtools) which is used for formatting bazel BUILD files. + +## Building Nighthawk + +Run: + +``` +bazel build -c opt //:nighthawk +``` + +# Using the Nighthawk CLI + +``` +bazel-bin/nighthawk_client --help +``` + +``` +USAGE: + +bazel-bin/nighthawk_client [--latency-response-header-name ] +[--stats-flush-interval ] +[--stats-sinks ] ... +[--no-duration] [--simple-warmup] +[--request-source-plugin-config ] +[--request-source ] [--label +] ... [--multi-target-use-https] +[--multi-target-path ] +[--multi-target-endpoint ] ... +[--experimental-h2-use-multiple-connections] +[--nighthawk-service ] +[--jitter-uniform ] [--open-loop] +[--experimental-h1-connection-reuse-strategy +] [--failure-predicate ] ... [--termination-predicate +] ... [--trace ] [--sequencer-idle-strategy ] [--max-concurrent-streams +] [--max-requests-per-connection +] [--max-active-requests +] [--max-pending-requests +] [--transport-socket ] +[--tls-context ] +[--request-body-size ] +[--request-header ] ... +[--request-method ] [--address-family +] [--burst-size ] +[--prefetch-connections] [--output-format +] [-v ] +[--concurrency ] [-p ] [--h2] [--timeout ] +[--duration ] [--connections +] [--rps ] [--] +[--version] [-h] + + +Where: + +--latency-response-header-name +Set an optional header name that will be returned in responses, whose +values will be tracked in a latency histogram if set. Can be used in +tandem with the test server's response option +"emit_previous_request_delta_in_response_header" to record elapsed +time between request arrivals. Default: "" + +--stats-flush-interval +Time interval (in seconds) between flushes to configured stats sinks. +Default: 5. + +--stats-sinks (accepted multiple times) +Stats sinks (in json or compact yaml) where Nighthawk metrics will be +flushed. This argument is intended to be specified multiple times. +Example (json): {name:"envoy.stat_sinks.statsd" +,typed_config:{"@type":"type.googleapis.com/envoy.config.metrics.v3.St +atsdSink",tcp_cluster_name:"statsd"}} + +--no-duration +Request infinite execution. Note that the default failure predicates +will still be added. Mutually exclusive with --duration. + +--simple-warmup +Perform a simple single warmup request (per worker) before starting +execution. Note that this will be reflected in the counters that +Nighthawk writes to the output. Default is false. + +--request-source-plugin-config +[Request +Source](https://github.com/envoyproxy/nighthawk/blob/main/docs/root/ov +erview.md#requestsource) plugin configuration in json or compact yaml. +Mutually exclusive with --request-source. Example (json): +{name:"nighthawk.stub-request-source-plugin" +,typed_config:{"@type":"type.googleapis.com/nighthawk.request_source.S +tubPluginConfig",test_value:"3"}} + +--request-source +Remote gRPC source that will deliver to-be-replayed traffic. Each +worker will separately connect to this source. For example +grpc://127.0.0.1:8443/. Mutually exclusive with +--request_source_plugin_config. + +--label (accepted multiple times) +Label. Allows specifying multiple labels which will be persisted in +structured output formats. + +--multi-target-use-https +Use HTTPS to connect to the target endpoints. Otherwise HTTP is used. +Mutually exclusive with providing a URI. + +--multi-target-path +The single absolute path Nighthawk should request from each target +endpoint. Required when using --multi-target-endpoint. Mutually +exclusive with providing a URI. + +--multi-target-endpoint (accepted multiple times) +Target endpoint in the form IPv4:port, [IPv6]:port, or DNS:port. This +argument is intended to be specified multiple times. Nighthawk will +spread traffic across all endpoints with round robin distribution. +Mutually exclusive with providing a URI. + +--experimental-h2-use-multiple-connections +DO NOT USE: This option is deprecated, if this behavior is desired, +set --max-concurrent-streams to one instead. + +--nighthawk-service +Nighthawk service uri. Example: grpc://localhost:8843/. Default is +empty. + +--jitter-uniform +Add uniformly distributed absolute request-release timing jitter. For +example, to add 10 us of jitter, specify .00001s. Default is empty / +no uniform jitter. + +--open-loop +Enable open loop mode. When enabled, the benchmark client will not +provide backpressure when resource limits are hit. + +--experimental-h1-connection-reuse-strategy +Choose picking the most recently used, or least-recently-used +connections for re-use.(default: mru). WARNING: this option is +experimental and may be removed or changed in the future! + +--failure-predicate (accepted multiple times) +Failure predicate. Allows specifying a counter name plus threshold +value for failing execution. Defaults to not tolerating error status +codes and connection errors. + +--termination-predicate (accepted multiple times) +Termination predicate. Allows specifying a counter name plus threshold +value for terminating execution. + +--trace +Trace uri. Example: zipkin://localhost:9411/api/v2/spans. Default is +empty. + +--sequencer-idle-strategy +Choose between using a busy spin/yield loop or have the thread poll or +sleep while waiting for the next scheduled request (default: spin). + +--max-concurrent-streams +Max concurrent streams allowed on one HTTP/2 or HTTP/3 connection. +Does not apply to HTTP/1. (default: 2147483647). + +--max-requests-per-connection +Max requests per connection (default: 4294937295). + +--max-active-requests +The maximum allowed number of concurrently active requests. HTTP/2 +only. (default: 100). + +--max-pending-requests +Max pending requests (default: 0, no client side queuing. Specifying +any other value will allow client-side queuing of requests). + +--transport-socket +Transport socket configuration in json or compact yaml. Mutually +exclusive with --tls-context. Example (json): +{name:"envoy.transport_sockets.tls" +,typed_config:{"@type":"type.googleapis.com/envoy.extensions.transport +_sockets.tls.v3.UpstreamTlsContext" +,common_tls_context:{tls_params:{cipher_suites:["-ALL:ECDHE-RSA-AES128 +-SHA"]}}}} + +--tls-context +DEPRECATED, use --transport-socket instead. Tls context configuration +in json or compact yaml. Mutually exclusive with --transport-socket. +Example (json): +{common_tls_context:{tls_params:{cipher_suites:["-ALL:ECDHE-RSA-AES128 +-SHA"]}}} + +--request-body-size +Size of the request body to send. NH will send a number of consecutive +'a' characters equal to the number specified here. (default: 0, no +data). + +--request-header (accepted multiple times) +Raw request headers in the format of 'name: value' pairs. This +argument may specified multiple times. + +--request-method +Request method used when sending requests. The default is 'GET'. + +--address-family +Network address family preference. Possible values: [auto, v4, v6]. +The default output format is 'AUTO'. + +--burst-size +Release requests in bursts of the specified size (default: 0). + +--prefetch-connections +Use proactive connection prefetching (HTTP/1 only). + +--output-format +Output format. Possible values: {"json", "human", "yaml", "dotted", +"fortio", "experimental_fortio_pedantic"}. The default output format +is 'human'. + +-v , --verbosity +Verbosity of the output. Possible values: [trace, debug, info, warn, +error, critical]. The default level is 'info'. + +--concurrency +The number of concurrent event loops that should be used. Specify +'auto' to let Nighthawk leverage all vCPUs that have affinity to the +Nighthawk process. Note that increasing this results in an effective +load multiplier combined with the configured --rps and --connections +values. Default: 1. + +-p , --protocol +The protocol to encapsulate requests in. Possible values: [http1, +http2, http3]. The default protocol is 'http1' when neither of --h2 or +--protocol is used. Mutually exclusive with --h2. + +--h2 +DEPRECATED, use --protocol instead. Encapsulate requests in HTTP/2. +Mutually exclusive with --protocol. Requests are encapsulated in +HTTP/1 by default when neither of --h2 or --protocol is used. + +--timeout +Connection connect timeout period in seconds. Default: 30. + +--duration +The number of seconds that the test should run. Default: 5. Mutually +exclusive with --no-duration. + +--connections +The maximum allowed number of concurrent connections per event loop. +HTTP/1 only. Default: 100. + +--rps +The target requests-per-second rate. Default: 5. + +--, --ignore_rest +Ignores the rest of the labeled arguments following this flag. + +--version +Displays version information and exits. + +-h, --help +Displays usage information and exits. + + +URI to benchmark. http:// and https:// are supported, but in case of +https no certificates are validated. Provide a URI when you need to +benchmark a single endpoint. For multiple endpoints, set +--multi-target-* instead. + + +L7 (HTTP/HTTPS/HTTP2) performance characterization tool. +``` + +# Using Nighthawk gRPC Service + +The gRPC service can be used to start a server which is able to perform back-to-back benchmark runs upon request. The service interface definition [can be found here](https://github.com/envoyproxy/nighthawk/blob/59a37568783272a6438b5697277d4e56aa16ebbe/api/client/service.proto). + +``` +bazel-bin/nighthawk_service --help +``` + +``` +USAGE: + +bazel-bin/nighthawk_service [--service ] +[--listener-address-file <>] [--listen +] [--] [--version] [-h] + + +Where: + +--service +Specifies which service to run. Default 'traffic-generator-service'. + +--listener-address-file <> +Location where the service will write the final address:port on which +the Nighthawk grpc service listens. Default empty. + +--listen +The address:port on which the Nighthawk gRPC service should listen. +Default: 0.0.0.0:8443. + +--, --ignore_rest +Ignores the rest of the labeled arguments following this flag. + +--version +Displays version information and exits. + +-h, --help +Displays usage information and exits. + + +L7 (HTTP/HTTPS/HTTP2) performance characterization tool. +``` + +# Nighthawk Output Transform Utility + +Nighthawk comes with a tool to transform its json output to its other supported output formats. + +``` +bazel-bin/nighthawk_output_transform --help +``` + +``` +USAGE: + +bazel-bin/nighthawk_output_transform --output-format [--] +[--version] [-h] + + +Where: + +--output-format +(required) Output format. Possible values: {"json", "human", "yaml", +"dotted", "fortio", "experimental_fortio_pedantic"}. + +--, --ignore_rest +Ignores the rest of the labeled arguments following this flag. + +--version +Displays version information and exits. + +-h, --help +Displays usage information and exits. + + +L7 (HTTP/HTTPS/HTTP2) performance characterization transformation tool. +``` + +See [Nighthawk README](https://github.com/envoyproxy/nighthawk) for more info. diff --git a/docs/collections/_docs/section2.md b/docs/collections/_docs/section2.md deleted file mode 100644 index 39c717e3..00000000 --- a/docs/collections/_docs/section2.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: docs -title: Overview -section: "Section 2" ---- - -Test section 2 \ No newline at end of file diff --git a/docs/collections/_docs/using-getnighthawk.md b/docs/collections/_docs/using-getnighthawk.md deleted file mode 100644 index 1f54af60..00000000 --- a/docs/collections/_docs/using-getnighthawk.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: docs -title: GetNighthawk -section: "Section 1" ---- -Test \ No newline at end of file diff --git a/docs/collections/_docs/what-is-getnighthawk.md b/docs/collections/_docs/what-is-getnighthawk.md new file mode 100644 index 00000000..17432540 --- /dev/null +++ b/docs/collections/_docs/what-is-getnighthawk.md @@ -0,0 +1,19 @@ +--- +layout: docs +title: What is GetNighthawk? +section: "Overview" +--- + +# What is GetNighthawk? + +GetNighthawk was built with the goal to make it easy to use Nighthawk. + +As such, GetNighthawk will provide generally available distributions of Nighthawk under different architectures and platforms also providing easy-to-use tooling for installation and operation. This involves creating distributions of Nighthawk and to build up existing tooling. + +The GetNighthawk project also aims to work alongside Meshery and Service Mesh Performance to enable standards-based distributed performance management. This would enable researchers and users to conveniently identify the optimal service mesh configuration while considering their specific environment, application and load. + +To provide this functionality, GetNighthawk will orchestrate multiple instances of Nighthawk (horizontal scaling) and would also provide an easy to use interface for Nighthawk's adaptive load controller capability. + +GetNighthawk also enables Nighthawk adoption by delivering trusted, certified builds, distributed via popular package managers like apt, yum, Homebrew and platforms including Docker and Meshery. GetNighthawk also bridges the gap between C++ code in Nighthawk and the language of the cloud, Golang. + +This would also enable Nighthawk to be the performance characterization tool that would be used in the 30 patterns in the [Service Mesh Patterns](https://layer5.io/books/service-mesh-patterns) book. \ No newline at end of file diff --git a/docs/collections/_docs/really-using-getnighthawk.md b/docs/collections/_docs/what-is-nighthawk.md similarity index 99% rename from docs/collections/_docs/really-using-getnighthawk.md rename to docs/collections/_docs/what-is-nighthawk.md index 9522f9f3..c934ac4f 100644 --- a/docs/collections/_docs/really-using-getnighthawk.md +++ b/docs/collections/_docs/what-is-nighthawk.md @@ -1,7 +1,7 @@ --- layout: docs -title: Overview -section: "Section 1" +title: What is Nighthawk? +section: "Overview" --- # Nighthawk: architecture and key concepts From f4cb940ca2726d4a5cb9456a46af631031ac8c64 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Thu, 23 Sep 2021 18:45:43 +0530 Subject: [PATCH 2/7] add performance testing guide with mesheryctl Signed-off-by: Navendu Pottekkat --- .../_docs/performance-benchmarking.md | 80 +++++++++++++++++++ docs/collections/_docs/section3.md | 7 -- docs/collections/_docs/using-getnighthawk.md | 13 +++ 3 files changed, 93 insertions(+), 7 deletions(-) create mode 100644 docs/collections/_docs/performance-benchmarking.md delete mode 100644 docs/collections/_docs/section3.md create mode 100644 docs/collections/_docs/using-getnighthawk.md diff --git a/docs/collections/_docs/performance-benchmarking.md b/docs/collections/_docs/performance-benchmarking.md new file mode 100644 index 00000000..8cc17f66 --- /dev/null +++ b/docs/collections/_docs/performance-benchmarking.md @@ -0,0 +1,80 @@ +--- +layout: docs +title: Running Performance Tests +section: "Performance Benchmarking with Nighthawk" +--- + +[Meshery](https://meshery.io/) uses Nighthawk as one of its load generators to run performance benchmarking. Meshery is the canonical implementation of [Service Mesh Performance](https://smp-spec.io/), CNCF's service mesh performance benchmarking specification. + +# Performance Benchmarking Using mesheryctl + +mesheryctl is the command line interface of Meshery. + +mesheryctl can use Nighthawk underneath the hood to run performance benchmarks. + +## Install mesheryctl + +Check this [quick start guide](https://meshery.io/#getting-started) on how to install mesheryctl. + +``` +mesheryctl -h +``` + +``` +Meshery is the service mesh management plane, providing lifecycle, performance, and configuration management of service meshes and their workloads. + +Usage: + mesheryctl [command] + +Available Commands: + app Service Mesh Apps Management + completion generate the autocompletion script for the specified shell + exp Experimental commands for mesheryctl + help Help about any command + mesh Service Mesh Lifecycle Management + pattern Service Mesh Patterns Management + perf Performance Management + system Meshery Lifecycle Management + version Version of mesheryctl + +Flags: + --config string path to config file (default "/Users/navendu/.meshery/config.yaml") + -h, --help help for mesheryctl + -v, --verbose verbose output + +Use "mesheryctl [command] --help" for more information about a command. +``` + +## Run a performance test + +See [this guide](https://docs.meshery.io/reference/mesheryctl#service-mesh-performance-management) for reference to mesheryctl commands. + +The command below runs a performance benchmark test with Nighthawk with the test configuration provided through flags. + +``` +mesheryctl perf apply --profile istio-soak-test --concurrent-requests 1 --duration 15s --load-generator nighthawk --mesh istio --url http://localhost:2323 +``` + +You can also run performance tests with SMP compatible test configuration files like the one shown below. + +```yaml +smp_version: v0.0.1 +id: d3ac6bf7-e35e-40c0-8669-5e13c9657286 +name: istio-soak-test +labels: {} +clients: +- internal: false + load_generator: nighthawk + protocol: 1 + connections: 2 + rps: 10 + headers: {} + cookies: {} + body: "" + content_type: "" + endpoint_urls: + - http://localhost:2323 +duration: "15s" +``` + +Check the [Meshery usage guides](https://docs.meshery.io/guides) for more information on running performance benchmarks. diff --git a/docs/collections/_docs/section3.md b/docs/collections/_docs/section3.md deleted file mode 100644 index 91ae7ed7..00000000 --- a/docs/collections/_docs/section3.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: docs -title: Overview -section: "Section 3" ---- - -Test section 3 \ No newline at end of file diff --git a/docs/collections/_docs/using-getnighthawk.md b/docs/collections/_docs/using-getnighthawk.md new file mode 100644 index 00000000..3da68b72 --- /dev/null +++ b/docs/collections/_docs/using-getnighthawk.md @@ -0,0 +1,13 @@ +--- +layout: docs +title: Using GetNighthawk +section: "Getting Started" +--- + +GetNighthawk provides a [Go package](https://github.com/layer5io/getnighthawk/tree/master/pkg/client) which the users can leverage to use Nighthawk. + +GetNighthawk also provides a gRPC Go stub which can be used to interact with a running service. + +[Client and Server binaries](https://github.com/layer5io/getnighthawk/tree/master/apinighthawk/bin) of Nighthawk are also built and ready to be used. + +GetNighthawk also provides a Docker image that can be pulled from here. \ No newline at end of file From 6af01fd367a7db5dfeb75508198164a10d326913 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 23 Sep 2021 09:35:00 -0500 Subject: [PATCH 3/7] Update docs/collections/_docs/building-nighthawk.md --- docs/collections/_docs/building-nighthawk.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/collections/_docs/building-nighthawk.md b/docs/collections/_docs/building-nighthawk.md index 1275660f..867ed3e5 100644 --- a/docs/collections/_docs/building-nighthawk.md +++ b/docs/collections/_docs/building-nighthawk.md @@ -312,7 +312,6 @@ benchmark a single endpoint. For multiple endpoints, set --multi-target-* instead. -L7 (HTTP/HTTPS/HTTP2) performance characterization tool. ``` # Using Nighthawk gRPC Service From c6b5872daa0522184b716932ad4509443e5247e6 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 23 Sep 2021 09:35:05 -0500 Subject: [PATCH 4/7] Update docs/collections/_docs/building-nighthawk.md --- docs/collections/_docs/building-nighthawk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/collections/_docs/building-nighthawk.md b/docs/collections/_docs/building-nighthawk.md index 867ed3e5..1cd2628d 100644 --- a/docs/collections/_docs/building-nighthawk.md +++ b/docs/collections/_docs/building-nighthawk.md @@ -6,7 +6,7 @@ section: "Getting Started" # Building Nighthawk -Although GetNighthawk would provide all of the features available in Nighthawk, you can also build Nighthawk and run it from source. +While GetNighthawk distribution are a convenient way of using Nighthawk, you can also build Nighthawk and run it from source. ## Clone the Nighthawk repo From c7a28c46458a466286aa24952baf3bfe4c527e25 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 23 Sep 2021 09:35:12 -0500 Subject: [PATCH 5/7] Update docs/collections/_docs/performance-benchmarking.md --- docs/collections/_docs/performance-benchmarking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/collections/_docs/performance-benchmarking.md b/docs/collections/_docs/performance-benchmarking.md index 8cc17f66..f6f986d0 100644 --- a/docs/collections/_docs/performance-benchmarking.md +++ b/docs/collections/_docs/performance-benchmarking.md @@ -8,7 +8,7 @@ section: "Performance Benchmarking with Nighthawk" # Performance Benchmarking Using mesheryctl -mesheryctl is the command line interface of Meshery. +
mesheryctl
is the command line interface of Meshery. 
mesheryctl
along with other load generators, 
mesheryctl
can use Nighthawk to run performance benchmarks. mesheryctl can use Nighthawk underneath the hood to run performance benchmarks. From 17edc73bd22e38284b587a9718ee5fd12fa3ede8 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Thu, 23 Sep 2021 09:35:16 -0500 Subject: [PATCH 6/7] Update docs/collections/_docs/performance-benchmarking.md --- docs/collections/_docs/performance-benchmarking.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/collections/_docs/performance-benchmarking.md b/docs/collections/_docs/performance-benchmarking.md index f6f986d0..6918c5c7 100644 --- a/docs/collections/_docs/performance-benchmarking.md +++ b/docs/collections/_docs/performance-benchmarking.md @@ -10,7 +10,6 @@ section: "Performance Benchmarking with Nighthawk" 
mesheryctl
is the command line interface of Meshery. 
mesheryctl
along with other load generators, 
mesheryctl
can use Nighthawk to run performance benchmarks. -mesheryctl can use Nighthawk underneath the hood to run performance benchmarks. ## Install mesheryctl From 981efd61497ef134b4d22e2fdf8a2d2e874ab987 Mon Sep 17 00:00:00 2001 From: Navendu Pottekkat Date: Thu, 23 Sep 2021 21:37:04 +0530 Subject: [PATCH 7/7] update perf command example Signed-off-by: Navendu Pottekkat --- docs/collections/_docs/building-nighthawk.md | 347 +---------------- .../_docs/performance-benchmarking.md | 8 +- docs/collections/_docs/using-nighthawk.md | 350 ++++++++++++++++++ 3 files changed, 358 insertions(+), 347 deletions(-) create mode 100644 docs/collections/_docs/using-nighthawk.md diff --git a/docs/collections/_docs/building-nighthawk.md b/docs/collections/_docs/building-nighthawk.md index 1cd2628d..4a4f878e 100644 --- a/docs/collections/_docs/building-nighthawk.md +++ b/docs/collections/_docs/building-nighthawk.md @@ -1,6 +1,6 @@ --- layout: docs -title: Building and Using Nighthawk +title: Building Nighthawk section: "Getting Started" --- @@ -50,348 +50,3 @@ Run: ``` bazel build -c opt //:nighthawk ``` - -# Using the Nighthawk CLI - -``` -bazel-bin/nighthawk_client --help -``` - -``` -USAGE: - -bazel-bin/nighthawk_client [--latency-response-header-name ] -[--stats-flush-interval ] -[--stats-sinks ] ... -[--no-duration] [--simple-warmup] -[--request-source-plugin-config ] -[--request-source ] [--label -] ... [--multi-target-use-https] -[--multi-target-path ] -[--multi-target-endpoint ] ... -[--experimental-h2-use-multiple-connections] -[--nighthawk-service ] -[--jitter-uniform ] [--open-loop] -[--experimental-h1-connection-reuse-strategy -] [--failure-predicate ] ... [--termination-predicate -] ... [--trace ] [--sequencer-idle-strategy ] [--max-concurrent-streams -] [--max-requests-per-connection -] [--max-active-requests -] [--max-pending-requests -] [--transport-socket ] -[--tls-context ] -[--request-body-size ] -[--request-header ] ... -[--request-method ] [--address-family -] [--burst-size ] -[--prefetch-connections] [--output-format -] [-v ] -[--concurrency ] [-p ] [--h2] [--timeout ] -[--duration ] [--connections -] [--rps ] [--] -[--version] [-h] - - -Where: - ---latency-response-header-name -Set an optional header name that will be returned in responses, whose -values will be tracked in a latency histogram if set. Can be used in -tandem with the test server's response option -"emit_previous_request_delta_in_response_header" to record elapsed -time between request arrivals. Default: "" - ---stats-flush-interval -Time interval (in seconds) between flushes to configured stats sinks. -Default: 5. - ---stats-sinks (accepted multiple times) -Stats sinks (in json or compact yaml) where Nighthawk metrics will be -flushed. This argument is intended to be specified multiple times. -Example (json): {name:"envoy.stat_sinks.statsd" -,typed_config:{"@type":"type.googleapis.com/envoy.config.metrics.v3.St -atsdSink",tcp_cluster_name:"statsd"}} - ---no-duration -Request infinite execution. Note that the default failure predicates -will still be added. Mutually exclusive with --duration. - ---simple-warmup -Perform a simple single warmup request (per worker) before starting -execution. Note that this will be reflected in the counters that -Nighthawk writes to the output. Default is false. - ---request-source-plugin-config -[Request -Source](https://github.com/envoyproxy/nighthawk/blob/main/docs/root/ov -erview.md#requestsource) plugin configuration in json or compact yaml. -Mutually exclusive with --request-source. Example (json): -{name:"nighthawk.stub-request-source-plugin" -,typed_config:{"@type":"type.googleapis.com/nighthawk.request_source.S -tubPluginConfig",test_value:"3"}} - ---request-source -Remote gRPC source that will deliver to-be-replayed traffic. Each -worker will separately connect to this source. For example -grpc://127.0.0.1:8443/. Mutually exclusive with ---request_source_plugin_config. - ---label (accepted multiple times) -Label. Allows specifying multiple labels which will be persisted in -structured output formats. - ---multi-target-use-https -Use HTTPS to connect to the target endpoints. Otherwise HTTP is used. -Mutually exclusive with providing a URI. - ---multi-target-path -The single absolute path Nighthawk should request from each target -endpoint. Required when using --multi-target-endpoint. Mutually -exclusive with providing a URI. - ---multi-target-endpoint (accepted multiple times) -Target endpoint in the form IPv4:port, [IPv6]:port, or DNS:port. This -argument is intended to be specified multiple times. Nighthawk will -spread traffic across all endpoints with round robin distribution. -Mutually exclusive with providing a URI. - ---experimental-h2-use-multiple-connections -DO NOT USE: This option is deprecated, if this behavior is desired, -set --max-concurrent-streams to one instead. - ---nighthawk-service -Nighthawk service uri. Example: grpc://localhost:8843/. Default is -empty. - ---jitter-uniform -Add uniformly distributed absolute request-release timing jitter. For -example, to add 10 us of jitter, specify .00001s. Default is empty / -no uniform jitter. - ---open-loop -Enable open loop mode. When enabled, the benchmark client will not -provide backpressure when resource limits are hit. - ---experimental-h1-connection-reuse-strategy -Choose picking the most recently used, or least-recently-used -connections for re-use.(default: mru). WARNING: this option is -experimental and may be removed or changed in the future! - ---failure-predicate (accepted multiple times) -Failure predicate. Allows specifying a counter name plus threshold -value for failing execution. Defaults to not tolerating error status -codes and connection errors. - ---termination-predicate (accepted multiple times) -Termination predicate. Allows specifying a counter name plus threshold -value for terminating execution. - ---trace -Trace uri. Example: zipkin://localhost:9411/api/v2/spans. Default is -empty. - ---sequencer-idle-strategy -Choose between using a busy spin/yield loop or have the thread poll or -sleep while waiting for the next scheduled request (default: spin). - ---max-concurrent-streams -Max concurrent streams allowed on one HTTP/2 or HTTP/3 connection. -Does not apply to HTTP/1. (default: 2147483647). - ---max-requests-per-connection -Max requests per connection (default: 4294937295). - ---max-active-requests -The maximum allowed number of concurrently active requests. HTTP/2 -only. (default: 100). - ---max-pending-requests -Max pending requests (default: 0, no client side queuing. Specifying -any other value will allow client-side queuing of requests). - ---transport-socket -Transport socket configuration in json or compact yaml. Mutually -exclusive with --tls-context. Example (json): -{name:"envoy.transport_sockets.tls" -,typed_config:{"@type":"type.googleapis.com/envoy.extensions.transport -_sockets.tls.v3.UpstreamTlsContext" -,common_tls_context:{tls_params:{cipher_suites:["-ALL:ECDHE-RSA-AES128 --SHA"]}}}} - ---tls-context -DEPRECATED, use --transport-socket instead. Tls context configuration -in json or compact yaml. Mutually exclusive with --transport-socket. -Example (json): -{common_tls_context:{tls_params:{cipher_suites:["-ALL:ECDHE-RSA-AES128 --SHA"]}}} - ---request-body-size -Size of the request body to send. NH will send a number of consecutive -'a' characters equal to the number specified here. (default: 0, no -data). - ---request-header (accepted multiple times) -Raw request headers in the format of 'name: value' pairs. This -argument may specified multiple times. - ---request-method -Request method used when sending requests. The default is 'GET'. - ---address-family -Network address family preference. Possible values: [auto, v4, v6]. -The default output format is 'AUTO'. - ---burst-size -Release requests in bursts of the specified size (default: 0). - ---prefetch-connections -Use proactive connection prefetching (HTTP/1 only). - ---output-format -Output format. Possible values: {"json", "human", "yaml", "dotted", -"fortio", "experimental_fortio_pedantic"}. The default output format -is 'human'. - --v , --verbosity -Verbosity of the output. Possible values: [trace, debug, info, warn, -error, critical]. The default level is 'info'. - ---concurrency -The number of concurrent event loops that should be used. Specify -'auto' to let Nighthawk leverage all vCPUs that have affinity to the -Nighthawk process. Note that increasing this results in an effective -load multiplier combined with the configured --rps and --connections -values. Default: 1. - --p , --protocol -The protocol to encapsulate requests in. Possible values: [http1, -http2, http3]. The default protocol is 'http1' when neither of --h2 or ---protocol is used. Mutually exclusive with --h2. - ---h2 -DEPRECATED, use --protocol instead. Encapsulate requests in HTTP/2. -Mutually exclusive with --protocol. Requests are encapsulated in -HTTP/1 by default when neither of --h2 or --protocol is used. - ---timeout -Connection connect timeout period in seconds. Default: 30. - ---duration -The number of seconds that the test should run. Default: 5. Mutually -exclusive with --no-duration. - ---connections -The maximum allowed number of concurrent connections per event loop. -HTTP/1 only. Default: 100. - ---rps -The target requests-per-second rate. Default: 5. - ---, --ignore_rest -Ignores the rest of the labeled arguments following this flag. - ---version -Displays version information and exits. - --h, --help -Displays usage information and exits. - - -URI to benchmark. http:// and https:// are supported, but in case of -https no certificates are validated. Provide a URI when you need to -benchmark a single endpoint. For multiple endpoints, set ---multi-target-* instead. - - -``` - -# Using Nighthawk gRPC Service - -The gRPC service can be used to start a server which is able to perform back-to-back benchmark runs upon request. The service interface definition [can be found here](https://github.com/envoyproxy/nighthawk/blob/59a37568783272a6438b5697277d4e56aa16ebbe/api/client/service.proto). - -``` -bazel-bin/nighthawk_service --help -``` - -``` -USAGE: - -bazel-bin/nighthawk_service [--service ] -[--listener-address-file <>] [--listen -] [--] [--version] [-h] - - -Where: - ---service -Specifies which service to run. Default 'traffic-generator-service'. - ---listener-address-file <> -Location where the service will write the final address:port on which -the Nighthawk grpc service listens. Default empty. - ---listen -The address:port on which the Nighthawk gRPC service should listen. -Default: 0.0.0.0:8443. - ---, --ignore_rest -Ignores the rest of the labeled arguments following this flag. - ---version -Displays version information and exits. - --h, --help -Displays usage information and exits. - - -L7 (HTTP/HTTPS/HTTP2) performance characterization tool. -``` - -# Nighthawk Output Transform Utility - -Nighthawk comes with a tool to transform its json output to its other supported output formats. - -``` -bazel-bin/nighthawk_output_transform --help -``` - -``` -USAGE: - -bazel-bin/nighthawk_output_transform --output-format [--] -[--version] [-h] - - -Where: - ---output-format -(required) Output format. Possible values: {"json", "human", "yaml", -"dotted", "fortio", "experimental_fortio_pedantic"}. - ---, --ignore_rest -Ignores the rest of the labeled arguments following this flag. - ---version -Displays version information and exits. - --h, --help -Displays usage information and exits. - - -L7 (HTTP/HTTPS/HTTP2) performance characterization transformation tool. -``` - -See [Nighthawk README](https://github.com/envoyproxy/nighthawk) for more info. diff --git a/docs/collections/_docs/performance-benchmarking.md b/docs/collections/_docs/performance-benchmarking.md index 6918c5c7..ddc98b19 100644 --- a/docs/collections/_docs/performance-benchmarking.md +++ b/docs/collections/_docs/performance-benchmarking.md @@ -8,7 +8,7 @@ section: "Performance Benchmarking with Nighthawk" # Performance Benchmarking Using mesheryctl -
mesheryctl
is the command line interface of Meshery. 
mesheryctl
along with other load generators, 
mesheryctl
can use Nighthawk to run performance benchmarks. +`mesheryctl` is the command line interface of Meshery. `mesheryctl` along with other load generators, `mesheryctl` can use Nighthawk to run performance benchmarks. ## Install mesheryctl @@ -76,4 +76,10 @@ clients: duration: "15s" ``` +You can then use `mesheryctl` to run the test using this configuration file as shown below. + +``` +mesheryctl perf apply -f perf-test.yaml +``` + Check the [Meshery usage guides](https://docs.meshery.io/guides) for more information on running performance benchmarks. diff --git a/docs/collections/_docs/using-nighthawk.md b/docs/collections/_docs/using-nighthawk.md new file mode 100644 index 00000000..4a5253fe --- /dev/null +++ b/docs/collections/_docs/using-nighthawk.md @@ -0,0 +1,350 @@ +--- +layout: docs +title: Using Nighthawk +section: "Getting Started" +--- + +# Using the Nighthawk CLI + +``` +bazel-bin/nighthawk_client --help +``` + +``` +USAGE: + +bazel-bin/nighthawk_client [--latency-response-header-name ] +[--stats-flush-interval ] +[--stats-sinks ] ... +[--no-duration] [--simple-warmup] +[--request-source-plugin-config ] +[--request-source ] [--label +] ... [--multi-target-use-https] +[--multi-target-path ] +[--multi-target-endpoint ] ... +[--experimental-h2-use-multiple-connections] +[--nighthawk-service ] +[--jitter-uniform ] [--open-loop] +[--experimental-h1-connection-reuse-strategy +] [--failure-predicate ] ... [--termination-predicate +] ... [--trace ] [--sequencer-idle-strategy ] [--max-concurrent-streams +] [--max-requests-per-connection +] [--max-active-requests +] [--max-pending-requests +] [--transport-socket ] +[--tls-context ] +[--request-body-size ] +[--request-header ] ... +[--request-method ] [--address-family +] [--burst-size ] +[--prefetch-connections] [--output-format +] [-v ] +[--concurrency ] [-p ] [--h2] [--timeout ] +[--duration ] [--connections +] [--rps ] [--] +[--version] [-h] + + +Where: + +--latency-response-header-name +Set an optional header name that will be returned in responses, whose +values will be tracked in a latency histogram if set. Can be used in +tandem with the test server's response option +"emit_previous_request_delta_in_response_header" to record elapsed +time between request arrivals. Default: "" + +--stats-flush-interval +Time interval (in seconds) between flushes to configured stats sinks. +Default: 5. + +--stats-sinks (accepted multiple times) +Stats sinks (in json or compact yaml) where Nighthawk metrics will be +flushed. This argument is intended to be specified multiple times. +Example (json): {name:"envoy.stat_sinks.statsd" +,typed_config:{"@type":"type.googleapis.com/envoy.config.metrics.v3.St +atsdSink",tcp_cluster_name:"statsd"}} + +--no-duration +Request infinite execution. Note that the default failure predicates +will still be added. Mutually exclusive with --duration. + +--simple-warmup +Perform a simple single warmup request (per worker) before starting +execution. Note that this will be reflected in the counters that +Nighthawk writes to the output. Default is false. + +--request-source-plugin-config +[Request +Source](https://github.com/envoyproxy/nighthawk/blob/main/docs/root/ov +erview.md#requestsource) plugin configuration in json or compact yaml. +Mutually exclusive with --request-source. Example (json): +{name:"nighthawk.stub-request-source-plugin" +,typed_config:{"@type":"type.googleapis.com/nighthawk.request_source.S +tubPluginConfig",test_value:"3"}} + +--request-source +Remote gRPC source that will deliver to-be-replayed traffic. Each +worker will separately connect to this source. For example +grpc://127.0.0.1:8443/. Mutually exclusive with +--request_source_plugin_config. + +--label (accepted multiple times) +Label. Allows specifying multiple labels which will be persisted in +structured output formats. + +--multi-target-use-https +Use HTTPS to connect to the target endpoints. Otherwise HTTP is used. +Mutually exclusive with providing a URI. + +--multi-target-path +The single absolute path Nighthawk should request from each target +endpoint. Required when using --multi-target-endpoint. Mutually +exclusive with providing a URI. + +--multi-target-endpoint (accepted multiple times) +Target endpoint in the form IPv4:port, [IPv6]:port, or DNS:port. This +argument is intended to be specified multiple times. Nighthawk will +spread traffic across all endpoints with round robin distribution. +Mutually exclusive with providing a URI. + +--experimental-h2-use-multiple-connections +DO NOT USE: This option is deprecated, if this behavior is desired, +set --max-concurrent-streams to one instead. + +--nighthawk-service +Nighthawk service uri. Example: grpc://localhost:8843/. Default is +empty. + +--jitter-uniform +Add uniformly distributed absolute request-release timing jitter. For +example, to add 10 us of jitter, specify .00001s. Default is empty / +no uniform jitter. + +--open-loop +Enable open loop mode. When enabled, the benchmark client will not +provide backpressure when resource limits are hit. + +--experimental-h1-connection-reuse-strategy +Choose picking the most recently used, or least-recently-used +connections for re-use.(default: mru). WARNING: this option is +experimental and may be removed or changed in the future! + +--failure-predicate (accepted multiple times) +Failure predicate. Allows specifying a counter name plus threshold +value for failing execution. Defaults to not tolerating error status +codes and connection errors. + +--termination-predicate (accepted multiple times) +Termination predicate. Allows specifying a counter name plus threshold +value for terminating execution. + +--trace +Trace uri. Example: zipkin://localhost:9411/api/v2/spans. Default is +empty. + +--sequencer-idle-strategy +Choose between using a busy spin/yield loop or have the thread poll or +sleep while waiting for the next scheduled request (default: spin). + +--max-concurrent-streams +Max concurrent streams allowed on one HTTP/2 or HTTP/3 connection. +Does not apply to HTTP/1. (default: 2147483647). + +--max-requests-per-connection +Max requests per connection (default: 4294937295). + +--max-active-requests +The maximum allowed number of concurrently active requests. HTTP/2 +only. (default: 100). + +--max-pending-requests +Max pending requests (default: 0, no client side queuing. Specifying +any other value will allow client-side queuing of requests). + +--transport-socket +Transport socket configuration in json or compact yaml. Mutually +exclusive with --tls-context. Example (json): +{name:"envoy.transport_sockets.tls" +,typed_config:{"@type":"type.googleapis.com/envoy.extensions.transport +_sockets.tls.v3.UpstreamTlsContext" +,common_tls_context:{tls_params:{cipher_suites:["-ALL:ECDHE-RSA-AES128 +-SHA"]}}}} + +--tls-context +DEPRECATED, use --transport-socket instead. Tls context configuration +in json or compact yaml. Mutually exclusive with --transport-socket. +Example (json): +{common_tls_context:{tls_params:{cipher_suites:["-ALL:ECDHE-RSA-AES128 +-SHA"]}}} + +--request-body-size +Size of the request body to send. NH will send a number of consecutive +'a' characters equal to the number specified here. (default: 0, no +data). + +--request-header (accepted multiple times) +Raw request headers in the format of 'name: value' pairs. This +argument may specified multiple times. + +--request-method +Request method used when sending requests. The default is 'GET'. + +--address-family +Network address family preference. Possible values: [auto, v4, v6]. +The default output format is 'AUTO'. + +--burst-size +Release requests in bursts of the specified size (default: 0). + +--prefetch-connections +Use proactive connection prefetching (HTTP/1 only). + +--output-format +Output format. Possible values: {"json", "human", "yaml", "dotted", +"fortio", "experimental_fortio_pedantic"}. The default output format +is 'human'. + +-v , --verbosity +Verbosity of the output. Possible values: [trace, debug, info, warn, +error, critical]. The default level is 'info'. + +--concurrency +The number of concurrent event loops that should be used. Specify +'auto' to let Nighthawk leverage all vCPUs that have affinity to the +Nighthawk process. Note that increasing this results in an effective +load multiplier combined with the configured --rps and --connections +values. Default: 1. + +-p , --protocol +The protocol to encapsulate requests in. Possible values: [http1, +http2, http3]. The default protocol is 'http1' when neither of --h2 or +--protocol is used. Mutually exclusive with --h2. + +--h2 +DEPRECATED, use --protocol instead. Encapsulate requests in HTTP/2. +Mutually exclusive with --protocol. Requests are encapsulated in +HTTP/1 by default when neither of --h2 or --protocol is used. + +--timeout +Connection connect timeout period in seconds. Default: 30. + +--duration +The number of seconds that the test should run. Default: 5. Mutually +exclusive with --no-duration. + +--connections +The maximum allowed number of concurrent connections per event loop. +HTTP/1 only. Default: 100. + +--rps +The target requests-per-second rate. Default: 5. + +--, --ignore_rest +Ignores the rest of the labeled arguments following this flag. + +--version +Displays version information and exits. + +-h, --help +Displays usage information and exits. + + +URI to benchmark. http:// and https:// are supported, but in case of +https no certificates are validated. Provide a URI when you need to +benchmark a single endpoint. For multiple endpoints, set +--multi-target-* instead. + + +``` + +# Using Nighthawk gRPC Service + +The gRPC service can be used to start a server which is able to perform back-to-back benchmark runs upon request. The service interface definition [can be found here](https://github.com/envoyproxy/nighthawk/blob/59a37568783272a6438b5697277d4e56aa16ebbe/api/client/service.proto). + +``` +bazel-bin/nighthawk_service --help +``` + +``` +USAGE: + +bazel-bin/nighthawk_service [--service ] +[--listener-address-file <>] [--listen +] [--] [--version] [-h] + + +Where: + +--service +Specifies which service to run. Default 'traffic-generator-service'. + +--listener-address-file <> +Location where the service will write the final address:port on which +the Nighthawk grpc service listens. Default empty. + +--listen +The address:port on which the Nighthawk gRPC service should listen. +Default: 0.0.0.0:8443. + +--, --ignore_rest +Ignores the rest of the labeled arguments following this flag. + +--version +Displays version information and exits. + +-h, --help +Displays usage information and exits. + + +L7 (HTTP/HTTPS/HTTP2) performance characterization tool. +``` + +# Nighthawk Output Transform Utility + +Nighthawk comes with a tool to transform its json output to its other supported output formats. + +``` +bazel-bin/nighthawk_output_transform --help +``` + +``` +USAGE: + +bazel-bin/nighthawk_output_transform --output-format [--] +[--version] [-h] + + +Where: + +--output-format +(required) Output format. Possible values: {"json", "human", "yaml", +"dotted", "fortio", "experimental_fortio_pedantic"}. + +--, --ignore_rest +Ignores the rest of the labeled arguments following this flag. + +--version +Displays version information and exits. + +-h, --help +Displays usage information and exits. + + +L7 (HTTP/HTTPS/HTTP2) performance characterization transformation tool. +``` + +See [Nighthawk README](https://github.com/envoyproxy/nighthawk) for more info.