dschneider-pivotal commented on a change in pull request #5450: URL: https://github.com/apache/geode/pull/5450#discussion_r470051786
########## File path: geode-redis/README.md ########## @@ -1,78 +1,302 @@ -# Geode Redis Module - -## Contents -1. [Overview](#overview) -2. [Performance Test Scripts](#performance-test) - -## <a name="overview"></a>Overview - -The [Redis API for Geode](https://geode.apache.org/docs/guide/12/tools_modules/redis_api_for_geode.html) allows -Geode to function as a drop-in replacement for a Redis data store, letting Redis applications -take advantage of Geode’s scaling capabilities without changing their client code. Redis clients -connect to a Geode server in the same way they connect to a Redis server, using a hostname and a -port number. - -## <a name="performance-test"></a>Performance Test Scripts - -###The `benchmark.sh` Script -To run the performance tests, use the `benchmark.sh` script located in the -`geode-redis/src/performanceTest` directory. This script uses the `redis-benchmark` command to -measure performance of various Redis commands in requests per second. It runs the commands in two -different ways. First it runs several clients in parallel, all testing the same command. Then it -runs all the commands together in parallel, crudely simulating a variety of simultaneous operations. - -Optional command line arguments for `benchmark.sh`: -- `-h` indicates the host to connect to (default: `localhost`) -- `-p` indicates the port to connect to (default: `6379`) -- `-t` indicates the number of times the `redis-benchmark` command will run (default: `10`) -- `-c` indicates the number of times the individual commands will run (default: `100000`) -- `-f` indicates an optional prefix for the summary file name - -The script will output a CSV file called `[optional prefix_]benchmark_summary.csv` which can be -easily loaded into any spreadsheet program for analysis. - -Sample output: -```csv -Command,Fastest Response Time (Msec),95th-99th Percentile (Msec),Slowest Response Time (Msec),Avg Requests Per Second -SET,1,8,43,13329 -GET,1,4,15,17842 -INCR,1,5,29,16069 -MSET,1,7,732,11183 -Parallel-SET,1,4,20,18460 -Parallel-GET,1,4,21,18291 -Parallel-INCR,1,4,20,18271 -Parallel-MSET,1,4,21,17771 -``` +# Redis API for Apache Geode + +[Introduction](#introduction) +[How To Try It](#how-to-try-it) +[Building Apache Geode](#building-apache-geode) +[Starting a Geode Server with Redis Enabled](#starting-a-server) +[Adding an Additional Geode Redis Server](#adding-a-server) +[Shutting Down](#shutting-down) +[Redis Commands](#redis-commands) + +## <a name="introduction"></a>Introduction + +The Redis API for Geode allow an application to send Redis commands to Geode. This will allow users to +switch seamlessly from native Redis to Geode as a data store/caching solution. + +The API allows Geode to listen for and interpret incoming Redis commands on a designated port. The +current set of supported Redis commands are listed [here](#redis-commands). + +## <a name="how-to-try-it"></a>How To Try It + +We’ll build the develop branch of Apache Geode and then connect the Redis-CLI to that instance. Once +we have established that the Redis APIs are available, we’ll connect a Spring Session Data Redis +application. + +### <a name="building-apache-geode"></a>Building Apache Geode +The Apache Geode source code can be found here + +1. In a terminal, git clone the Geode repo: + ```commandline + $ git clone https://github.com/apache/geode.git + ``` + +2. Change the working directory to the Geode directory you cloned + ```commandline + $ cd geode + ``` + +3. Build the Geode application without running the test (REQUIRES JAVA 8) + ```commandline + $ ./gradlew build -x test + ``` + +4. Once the build has completed, navigate to the geode-assembly directory which contains the Apache + Geode Shell - also referred to as GFSH: + ```commandline + $ cd geode-assembly/build/install/apache-geode/bin + ``` -###Benchmark Helper Scripts -The `benchmark.sh` script uses several helper scripts. The `execute-operation.sh` script runs a -particular instance of `redis-benchmark`. The `summarize-operation-results.sh` script processes the -output of `execute-operation.sh`, and the `summarize-batch-results.sh` script processes the output -of multiple runs of `summarize-operation-results.sh`. +5. Once in that folder run the following command: + ```commandline + $ ./gfsh + ``` -###The `environment-setup.sh` Script -The `environment-setup.sh` is optional. It can start a local Geode Redis Adapter, or confirm that a -local Redis server is running, then call `benchmark.sh`. +You should now see GFSH starting up with a version of 1.14.x.-build.x -Mandatory command line arguments for `environment-setup.sh`: -- either `-g` or `-r` + -`-g` will: -- Start a local Geode Redis Server for you -- Shut the server down once the benchmark finishes +### <a name="starting-a-server"></a>Starting a Geode Server with Redis Enabled +Using GFSH enter the following commands: -`-r` will: -- Connect to a Redis server that is already running +1. Start a locator. The locator tracks servers and server load. When a client requests a server +connection, the locator directs the client to one of the least loaded servers. Learn more. + ```commandline + gfsh> start locator + ``` -Optional command line arguments for `environment-setup.sh`: -- `-f` indicates an optional prefix for the summary file name that will be passed to `benchmark.sh` +2. After the locator has started, start a server that will be able to handle incoming Redis commands. -###The `shacompare.sh` Script -The `shacompare.sh` script is used to compare performance between different commits. This script -takes in two different commit hashes, checks them out, uses `environment-setup.sh` script to start -up the Geode Redis server, and runs the benchmarks for each commit. It generates two summary CSV -files, labeled with the short commit hash, that can be compared for performance changes. + For example: + ```commandline + gfsh> start server --name=redisServer1 --locators=localhost[10334] --server-port=0 --redis-port=6379 --redis-bind-address=127.0.0.1 Review comment: I think, for this example, the --redis-bind-address is not needed (we listen on all local addresses by default). ########## File path: geode-redis/README.md ########## @@ -1,78 +1,302 @@ -# Geode Redis Module - -## Contents -1. [Overview](#overview) -2. [Performance Test Scripts](#performance-test) - -## <a name="overview"></a>Overview - -The [Redis API for Geode](https://geode.apache.org/docs/guide/12/tools_modules/redis_api_for_geode.html) allows -Geode to function as a drop-in replacement for a Redis data store, letting Redis applications -take advantage of Geode’s scaling capabilities without changing their client code. Redis clients -connect to a Geode server in the same way they connect to a Redis server, using a hostname and a -port number. - -## <a name="performance-test"></a>Performance Test Scripts - -###The `benchmark.sh` Script -To run the performance tests, use the `benchmark.sh` script located in the -`geode-redis/src/performanceTest` directory. This script uses the `redis-benchmark` command to -measure performance of various Redis commands in requests per second. It runs the commands in two -different ways. First it runs several clients in parallel, all testing the same command. Then it -runs all the commands together in parallel, crudely simulating a variety of simultaneous operations. - -Optional command line arguments for `benchmark.sh`: -- `-h` indicates the host to connect to (default: `localhost`) -- `-p` indicates the port to connect to (default: `6379`) -- `-t` indicates the number of times the `redis-benchmark` command will run (default: `10`) -- `-c` indicates the number of times the individual commands will run (default: `100000`) -- `-f` indicates an optional prefix for the summary file name - -The script will output a CSV file called `[optional prefix_]benchmark_summary.csv` which can be -easily loaded into any spreadsheet program for analysis. - -Sample output: -```csv -Command,Fastest Response Time (Msec),95th-99th Percentile (Msec),Slowest Response Time (Msec),Avg Requests Per Second -SET,1,8,43,13329 -GET,1,4,15,17842 -INCR,1,5,29,16069 -MSET,1,7,732,11183 -Parallel-SET,1,4,20,18460 -Parallel-GET,1,4,21,18291 -Parallel-INCR,1,4,20,18271 -Parallel-MSET,1,4,21,17771 -``` +# Redis API for Apache Geode + +[Introduction](#introduction) +[How To Try It](#how-to-try-it) +[Building Apache Geode](#building-apache-geode) +[Starting a Geode Server with Redis Enabled](#starting-a-server) +[Adding an Additional Geode Redis Server](#adding-a-server) +[Shutting Down](#shutting-down) +[Redis Commands](#redis-commands) + +## <a name="introduction"></a>Introduction + +The Redis API for Geode allow an application to send Redis commands to Geode. This will allow users to +switch seamlessly from native Redis to Geode as a data store/caching solution. + +The API allows Geode to listen for and interpret incoming Redis commands on a designated port. The +current set of supported Redis commands are listed [here](#redis-commands). + +## <a name="how-to-try-it"></a>How To Try It + +We’ll build the develop branch of Apache Geode and then connect the Redis-CLI to that instance. Once +we have established that the Redis APIs are available, we’ll connect a Spring Session Data Redis +application. + +### <a name="building-apache-geode"></a>Building Apache Geode +The Apache Geode source code can be found here + +1. In a terminal, git clone the Geode repo: + ```commandline + $ git clone https://github.com/apache/geode.git + ``` + +2. Change the working directory to the Geode directory you cloned + ```commandline + $ cd geode + ``` + +3. Build the Geode application without running the test (REQUIRES JAVA 8) + ```commandline + $ ./gradlew build -x test + ``` + +4. Once the build has completed, navigate to the geode-assembly directory which contains the Apache + Geode Shell - also referred to as GFSH: + ```commandline + $ cd geode-assembly/build/install/apache-geode/bin + ``` -###Benchmark Helper Scripts -The `benchmark.sh` script uses several helper scripts. The `execute-operation.sh` script runs a -particular instance of `redis-benchmark`. The `summarize-operation-results.sh` script processes the -output of `execute-operation.sh`, and the `summarize-batch-results.sh` script processes the output -of multiple runs of `summarize-operation-results.sh`. +5. Once in that folder run the following command: + ```commandline + $ ./gfsh + ``` -###The `environment-setup.sh` Script -The `environment-setup.sh` is optional. It can start a local Geode Redis Adapter, or confirm that a -local Redis server is running, then call `benchmark.sh`. +You should now see GFSH starting up with a version of 1.14.x.-build.x -Mandatory command line arguments for `environment-setup.sh`: -- either `-g` or `-r` + -`-g` will: -- Start a local Geode Redis Server for you -- Shut the server down once the benchmark finishes +### <a name="starting-a-server"></a>Starting a Geode Server with Redis Enabled +Using GFSH enter the following commands: -`-r` will: -- Connect to a Redis server that is already running +1. Start a locator. The locator tracks servers and server load. When a client requests a server +connection, the locator directs the client to one of the least loaded servers. Learn more. + ```commandline + gfsh> start locator + ``` -Optional command line arguments for `environment-setup.sh`: -- `-f` indicates an optional prefix for the summary file name that will be passed to `benchmark.sh` +2. After the locator has started, start a server that will be able to handle incoming Redis commands. -###The `shacompare.sh` Script -The `shacompare.sh` script is used to compare performance between different commits. This script -takes in two different commit hashes, checks them out, uses `environment-setup.sh` script to start -up the Geode Redis server, and runs the benchmarks for each commit. It generates two summary CSV -files, labeled with the short commit hash, that can be compared for performance changes. + For example: + ```commandline + gfsh> start server --name=redisServer1 --locators=localhost[10334] --server-port=0 --redis-port=6379 --redis-bind-address=127.0.0.1 + ``` + * --name: A name you create for your server. + * --locators: This is the location of the locator you started in step 1. + * --server-port: The port that Geode clients connect to. + * --redis-port: The port that your Redis client will connect to. + * --redis-bind-address: This will be the address your client uses to connect. + + Your Geode instance should now be up and running (1 locator and 1 server) and ready to accept Redis + commands. + + **Keep this terminal open and running so that you can easily shutdown the Geode instance when you are + done working locally.** + +3. To confirm that things are running correctly, in a separate terminal run: + ```commandline Review comment: Should we say something here about the version of redis they should use and how to get the redis-cli installed? ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
