From c5fdf1d6a39c0529eb810dbad821e59d7686ea2d Mon Sep 17 00:00:00 2001 From: Tymoteusz Czech <2625371+Tymek@users.noreply.github.com> Date: Tue, 7 Nov 2023 15:55:43 +0100 Subject: [PATCH] Docs: debugging and persistent storage explanations (#325) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Nuno Góis Co-authored-by: Thomas Heartman --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index d50cd067..5fbc971a 100644 --- a/README.md +++ b/README.md @@ -168,6 +168,10 @@ This means that, in order to start up, Edge mode needs to know where the upstrea By default, Edge mode uses an in-memory cache to store the features it fetches from the upstream node. However, you may want to use a more persistent storage solution. For this purpose, Edge supports either Redis or a backup file, which you can configure by passing in either the `--redis-url` or `--backup_folder` command line argument, respectively. On start-up, Edge checks whether the persistent backup option is specified, in which case it uses it to populate its internal caches. This can be useful when your Unleash server is unreachable. +Persistent storage is useful for high availability and resilience. If an Edge instance using persistent storage is restarted, it will not have to synchronize with upstream before it is ready. The persistent storage is only read on startup and will only be used until Edge is able to synchronize with upstream. Because of this, there is no need to purge the cache. After Edge has synchronized with an upstream, it will periodically save its in-memory state to the persistent storage. + +Multiple Edge nodes can share the same Redis instance or backup folder. Failure to read from persistent storage will not prevent Edge from starting up. In this case an Edge instance will be ready only after it is able to connect with upstream. + Edge mode also supports dynamic tokens, meaning that Edge doesn't need a token to be provided when starting up. Once we make a request to the `/api/client/features` endpoint using a [client token](https://docs.getunleash.io/reference/api-tokens-and-client-keys#client-tokens) Edge will validate upstream and fetch its respective features. After that, it gets added to the list of known tokens that gets periodically synced, making sure it is a valid token and its features are up-to-date. Even though Edge supports dynamic tokens, you still have the option of providing a token through the command line argument or environment variable. This way, since Edge already knows about your token at start up, it will sync your features for that token and should be ready for your requests right away (_warm up / hot start_). @@ -375,6 +379,16 @@ However, there are a few notable differences between the Unleash Proxy and Unlea - Backend SDKs can connect to Unleash Edge without turning on experimental feature flags. - Unleash Edge is smart enough to dynamically resolve the tokens you use to connect to it against the upstream Unleash instance. This means you don't have to worry about knowing in advance what tokens your SDKs use - if you want to swap out the Unleash token your SDK uses, this can be done without ever restarting or worrying about Unleash Edge. Unleash Edge will only collect and cache data for the environments and projects you use. +## Debugging + +You can adjust the `RUST_LOG` environment variable to see more verbose log output. For example, in order to get logs originating directly from Edge but not its dependencies, you can raise the default log level from `error` to `warning` and set Edge to `debug`, like this: + +```sh +RUST_LOG="warn,unleash-edge=debug" ./unleash-edge # +``` + +See more about available logging and log levels at https://docs.rs/env_logger/latest/env_logger/#enabling-logging + ## Development See our [Contributors guide](./CONTRIBUTING.md) as well as our [development-guide](./development-guide.md)