Experiment Evaluation Proxy

Beta

The evaluation proxy is under active development. APIs are unstable and may change before general availability.

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.

Recommended configuration

Replace the fields in the configuration with values specific to your account/infrastructure.

1projects:
2 - apiKey: "YOUR API KEY"
3 secretKey: "YOUR SECRET KEY"
4 managementKey: "YOUR MANAGEMENT API KEY"
5 
6configuration:
7 redis:
8 uri: "YOUR REDIS URI" # e.g. "redis://localhost:6379"

Environment configuration can only configure a single project. Environment variable configuration is only considered if the configuration file is not found.

Environment Variable Description
AMPLITUDE_API_KEY The project's API key.
AMPLITUDE_SECRET_KEY The project's secret key.
AMPLITUDE_EXPERIMENT_MANAGEMENT_API_KEY The Experiment management API key. Must be created for the same project as the configured API and secret key. Used to automatically access and update deployments used for the project.
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.
managementKey The Experiment management API key. Must be created for the same project as the configured API and secret key. Used to automatically access and update deployments used for the project.

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:

1configuration:
2 # Other configurations...
3 serverUrl: "https://api.lab.eu.amplitude.com"
4 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.

Helm

Add helm repo
1helm repo add \
2 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.

1evaluationProxy:
2 # At least one project is required.
3 projects:
4 - apiKey: "YOUR API KEY"
5 secretKey: "YOUR SECRET KEY"
6 managementKey: "YOUR MANAGEMENT API KEY"
7 configuration: {}
8# redis:
9# uri: "redis://redis-master.default.svc.cluster.local:6379"
Install helm chart
1helm install -f values.yaml \
2 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.

1docker run \
2 -v CONFIG_FILE_PATH:/etc/evaluation-proxy-config.yaml \
3 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.

You must send requests to the service using http on port 3546.

Kubernetes

A Kubernetes deployed Evaluation Proxy service (named evaluation-proxy) running within a kubernetes namespace main is from within the cluster at: http://evaluation-proxy.main.svc.cluster.local:3546

Was this page helpful?

Thanks for your feedback!

June 4th, 2024

Need help? Contact Support

Visit Amplitude.com

Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.