docs: Performance section (#5880)

Co-authored-by: htessaro <heitor@writechoice.io>

Author: guiwrite

docs/docs/performance/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Performance",
+    "position": 80,
+    "collapsed": true
+}

docs/docs/performance/edge-api.md

@@ -0,0 +1,140 @@
+---
+title: Edge API
+sidebar_label: Edge API
+sidebar_position: 30
+---
+
+If you are a Flagsmith SaaS customer, you are using our Edge API by default.
+
+[The Flagsmith Architecture](/clients#remote-evaluation) is based around a server-side flag engine. This comes with a
+number of benefits, but it can increase latency, especially when the calls are being made from a location that is far
+from the EU; the location of our current API. It also provides a single point of failure in the event of an AWS
+region-wide outage.
+
+The Edge API solves both of these issues. It provides a datastore and Edge compute API that is replicated across 8 AWS
+regions, with latency-based routing and global failover in the event of a region outage.
+
+The Edge API provides API service from the following AWS regions:
+
+- Europe (London) - `eu-west-2`
+- US East (Ohio) - `us-east-2`
+- US West (N. California) - `us-west-1`
+- Asia Pacific (Mumbai) - `ap-south-1`
+- Asia Pacific (Sydney) - `ap-southeast-2`
+- South America (São Paulo) - `sa-east-1`
+- Asia Pacific (Seoul) - `ap-northeast-2`
+- Asia Pacific (Singapore) - `ap-southeast-1`
+
+## Enabling the Edge API
+
+:::tip
+
+Existing organisations created before **7th June 2022** have their projects deployed to the Core API. You can migrate your project over to our Edge API by going to the **Project Settings** page and hitting the **Start Migration** button. The migration will take between 1 minute and an hour depending on how many identities your project has.
+
+The Core API will continue to work normally during and following the migration. See the
+[Migration Steps](#migration-steps) for more info.
+
+:::
+
+Once you have had your projects migrated to Edge, all you will need to do is point your SDK to a new Flagsmith Edge API
+URL at `edge.api.flagsmith.com`. This domain points to our Edge CDN. That's it!
+
+The easiest way to do this is to upgrade to the latest version of the Flagsmith SDK for your language.
+
+If you are unable to upgrade, you can manually point the existing SDK to the Edge API endpoint. So for example, in the
+Java SDK we just add the `withApiUrl` line:
+
+```java
+FlagsmithClient flagsmithClient = FlagsmithClient.newBuilder()
+        .setApiKey("aaa"))
+        .withApiUrl("https://edge.api.flagsmith.com/api/v1/")
+        .build();
+```
+
+Note that the Edge API URL is: `https://edge.api.flagsmith.com/api/v1/`.
+
+Check the docs for your language SDK on how to override the endpoint URL prefix.
+
+## Migration Steps
+
+The migration process will carry out a one-way sync of your `identity` data, from the Core API to the Edge API. All your `identity` data will continue to exist within the Core API, and you can continue to write `identities` to the Core API if you wish.
+
+The goal is to get all of your applications running against the Edge API, where you will benefit from global low latency as well as multi-region failover and fault tolerance.
+
+### Step 1 - Prepare your applications
+
+Set your applications up to point to the Flagsmith Edge API. This means going from `api.flagsmith.com` to `edge.api.flagsmith.com`. You can either set this explicitly in our SDK or just ensure you are running the latest version of the SDK; by default the _latest version_ of the SDKs will point to `edge.api.flagsmith.com`.
+
+### Step 2 - Migrate your data
+
+You can now trigger a one-way sync of data for each of your Flagsmith projects within the Flagsmith Dashboard. You can migrate your project over to our edge API by going to the **Project Settings** page and hitting the **Start Migration** button. This will start a job that can take between 1 minute and 1 hour, depending on how much data you have. Once the job is complete, all the identities that were present in your Core API will be present in the Edge API.
+
+The Core API will continue to work normally during and following the migration.
+
+:::caution
+
+As of Dec 1st, 2023, we will no longer be replicating identities from the Core API to our Edge API. Please ensure your applications are fully migrated before this point in time.
+
+:::
+
+If you have a product like a mobile app, where you cannot immediately force your users to upgrade (as opposed to a web app, for example), you will likely generate identity writes to the old Core API.
+
+Following and during the migration, if we receive a request to an `identity` endpoint that results in a write to the Core API, we will persist the data in the Core API _and replay the request into the Edge API_. You can then update your API endpoints/SDKs in your own time to gradually move over the Edge API. This will give you time to migrate your users over to the new version of your application.
+
+Note that writes to the Core API will still work into the future, but the data will not be synchronised across the two platforms (Core and Edge).
+
+### Step 3 - Deploy your applications
+
+Once your data has been copied onto the Edge API datastore, you can now deploy your applications that point to the new endpoint `edge.api.flagsmith.com` and benefit from global low latency!
+
+## Things you should know
+
+### Some of the Secure Identity Endpoints Have Changed
+
+If you are using our REST API to manipulate/update/list your identities, some of these endpoints have changed. Please get in touch if you need any help related to this.
+
+### New Identity Overrides Will Only Apply to the Edge API
+
+After the migration, any new identity overrides you apply to feature flag values for specific identities will only be applied to the Edge API.
+
+### Increment and Decrement endpoints are deprecated
+
+You probably didn't know these existed though, right?
+
+### Bulk Trait endpoint is deprecated
+
+But you can still achieve the same functionality using our POST /identities endpoints.
+
+### The API responses have been slimmed down
+
+Our core API responses are quite verbose, and the SDKs ignore a lot of the fields they receive. We've taken the
+opportunity to remove these additional, unused fields. This wont affect the SDKs but if you are using these values via
+the REST API, things have changed. The list of removed fields is as follows:
+
+```txt
+trait.id
+flag.feature.created_data
+flag.feature.description
+flag.feature.initial_value
+flag.feature.default_enabled
+flag.environment
+flag.identity
+flag.feature_segment
+```
+
+## Architecture
+
+You can see our SaaS architecture [here](/system-administration/architecture.md#saas).
+
+## How It Works
+
+### Lambda@Edge
+
+Our core [Rules Engine](https://github.com/Flagsmith/flagsmith-engine) has been factored out of our REST API. This
+allows us to use it as a dependency within both the Flagsmith API, but also within a set of Lambda functions that
+service SDK API calls. You can point your SDK clients to our global CDN `edge.api.flagsmith.com` which will serve your
+request using a Lambda function running in an AWS data-centre near your client. This is how we reduce latency!
+
+### DynamoDB Global Tables
+
+We store state within our API - both related to the environments for your projects, but also for the identities within those environments. Our Edge design sees us write this data through to DynamoDB global tables, which are replicated globally. Our Lambda functions then connect to the nearest DynamoDB table to retrieve both environment and identity data.

docs/docs/performance/edge-proxy.md

@@ -0,0 +1,73 @@
+---
+title: Edge Proxy
+sidebar_label: Edge Proxy
+sidebar_position: 10
+---
+
+The Flagsmith Edge Proxy is a service that you host yourself, that allows you to run an instance of the Flagsmith Engine close to your servers. If you are running Flagsmith within a server-side environment and you want to have very low latency flags, you have two options:
+
+1. Run the Edge Proxy within in your own infrastructure and connect to it from your server-side SDKs
+2. Run your server-side SDKs in [Local Evaluation Mode](/clients#local-evaluation).
+
+The main benefit to running the Edge Proxy is that you reduce your polling requests against the Flagsmith API itself.
+
+The main benefit to running server side SDKs in [Local Evaluation Mode](/clients#local-evaluation) is that you get the lowest possible latency.
+
+## How does it work
+
+:::info
+
+The Edge Proxy has the same [caveats as running our SDK in Local Evaluation mode.](/clients/#local-evaluation).
+
+:::
+
+You can think of the Edge Proxy as a copy of our Python Server Side SDK, running in [Local Evaluation Mode](/clients#local-evaluation), with an API interface that is compatible with the Flagsmith SDK API.
+
+The Edge Proxy runs as a lightweight Docker container. It connects to the Flagsmith API (either powered by us at `api.flagsmith.com` or self hosted by you) to get environment flags and segment rules. You can then point the Flagsmith SDKs to your Edge Proxy; it implements all the current SDK endpoints. This means you can serve a very large number of requests close to your infrastructure and users, at very low latency. Check out the [architecture below](#architecture).
+
+The proxy also acts as a local cache, allowing you to make requests to the proxy without hitting the Core API.
+
+## Performance
+
+The edge proxy can currently serve ~2,000 requests per second (RPS) at a mean latency of ~7ms on an M1 MacBook Pro with a simple set of feature flags. Working with more complex environments with many segment rules will bring this RPS number down.
+
+It is stateless and hence close to perfectly scalable being deployed behind a load balancer.
+
+## Managing Traits
+
+There is one caveat with the Edge Proxy. Because it is entirely stateless, it is not able to persist trait data into any sort of datastore. This means that you _have_ to provide the full complement of traits when requesting the flags for a particular identity. Our SDKs all provide relevant methods to achieve this. An example using `curl` would read as follows:
+
+```bash
+curl -X "POST" "http://localhost:8000/api/v1/identities/?identifier=do_it_all_in_one_go_identity" \
+     -H 'X-Environment-Key: n9fbf9h3v4fFgH3U3ngWhb' \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     -d $'{
+  "traits": [
+      {
+          "trait_value": 123.5,
+          "trait_key": "my_trait_key"
+      },
+      {
+          "trait_value": true,
+          "trait_key": "my_other_key"
+      }
+  ],
+  "identifier": "do_it_all_in_one_go_identity"
+}'
+```
+
+Note that the Edge Proxy will currently _not_ send the Trait data back to the Core API.
+
+## Deployment and Configuration
+
+Please see the [hosting documentation](/deployment/hosting/locally-edge-proxy).
+
+## Architecture
+
+The standard Flagsmith architecture:
+
+![Image](/img/edge-proxy-existing.svg)
+
+With the proxy added to the mix:
+
+![Image](/img/edge-proxy-proxy.svg)

docs/docs/performance/real-time-flags.md

@@ -0,0 +1,101 @@
+---
+title: Real-time flag updates
+sidebar_label: Real-time Flags
+sidebar_position: 20
+---
+
+When an application fetches its current feature flags, it usually caches the flags for a certain amount of time to make [efficient use](/guides-and-examples/efficient-api-usage) of the Flagsmith API and network resources. In some cases, you may want an application to be notified about feature flag updates without needing to repeatedly call the Flagsmith API. This guide explains how to achieve this by subscribing to real-time flag updates.
+
+## Prerequisites
+
+- Real-time flag updates require an Enterprise subscription.
+- Real-time flag updates are only available on the public SaaS Flagsmith instance. Self-hosted and private cloud Flagsmith installations do not support real-time flag updates.
+
+## Setup
+
+To enable real-time flag updates for your Flagsmith project:
+
+1. Log in to the Flagsmith dashboard as a user with project administrator permissions.
+2. Navigate to **Project Settings > SDK Settings**.
+3. Enable **Real-time updates**.
+
+By default, applications using a supported Flagsmith SDK do not subscribe to real-time flag updates. Refer to your SDK's documentation for subscribing to real-time flag updates.
+
+## How it works
+
+The following sequence diagram shows how a typical application would use real-time flag updates. [Billable API requests](/billing) are highlighted in yellow.
+
+```mermaid
+sequenceDiagram
+    rect rgb(255,245,173)
+        Application->>Flagsmith: Fetch initial flags
+        Flagsmith->>Application: #nbsp
+    end
+    Application->>Flagsmith: Connect to update stream
+    Flagsmith->>Application: #nbsp
+    Flagsmith Administrator->>Flagsmith: Update flag state
+    Flagsmith->>Flagsmith Administrator: #nbsp
+    Flagsmith-->>Application: Flag update event
+    rect rgb(255,245,173)
+        Application->>Flagsmith: Fetch latest flags
+        Flagsmith->>Application: #nbsp
+    end
+    Application-->Application: Store latest update timestamp
+```
+
+Your application subscribes to real-time flag updates by opening a long-lived [server-sent events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) connection to Flagsmith, which is specific to its current environment.
+
+When the environment is updated in some way, either via the Flagsmith dashboard or the [Admin API](/clients/rest#private-admin-api-endpoints), all clients connected to that environment's real-time stream will receive a message containing the latest update's timestamp. If your application's latest flags are older than the received timestamp, it requests the latest flags from Flagsmith. When your application receives the latest flags, you must propagate the latest flag state throughout your application as necessary.
+
+## Limitations
+
+Real-time flag update events only contain a timestamp indicating when any flag in the environment was last updated. Applications must still call the Flagsmith API to get the actual flags for their current environment or user.
+
+Only changes made to environments or projects result in flag update events. For example, the following operations will cause updates to be sent:
+
+- Manually toggling a flag on or off, or changing its value.
+- A [scheduled Change Request](/advanced-use/scheduled-flags) for a feature goes live.
+- Creating or updating segment overrides for a feature.
+- Changing a segment definition.
+
+Identity-level operations _will not_ cause updates to be sent:
+
+- Updating an identity's traits.
+- Creating or updating an identity override.
+
+The following SDK clients support subscribing to real-time flag updates:
+
+- JavaScript
+- Android
+- iOS
+- Flutter
+- Python
+- Ruby
+
+## Implementation details
+
+The event source URL used by Flagsmith SDKs is:
+
+```
+https://realtime.flagsmith.com/sse/environments/ENVIRONMENT_ID/stream
+```
+
+Each real-time flag event message is a JSON object containing a Unix epoch timestamp of the environment's last update:
+
+```json
+{
+  "updated_at": 3133690620000
+}
+```
+
+You can test real-time flag updates by using cURL to connect to the event source URL:
+
+```
+curl -H 'Accept: text/event-stream' -N -i https://realtime.flagsmith.com/sse/environments/ENVIRONMENT_ID/stream
+```
+
+## What's next?
+
+- [Efficient API Usage](/guides-and-examples/efficient-api-usage) – Tips for reducing API calls and making the most of your integration.
+- [Edge Proxy](/performance/edge-proxy) – Run the Flagsmith engine closer to your infrastructure for even lower latency.
+- [Integration Approaches](/guides-and-examples/integration-approaches) – Explore different ways to integrate Flagsmith into your applications.