Skip to content

Evaluation Proxy


The Evaluation Proxy is a Service to enable, enhance, and optimize local evaluation running within your infrastructure.

Architectural diagram showing how the evaluation proxy interacts with your services and Amplitude.

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:

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.

values.yaml
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

docker image version

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 -

Was this page helpful?