diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b7c389f6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,204 @@ +# Contribution Guidelines + +Thanks for your interest in contributing to the ZDM Proxy! + +Below you'll find some guidelines to help you get started. +There are multiple ways you can contribute to the project, you can open Pull Requests +to fix a bug or add a new feature, report issues or improve the documentation. + +The proxy is written in Go, so if you're already familiar with the language, you'll notice +the project uses most of the standard tools and conventions in the Go ecosystem for code formatting, building +and testing. But if you're still new to it, don't worry, we'll give you an overview in the next +few sections. + +- [Code Contributions](#code-contributions) + - [Running Unit Tests](#running-unit-tests) + - [Running Integration Tests](#running-integration-tests) + - [Simulacron](#simulacron) + - [CCM](#ccm) + - [Running on Localhost with Docker Compose](#running-on-localhost-with-docker-compose) + - [Debugging](#debugging) + - [CPU and Memory Profiling](#cpu-and-memory-profiling) + - [Pull Request Checks](#pull-request-checks) + - [Code Formatting](#code-formatting) + +## Code Contributions + +--- +**Note:** If you'll contribute code or examples via a Pull Request (PR) to this ZDM Proxy project, be sure to first read +the Contribution License Agreement (CLA) at https://cla.datastax.com/. You'll be required to sign it with your GitHub +account before we can consider accepting your PR changes. +--- + +**Before you start working on a feature or major change, we ask you to discuss your idea with the members +of the community by opening an issue in GitHub, this way we can discuss design considerations and +feasibility before you invest your time on the effort.** + +When you're ready to code, follow these steps: + +1. If you haven't done so yet, go ahead now and fork the ZDM Proxy repository into your own Github account and clone it +on your machine. That's how you'll be able to make contributions, you cannot push directly to the main repository, but +you can open a Pull Request for your branch when you're ready. + + +2. From your fork, create a new local branch where you'll make changes. Give it a short, descriptive, name. +If there's an associated issue open, include its number as a prefix, *#issue-name*, for example: 10-fix-bug-xyz. + + +3. Make the changes you want locally and validate them with the [test tools](#running-unit-tests) provided. Push the +updated code to the remote branch in your fork. + + +4. Finally, when you're happy with your edits, open a Pull Request through the GitHub UI. + + +5. The automated tests in GitHub Actions will kick in and in a few minutes you should +have some results. If any of the checks fail, take a look at the workflow [logs](#pull-request-checks) to understand +what happened. You can push more commits to the PR until the problem is resolved, the checks will run again. + + +6. Once all checks are passing, your PR is ready for review and the members of the ZDM Proxy community will +start the process. You may be asked to make further adjustments, this is an iterative process, but +in the end if everything looks good, you'll be able to merge the PR to the main branch. + + +7. Congratulations! At this point your code is ready to be released in the official distribution in the +next release cycle. Keep an eye on the Releases page for new versions: https://github.com/datastax/zdm-proxy/releases + +### Running Unit Tests + +The main source code of the project is located under the [proxy](https://github.com/datastax/zdm-proxy/tree/main/proxy) +folder, but you'll notice some files have the following name pattern `*_test.go` next to the main file, +these are the unit tests. These tests are meant to run very quickly with no external dependencies. + +To run the unit tests, go the root of the project in a terminal window and execute the following command: + +> $ go test -v ./proxy/... + +You should see a PASS or FAIL message at the end of the execution. + +Make sure you add tests to your PR if you're making a major contribution. + +### Running Integration Tests + +The integration tests have different execution modes that allow you to test the proxy with +an in-memory CQL server, a mock service ([Simulacron](https://github.com/datastax/simulacron)), or an actual database +(managed by [CCM](https://github.com/riptano/ccm)). +By the default, it will run both the in-memory and Simulacron tests, but you can selectively +enable the ones you want with the command-line flags we'll see next. + +#### Simulacron + +Simulacron is a native protocol server simulator for Apache Cassandra® written in Java. It allows us to test the +protocol message exchanges over a socket from the proxy to the backend without having to run a fully-fledged database. + +It needs to be installed separately, and for that follow the installation instructions available +[here](https://github.com/datastax/simulacron#prerequisites). + +Now set the `SIMULACRON_PATH` environment variable to the path of the jar file you downloaded in the previous step. + +Simulacron relies on loopback aliases to simulate multiple nodes. On Linux or Windows, you shouldn't have anything to do. +On MacOS, run this script: + +```bash +#!/bin/bash +for sub in {0..4}; do + echo "Opening for 127.0.$sub" + for i in {0..255}; do sudo ifconfig lo0 alias 127.0.$sub.$i up; done +done +``` +It may take a couple of minutes for it to complete and settle down. Also, note that this does not survive reboots. + +Now you should be ready to run the Simulacron tests with: + +> $ go test -v ./integration-tests + +#### CCM + +Cassandra Cluster Manager (CCM) is a tool written in Python that manages local Cassandra installations for testing purposes. +These tests will be run automatically by Github when you open a PR, but you can optionally run them locally too, +for that follow the installation instructions available in the CCM [repository](https://github.com/riptano/ccm#installation). + +Once you have CCM installed, run the tests with: + +> $ go test -v ./integration-tests -RUN_CCMTESTS=true + +By the default, that will include the mock tests too (CQL Server and Simulacron), but you can disabled them and run CCM +only with: + +> $ go test -v ./integration-tests -RUN_CCMTESTS=true -RUN_MOCKTESTS=false + +In order to specify a specific Cassandra or DSE version, use the `CASSANDRA_VERSION` or `DSE_VERSION` flags, for example: + +> $ go test -v ./integration-tests -RUN_CCMTESTS=true -CASSANDRA_VERSION=3.11.8 + +### Running on Localhost with Docker Compose + +Sometimes you may want to run the proxy on localhost to do some manual validation, but in order to do anything meaningful +with it, you'll need to connect it to two database clusters (ORIGIN and TARGET). To simplify the process we provide a +[docker-compose](https://docs.docker.com/compose/) definition that handles the setup for you. + +The definition will start two Cassandra clusters, one ZDM proxy instance and automatically run a NoSQLBench workload to +verify the setup. + +Start the services with the following command (this assumes you have docker-compose [installed](https://docs.docker.com/compose/install/)): + +> $ docker-compose -f docker-compose-tests.yml up + +After it completes, it will still keep the containers running in case you want to do any further inspection. +To stop the services, hit CTRL+C and delete the containers with: + +> $ docker-compose -f docker-compose-tests.yml down + +### Debugging + +Similarly, there's a docker-compose setup for debugging the proxy while connected to running clusters. The provided +setup uses [Delve](https://github.com/go-delve/delve) to enable remote debugging so you can connect to the proxy from +your IDE. + +First, start docker-compose with the debug definition: + +> $ docker-compose -f docker-compose-debug.yml up + +Wait until you this message `API server listening at: [::]:2345`, then you'll know the debugger is ready. + +Now attach your IDE to the debugger at `localhost:2345`. If you're using IntelliJ, check +[this](https://www.jetbrains.com/help/go/attach-to-running-go-processes-with-debugger.html#step-4-start-the-debugging-process-on-the-client-computer) +guide to learn how. + +At this point the proxy is ready to receive requests, so enter some breakpoints in the IDE and connect some CQL client +to the proxy at `localhost:9042`. + +### CPU and Memory Profiling + +During development, you may want to enable CPU and Memory profiling on the proxy to investigate some performance degradation. +To do that, you'll have to build the proxy with profiling enabled first: + +> $ go build -tags profiling + +And then when you start the proxy, specify where to save the profile data: + +> $ ./proxy -cpu_profile cpu.prof -mem_profile heap.prof + +Note that these files will be created at the moment the proxy is stopped. These files can then be opened using the +Go tool [pprof](https://go.dev/blog/pprof). + +### Pull Request Checks + +All the tests we described above are also executed in an automated fashion by a GitHub Workflow when you +open a Pull Request. + +Below you see an example of a PR that had some successful tests but a couple that failed. + +![ZDM-PR-checks](docs/assets/ZDM-PR-checks.png) + +To investigate the failures, click the `Details` link next to the job you're interested in and that will take you to +execution logs. You can download the full log file by going to `Gear icon > Download log archive`: + +![ZDM-PR-logs](docs/assets/ZDM-PR-logs.png) + +In case you just want to see an overview of the test results, click the `Summary` link on the top left-hand side of the +page, which will show you only the relevant pieces of the log for the failed tests. + +![ZDM-PR-summary](docs/assets/ZDM-PR-summary.png) +![ZDM-PR-summary-details](docs/assets/ZDM-PR-summary-details.png) diff --git a/README.md b/README.md index 9d9f4874..c2025159 100644 --- a/README.md +++ b/README.md @@ -2,283 +2,117 @@ ## Overview -This is a simple proxy component to enable users to migrate without downtime from a Cassandra cluster to another (which may be an Astra cluster) without requiring code changes in the application client. +The ZDM Proxy is client-server component written in Go that enables users to migrate with zero downtime from an Apache +Cassandra® cluster to another (which may be an [Astra](https://astra.datastax.com/) cluster) and not requiring code +changes in the application client. -The only change to the client is pointing it to the proxy rather than directly to the original cluster. In turn, the proxy connects to both origin and target clusters. +The only change to the client is pointing it to the proxy rather than directly to the original cluster (Origin). In turn, +the proxy connects to both Origin and Target clusters. -The proxy will forward read requests only to the origin cluster, while writes will be sent to both clusters concurrently. +By default, the proxy will forward read requests only to the Origin cluster, though you can optionally configure it to +forward reads to both clusters asynchronously, while writes will always be sent to both clusters concurrently. -An overview of the proxy architecture and logical flow will be added here soon. +An overview of the proxy architecture and logical flow can be viewed [here](#). -## Frequently Asked Questions - -For frequently asked questions, please refer to our separate [faq](faq.md) page. +## Quick Start -## Environment Variables +In order to run the proxy, you'll need to set some environment variables to configure it properly. +Below you'll find a list with the most important variables along with their default values. +The required ones are marked with a comment. ```shell -PROXY_INDEX=0 -PROXY_ADDRESSES=127.0.0.1 -ORIGIN_ENABLE_HOST_ASSIGNMENT=true -TARGET_ENABLE_HOST_ASSIGNMENT=true -ORIGIN_CASSANDRA_CONTACT_POINTS=127.0.0.1 #required -ORIGIN_CASSANDRA_USERNAME=cassandra #required -ORIGIN_CASSANDRA_PASSWORD=cassandra #required -ORIGIN_CASSANDRA_PORT=9042 -TARGET_CASSANDRA_CONTACT_POINTS=127.0.0.1 #required -TARGET_CASSANDRA_USERNAME=cassandra #required -TARGET_CASSANDRA_PASSWORD=cassandra #required -TARGET_CASSANDRA_PORT=9043 -PROXY_METRICS_ADDRESS=127.0.0.1 -PROXY_METRICS_PORT=14001 -PROXY_QUERY_PORT=14002 -PROXY_QUERY_ADDRESS=127.0.0.1 -CLUSTER_CONNECTION_TIMEOUT_MS=30000 -HEARTBEAT_INTERVAL_MS=30000 -ENABLE_METRICS=true -MAX_CLIENTS_THRESHOLD=500 -FORWARD_READS_TO_TARGET=false -FORWARD_SYSTEM_QUERIES_TO_TARGET=true -REQUEST_TIMEOUT_MS=10000 -LOG_LEVEL=INFO +ZDM_ORIGIN_CONTACT_POINTS=10.0.0.1 #required +ZDM_ORIGIN_USERNAME=cassandra #required +ZDM_ORIGIN_PASSWORD=cassandra #required +ZDM_ORIGIN_PORT=9042 +ZDM_TARGET_CONTACT_POINTS=10.0.0.2 #required +ZDM_TARGET_USERNAME=cassandra #required +ZDM_TARGET_PASSWORD=cassandra #required +ZDM_TARGET_PORT=9042 +ZDM_PROXY_LISTEN_PORT=14002 +ZDM_PROXY_LISTEN_ADDRESS=127.0.0.1 +ZDM_PRIMARY_CLUSTER=ORIGIN +ZDM_READ_MODE=PRIMARY_ONLY +ZDM_LOG_LEVEL=INFO ``` -These environment variables must be set and exported for the proxy to work. They are read and processed into a `Config` struct, which is passed into the Proxy Service. +The environment variables must be set and exported for the proxy to work. -## Running and testing the proxy locally +In order to get started quickly, in your local environment, grab a copy of the binary distribution in the +[Releases](https://github.com/datastax/zdm-proxy/releases) page. For the recommended installation in a production +environment, check the [Production Setup](#production-setup) section below. -Launch two Cassandra single-node clusters as docker containers, one listening on port `9042` and the other on `9043`: +Now, suppose you have two clusters running at `10.0.0.1` and `10.0.0.2` with `cassandra/cassandra` credentials +and the same key-value [schema](nb-tests/schema.cql). You can start the proxy and connect it to these clusters like this: ```shell -docker run --name cassandra-source --env CASSANDRA_BROADCAST_ADDRESS=127.0.0.1 -p 9042:9042 -d cassandra -docker run --name cassandra-dest --env CASSANDRA_BROADCAST_ADDRESS=127.0.0.1 -p 9043:9042 -d cassandra +$ export ZDM_ORIGIN_CONTACT_POINTS=10.0.0.1 \ +export ZDM_TARGET_CONTACT_POINTS=10.0.0.2 \ +export ZDM_ORIGIN_USERNAME=cassandra \ +export ZDM_ORIGIN_PASSWORD=cassandra \ +export ZDM_TARGET_USERNAME=cassandra \ +export ZDM_TARGET_PASSWORD=cassandra \ +./zdm-proxy-v2.0.0 # run the ZDM proxy executable ``` -Open cqlsh directly on each of these clusters: - -```shell -docker exec -it cassandra-source cqlsh -``` +At this point, you should be able to connect some client such as [CQLSH](https://downloads.datastax.com/#cqlsh) to the proxy +and write data to it and the proxy will take care of forwarding the requests to both clusters concurrently. ```shell -docker exec -it cassandra-dest cqlsh +$ cqlsh 14002 # this is the proxy's default listen port ``` -Create a keyspace + table directly on each cluster, for example: +From the CQLSH prompt: ```cql -CREATE KEYSPACE test WITH REPLICATION = {'class' : 'SimpleStrategy', 'replication_factor' : 1}; -CREATE TABLE test.keyvalue (key int PRIMARY KEY, value text); -``` - -You can also use ccm instead of docker: - -```shell -ccm create -v 3.11.7 origin -ccm add -s --binary-itf="127.0.0.1:9042" --storage-itf="127.0.0.1:7000" --thrift-itf="127.0.0.1:9160" -r 5005 -j 9000 node1 -ccm start --wait-for-binary-proto - -ccm create -v 3.11.7 target -ccm add -s --binary-itf="127.0.0.1:9043" --storage-itf="127.0.0.1:7001" --thrift-itf="127.0.0.1:9161" -r 5006 -j 9001 node1 -ccm start --wait-for-binary-proto - -# use cqlsh on origin -ccm switch origin -ccm node1 cqlsh - -# use cqlsh on target -ccm switch target -ccm node1 cqlsh -``` - -Clone this project into the following directory, using the exact same path specified here: `~/go/src/github.com/riptano` - -In the configuration, use this environment variable list: `ORIGIN_CASSANDRA_CONTACT_POINTS=127.0.0.1;ORIGIN_CASSANDRA_USERNAME=cassandra;ORIGIN_CASSANDRA_PASSWORD=cassandra;ORIGIN_CASSANDRA_PORT=9042;TARGET_CASSANDRA_CONTACT_POINTS=127.0.0.10;TARGET_CASSANDRA_USERNAME=cassandra;TARGET_CASSANDRA_PASSWORD=cassandra;TARGET_CASSANDRA_PORT=9042;DEBUG=true;PROXY_METRICS_PORT=14001;PROXY_QUERY_PORT=14002` - -Start the proxy with the newly created run configuration. - -Install a cqlsh standalone client ([download here](https://downloads.datastax.com/#cqlsh)) and connect to the proxy: `./cqlsh localhost 14002`. - -Note that: - -- If you are debugging you may want to increase the timeouts to have more time to step through the code. The options are: ` --connect-timeout="XXX" --request-timeout="YYY" ` -- For the moment, the keyspace must be specified when accessing a table, even after using `USE `. - -Once connected, experiment sending some requests through the proxy. For example: - -```cql -INSERT INTO test.keyvalue (key, value) VALUES (1, 'ABC'); -INSERT INTO test.keyvalue (key, value) VALUES (2, 'DEF'); -SELECT * FROM test.keyvalue; -UPDATE test.keyvalue SET value='GYEKJF' WHERE key = 1; -DELETE FROM test.keyvalue WHERE key = 2; -``` - -And verify that the data is in both clusters by querying them directly through their own cqlsh. - -To test prepared statements, there is a simple noSQLBench activity under nb-tests that can be launched like this: - -`java -jar nb.jar run driver=cql workload=~/go/src/github.com/datastax/zdm-proxy/nb-tests/cql-nb-activity.yaml tags=phase:'rampup' cycles=20..30 host=localhost port=14002 cbopts=".withProtocolVersion(ProtocolVersion.V3)"` - -## Running the proxy with docker - -From the root of the repository, run the following and take note of the id of the generated image. - -```shell -docker build . -``` - -To make it easier to provide all of the necessary environment variables, create a simple `test.env` file with the following content: - -```shell -ORIGIN_CASSANDRA_CONTACT_POINTS=localhost -ORIGIN_CASSANDRA_USERNAME=cassandra -ORIGIN_CASSANDRA_PASSWORD=cassandra -ORIGIN_CASSANDRA_PORT=9042 -TARGET_CASSANDRA_CONTACT_POINTS=localhost -TARGET_CASSANDRA_USERNAME=cassandra -TARGET_CASSANDRA_PASSWORD=cassandra -TARGET_CASSANDRA_PORT=9043 -LOG_LEVEL=DEBUG -PROXY_METRICS_ADDRESS=0.0.0.0 -PROXY_METRICS_PORT=14001 -PROXY_QUERY_PORT=14002 -PROXY_QUERY_ADDRESS=0.0.0.0 -``` - -On Windows you need to replace both `_HOSTNAME` variables with `host.docker.internal`. - -Finally, run: - -```shell -docker run --env-file ./test.env IMAGE_ID -``` - -Here `IMAGE_ID` is the id of the image that was generated by the previous `docker build` step. - -## Building docker image and publishing it - -First login with your dockerhub creds. - -```shell -export DOCKER_USER= -export DOCKER_PASS= -make login -``` - -Then build and push the image. This will tag the image with the current git commit hash. - -```shell -make build push -``` - -This doesn't tag the image with `latest` or any version tag like `1.x`. To do that you need to copy the image tag that was printed to the console by `make push` or run `make get_current_tag` to get the tag based on the current git commit hash. Then you run `docker tag ` followed by `docker push `. - -For example, if you want to tag and push the image tagged by the current git commit hash with `1.x`, `1.0.1` and `latest`: - -```shell -> make get_current_tag -datastax/zdm-proxy:d046148f606b65b536bb0cc2bd63daf1d556e778 -> docker tag datastax/zdm-proxy:d046148f606b65b536bb0cc2bd63daf1d556e778 datastax/zdm-proxy:1.x -> docker tag datastax/zdm-proxy:d046148f606b65b536bb0cc2bd63daf1d556e778 datastax/zdm-proxy:1.0.1 -> docker tag datastax/zdm-proxy:d046148f606b65b536bb0cc2bd63daf1d556e778 datastax/zdm-proxy:latest -> docker push datastax/zdm-proxy:1.x -> docker push datastax/zdm-proxy:1.0.1 -> docker push datastax/zdm-proxy:latest +cqlsh> INSERT INTO test.keyvalue (key, value) VALUES (1, 'ABC'); +cqlsh> INSERT INTO test.keyvalue (key, value) VALUES (2, 'DEF'); +cqlsh> SELECT * FROM test.keyvalue; +cqlsh> UPDATE test.keyvalue SET value='GYEKJF' WHERE key = 1; +cqlsh> DELETE FROM test.keyvalue WHERE key = 2; ``` +You can confirm that the data is stored in both clusters by querying them directly in other cqlsh sessions. +Note: For the moment, the keyspace must be specified when accessing a table, even after using `USE `. +If you don't have test clusters readily available to try with, check the [alternative](./CONTRIBUTING.md#running-on-localhost-with-docker-compose) method with docker-compose in the +[Contributor's guide](./CONTRIBUTING.md), which will set up all the dependencies, including two test clusters and a proxy instance, in a +containerized sandbox environment. -## Integration tests - -The `integration-tests` module contains integration tests that use `CCM` and `Simulacron`. +## Supported Protocol Versions -### Tools setup +**ZDM Proxy supports protocol versions v3, v4, DSE_V1 and DSE_V2.** -`Simulacron` is required but `CCM` is optional. By default only `Simulacron` tests run. +It technically doesn't support v5, but handles protocol negotiation so that the client application properly downgrades +the protocol version to v4 if v5 is requested. This means that any client application using a recent driver that supports +protocol version v5 can be migrated using the ZDM Proxy (as long as it does not use v5-specific functionality). -#### Simulacron +--- +**Thrift is not supported by ZDM Proxy.** If you are using a very old driver or cluster version that only supports Thrift +then you need to change your client application to use CQL and potentially upgrade your cluster before starting the +migration process. +--- -To run the default suite of integration tests you need [simulacron][simulacronrepo]: +In practice this means that ZDM Proxy supports the following cluster versions (as Origin and / or Target): -1. Download the latest jar file [here][simulacronreleases]. -2. Set `SIMULACRON_PATH` environment variable to the path of the jar file you downloaded in the previous step. - -Simulacron relies on loopback aliases to simulate multiple nodes. On Linux or Windows, you shouldn't have anything to do. On MacOS, run this script: - -```bash -#!/bin/bash -for sub in {0..4}; do - echo "Opening for 127.0.$sub" - for i in {0..255}; do sudo ifconfig lo0 alias 127.0.$sub.$i up; done -done -``` +- Apache Cassandra from 2.1+ up to (and including) Apache Cassandra 4.x. Apache Cassandra 2.0 support will be introduced +when protocol version v2 is supported. +- DataStax Enterprise 4.8+. DataStax Enterprise 4.6 and 4.7 support will be introduced when protocol version v2 is supported. +- DataStax Astra DB (both Serverless and Classic) -Note that this is known to cause temporary increased CPU usage in OS X initially while mDNSResponder acclimates itself to the presence of added IP addresses. This lasts several minutes. Also, this does not survive reboots. +## Production Setup -#### CCM +The setup we described above is only for testing in a local environment. It is **NOT** recommended for a production +installation where the minimum number of proxy instances is 3. -The optional integration tests require [ccm][ccmrepo] on your machine so make sure the ccm commands are accessible from the command line. You should be able to run `> cmd.exe /c ccm help` using command line on Windows or `$ /usr/local/bin/ccm help` on Linux / macOS. - -Installing CCM on **linux/macOS** it should be as simple as cloning the [ccm][ccmrepo] and running `sudo ./setup.py install` - -On **Windows**, however, there are a couple of dependencies and environment variables that you need to set up. This [blog post][ccm-windows-blog] should help you set up those dependencies and environment variables. - -### Running the tests - -By default only `Simulacron` based tests will run: - -```shell -# from the root of the repository -go test -v ./integration-tests -``` - -To include `CCM` based tests run: - -```shell -# from the root of the repository -go test -v ./integration-tests -RUN_CCMTESTS=true -``` +For a comprehensive guide with the recommended production setup check the documentation available at -If using IntelliJ Goland or the go plugin for IntelliJ Idea Ultimate, you can create a run configuration as shown here (you can remove the `Program arguments` to exclude `CCM` tests): - -![Run configuration](img/integration_tests_run_config.png) - -### Advanced - -If you want to specify which C*/DSE version is used for `CCM` and `Simulacron`, you can specify the `CASSANDRA_VERSION` and `DSE_VERSION` flags: - -```shell -# from the root of the repository -go test -v ./integration-tests -RUN_CCMTESTS=true -CASSANDRA_VERSION=3.11.8 -``` - -Also note that any of the test flags can also be provided via environment variables instead. If both are present then the test flag is used instead of the environment variable. - -[ccmrepo]: https://github.com/riptano/ccm -[simulacronrepo]: https://github.com/datastax/simulacron -[simulacronreleases]: https://github.com/datastax/simulacron/releases -[ccm-windows-blog]: https://www.datastax.com/blog/2015/01/ccm-20-and-windows - -### Building the proxy with CPU and memory profiling support - -To add built-in support for CPU and memory profiling (strictly for development only), build the proxy as follows: - -```shell -go build -tags profiling -``` - -This will add two flags that can be optionally specified at proxy startup to enable CPU and / or memory profiling: - -```shell -./proxy -cpu_profile cpu.prof -mem_profile heap.prof -``` - -Where `cpu.prof` and `heap.prof` are the names of the files in which the profiling data will be stored. -Note that these files will be created when the proxy is stopped. - -These files can then be accessed using `go tool pprof` (see [here](https://go.dev/blog/pprof)). +There you'll find information about an Ansible-based tool that automates most of the process. ## Project Dependencies For information on the packaged dependencies of the Zero Downtime Migration (ZDM) Proxy and their licenses, check out our [open source report](https://app.fossa.com/reports/910065e9-5620-4ed7-befb-b69c45ebce6e). + +## Frequently Asked Questions + +For frequently asked questions, please refer to our separate [FAQ](faq.md) page. \ No newline at end of file diff --git a/docs/assets/ZDM-PR-checks.png b/docs/assets/ZDM-PR-checks.png new file mode 100644 index 00000000..e5720612 Binary files /dev/null and b/docs/assets/ZDM-PR-checks.png differ diff --git a/docs/assets/ZDM-PR-logs.png b/docs/assets/ZDM-PR-logs.png new file mode 100644 index 00000000..bd12962f Binary files /dev/null and b/docs/assets/ZDM-PR-logs.png differ diff --git a/docs/assets/ZDM-PR-summary-details.png b/docs/assets/ZDM-PR-summary-details.png new file mode 100644 index 00000000..4670de19 Binary files /dev/null and b/docs/assets/ZDM-PR-summary-details.png differ diff --git a/docs/assets/ZDM-PR-summary.png b/docs/assets/ZDM-PR-summary.png new file mode 100644 index 00000000..c406cdf7 Binary files /dev/null and b/docs/assets/ZDM-PR-summary.png differ