Evaluation Proxy
Beta Resources
GitHub · Releases · Docker Image · Helm Chart
The Evaluation Proxy is a Service to enable, enhance, and optimize local evaluation running within your infrastructure.
Enable local evaluation on unsupported platforms:
Use remote Evaluation APIs and SDKs to run local evaluation in your infrastructure.
Automatically track assignment events for local evaluations:
Identical assignment events are deduplicated for 24 hours.
Enhance local evaluation with large cohort targeting:
Targeted cohorts are synced hourly to the Evaluation Proxy and added to the user prior to evaluation.
Configuration¶
The evaluation proxy is either configured via a YAML file (recommended, more configuration options), or using environment variables.
The default location for the configuration YAML file is /etc/evaluation-proxy-config.yaml
. You may also configure the file location using the PROXY_CONFIG_FILE_PATH
environment variable.
The configuration YAML file base is an object with two primary sub objects:
projects
(required)configuration
(optional).
Recommended configuration
Replace the fields in the configuration with values specific to your account/infrastructure.
projects:
- id: "YOUR PROJECT ID"
apiKey: "YOUR API KEY"
secretKey: " YOUR SECRET KEY"
deploymentKeys:
- "YOUR DEPLOYMENT KEY 1"
- "YOUR DEPLOYMENT KEY 2"
configuration:
redis:
uri: "YOUR REDIS URI" # e.g. "redis://localhost:6379"
Environment variable configuration (click to open)
Environment configuration can only configure a single deployment within a single project. Environment variable configuration is only considered if the configuration file is not found.
Environment Variable | Description |
---|---|
AMPLITUDE_PROJECT_ID |
The project's ID. Found in the project settings. |
AMPLITUDE_API_KEY |
The project's API key. |
AMPLITUDE_SECRET_KEY |
The project's secret key. |
AMPLITUDE_EXPERIMENT_DEPLOYMENT_KEY |
The key for the deployment to manage. The deployment key must exist within the same project as the API and secret key. |
AMPLITUDE_REDIS_URI |
Optional. The entire URI to connect to Redis. Include the protocol, host, port, and optional username, password, and path (for example redis://localhost:6379 ). |
AMPLITUDE_REDIS_PREFIX |
Optional. The prefix to connect |
AMPLITUDE_SERVER_URL |
Optional. The server URL, including protocol and host, to fetch flags from. |
AMPLITUDE_COHORT_SERVER_URL |
Optional. The server URL, including protocol and host, to download cohorts from. |
Field | Type | Description |
---|---|---|
projects |
array | Required. See projects . |
configuration |
object | Optional. See configuration |
projects
¶
A required array of objects with the following fields, all which are required.
Field |
Description |
---|---|
id |
The project's ID. Found in the project settings. |
apiKey |
The project's API key. |
secretKey |
The project's secret key. |
deploymentKeys |
The keys of the deployments to manage within the project. The deployment keys must exist within the same project as the API and secret key. |
configuration
¶
An optional object of extra configuration.
Field |
Description |
---|---|
redis |
Optional (Recommended). See redis . Configure the proxy to use redis as persistent storage. |
flagSyncIntervalMillis |
Optional. The polling interval to update flag configurations (default 10000 ). |
maxCohortSize |
Optional. The maximum size of targeted cohorts that the proxy can download (default 2147483647 ). |
serverUrl |
Optional. The server URL, including protocol and host, to fetch flags from. (default https://api.lab.amplitude.com ) |
cohortServerUrl |
Optional. The server URL, including protocol and host, to download cohorts from. (default https://cohort.lab.amplitude.com ) |
EU Data Residency
To use the evaluation proxy with the EU data center, set the serverUrl
and cohortServerUrl
configurations to hit the EU data center endpoints:
configuration:
# Other configurations...
serverUrl: "https://api.lab.eu.amplitude.com"
cohortServerUrl: "https://cohort.lab.eu.amplitude.com"
redis
¶
Configure the evaluation proxy to use Redis as a persistent storage. Highly recommended to enable the evaluation proxy to run efficiently.
Field |
Description |
---|---|
uri |
Required. The full URI to connect to Redis with. Include the protocol, host, port, and optional username, password, and path. |
readOnlyUri |
Optional. Optional URI to connect to read only replicas for high scaling high volume reads to Redis read replicas. |
prefix |
Optional. A prefix for all keys saved by the evaluation proxy (default amplitude ). |
Deployment¶
The evaluation proxy is stateless, and should be deployed with multiple instances behind a load balancer for high availability and scalability. For example, a kubernetes deployment with greater than one replica.
Kubernetes¶
Use the evaluation proxy Helm chart to install the proxy service on kubernetes or generate the files needed to deploy the service manually. The repository also contains an example of running the evaluation proxy on kubernetes locally using minikube
.
Add helm repo¶
helm repo add \
evaluation-proxy-helm https://amplitude.github.io/evaluation-proxy-helm
Configure values.yaml
¶
Configure the chart values. The recommended approach to configuring and installing the helm chart is using a values.yaml configuration file.
The chart's evaluationProxy
value contents exactly match the evaluation proxy's configuration file fields.
evaluationProxy:
# At least one project is required.
projects:
- id: "TODO"
apiKey: "TODO"
secretKey: "TODO"
deploymentKeys:
- "TODO"
configuration: {}
# redis:
# uri: "redis://redis-master.default.svc.cluster.local:6379"
Install helm chart¶
helm install -f values.yaml \
evaluation-proxy evaluation-proxy-helm/evaluation-proxy
Docker¶
You may run the docker image directly. First, create a configuration file, then run the docker image mounting the file as a volume to the expected directory in the container.
docker run \
-v CONFIG_FILE_PATH:/etc/evaluation-proxy-config.yaml \
amplitudeinc/evaluation-proxy
Docker compose example
The evaluation-proxy GitHub repository also contains an example using docker compose
to run the proxy alongside a local Redis image.
Evaluation¶
The Evaluation Proxy exposes remote Evaluation API and SDK endpoints to run local evaluation within your cluster. This is useful to enable platforms and languages which aren't supported by local evaluation SDKs. As an added benefit, fetch requests made to the evaluation proxy can target cohorts of users, and have assignment events tracked automatically to Amplitude.
Requests must be sent to the service using http
on port 3546
.
Kubernetes
A Kubernetes deployed Evaluation Proxy service (named evaluation-proxy
) running within a kubernetes namespace prod
may be accessed from within the cluster at: http://evaluation-proxy.prod.svc.cluster.local:3546
SDK proxy mode¶
Certain local evaluation SDKs are configurable to run in proxy mode. In proxy mode, flag configurations, full cohorts, and cohort memberships are synced from the evaluation proxy rather than from Amplitude directly. This reduces SDK startup time and provides redundancy for flags and cohorts for local evaluation SDKs running within your infrastructure.
SDK | Proxy Mode Support | Supported Version |
---|---|---|
Java/Kotlin | 1.2.0-beta.3 |
|
Node.js | - | |
Ruby | - | |
Go | - | |
Python | - |