Skip to main content

Split Proxy

The Split Proxy enables you to deploy a service in your own infrastructure that behaves like Harness servers and is used by both server-side and client-side SDKs to synchronize the flags without connecting to Harness FME's actual backend directly.

This tool reduces connection latencies between the SDKs and Harness FME servers, and when a single connection is required from a private network to the outside for security reasons.

Architecture​

Setup​

The service is available via Docker or command line, and its source code is available at the split-synchronizer GitHub site.

  • Pull the image: docker pull splitsoftware/split-proxy
  • Run as:
Standard execution
docker run --rm --name split-proxy \
 -p 3000:3000 \
 -p 3010:3010 \
 -e SPLIT_PROXY_APIKEY="your-sdk-key" \
 -e SPLIT_PROXY_CLIENT_APIKEYS="123456,qwerty" \
 splitsoftware/split-proxy
API Keys

The SPLIT_PROXY_APIKEY is the server-side SDK API Key that you can find or create in Admin settings. The Split Proxy uses the SPLIT_PROXY_APIKEY to connect to Harness servers.

The SPLIT_PROXY_CLIENT_APIKEYS is a list of strings that the Split Proxy will use to authenticate a client. (A Split Proxy client is a client/server-side FME SDK instance that connects to Split Proxy.) The Split Proxy will validate the client by comparing the key the client provides with the strings listed in SPLIT_PROXY_CLIENT_APIKEYS. These keys can be any string, generated via any method of your choice. For example, you can generate a GUID or use the string "hello" (e.g. for initial setup and testing the connection). As long as the Proxy client supplies a string that is in the SPLIT_PROXY_CLIENT_APIKEYS list, the Proxy will accept the client and forward the request to Harness servers. The Split Proxy client (the client/server-side FME SDK instance) will supply a Split Proxy Client API Key in the usual place of the SDK Key.

Command line​

To install and run the service from command line, depending of your platform, follow the steps below:

Linux​

On Linux systems, invoke the Proxy service install script with the following:

Shell
curl -L -o install_linux.bin 'https://downloads.split.io/proxy/install_split_proxy_linux.bin' && chmod 755 install_linux.bin && ./install_linux.bin

OSX​

On OSX systems, invoke the Proxy service install script with the following:

Shell
curl -L -o install_osx.bin 'https://downloads.split.io/proxy/install_split_proxy_osx.bin' && chmod 755 install_osx.bin && ./install_osx.bin

Windows​

On Microsoft Windows systems, follow the steps below:

  1. Download the app from https://downloads.split.io/proxy/split_proxy_windows.zip.

  2. Unzip the downloaded file.

  3. Run it.

Download previous versions

The links above point to the latest version. To download a previous version of split-sync, go to https://downloads.split.io/proxy/downloads.proxy.html.

Run the service​

To run the service, paste the following snippet into your command line terminal and add your SDK key.

Linux/Mac​

Proxy
split-proxy -apikey "your_sdk_key" -client-apikeys "your_client_key_1,your_client_key_2"

Windows​

Open the cmd terminal or the PowerShell terminal, go to (cd) your unzipped Split Proxy folder, and type:

Proxy
split-proxy -apikey "your_sdk_key" -client-apikeys "your_client_key_1,your_client_key_2"

You can run the service with the simple steps above, but the system is more stable in your production environment when you run the job with a scheduling system. We recommend starting the Proxy using supervisord, a daemon that launches other processes and ensures they stay running.

To use supervisord, make sure you install it on your machine. You can get help on the installation at the official Supervisord documentation.

After you install supervisord into your project, copy and paste the program below anywhere into the supervisord.conf file that should now be in your project.

supervisord configuration file (sample)
[program:splitio_proxy]
command=/usr/local/bin/split-proxy -config /path/to/your/config.file.json
process_name = SplitIO
numprocs = 1
autostart=true
autorestart=true
user = your_user
stderr_logfile=/var/log/splitio.err.log
stderr_logfile_maxbytes = 1MB
stdout_logfile=/var/log/splitio.out.log
stdout_logfile_maxbytes = 1MB

Advanced configuration​

The Proxy service has several knobs for configuring performance. Each knob is tuned to a reasonable default. However, you can override the default values by changing a splitio.config.json file or by setting your customer values as parameters of -config in the command line option. In this section, we lay out all the different knobs you can configure for performance, persistent storage, and logging.

The splitio.config.json file provided using the -config option lets you control how often the synchronizer fetches data from Harness servers. You can create a sample JSON file automatically with default values by running the following command:

Shell
./split-proxy -write-default-config "/home/someuser/splitio.config.json"
Configuration path file

Save the JSON config file on your server in your desired folder. For example, on Linux systems, you can save it in the etc folder. Be sure to set the right path as the -config parameter.

splitio.config.json
{
  "apikey": "YOUR_SDK_KEY",
  "ipAddressEnabled": true,
  "initialization": {
    "timeoutMS": 10000,
    "snapshot": "",
    "forceFreshStartup": false
  },
  "server": {
    "apikeys": [
      "YOUR_SDK_KEY"
    ],
    "host": "0.0.0.0",
    "port": 3000,
    "httpCacheSize": 1000000
  },
  "admin": {
    "host": "0.0.0.0",
    "port": 3010,
    "username": "",
    "password": "",
    "secureChecks": false
  },
  "storage": {
    "volatile": {},
    "persistent": {
      "filename": ""
    }
  },
  "sync": {
    "splitRefreshRateMs": 60000,
    "segmentRefreshRateMs": 60000,
    "advanced": {
      "streamingEnabled": true,
      "httpTimeoutMs": 30000,
      "impressionsBufferSize": 500,
      "eventsBufferSize": 500,
      "telemetryBufferSize": 500,
      "impressionsWorkers": 10,
      "eventsWorkers": 10,
      "telemetryWorkers": 10,
      "internalTelemetryRateMs": 3600000
    }
  },
  "integrations": {
    "impressionListener": {
      "endpoint": "",
      "queueSize": 100
    },
    "slack": {
      "webhook": "",
      "channel": ""
    }
  },
  "logging": {
    "level": "info",
    "output": "stdout",
    "rotationMaxFiles": 10,
    "rotationMaxSizeKb": 0
  },
  "healthcheck": {
    "dependencies": {
      "dependenciesCheckRateMs": 3600000
    }
  }
}
Command line parameters

All available options in the JSON file are also included as command line options. Run the command followed by the -help option to see more details, or just keep reading this documentation page.

Methods to Configure the Split Proxy​

You can configure the Split Proxy using the command line or by directly editing the above mentioned JSON configuration file.

Config values priority

All config values are set with a default value that you can see in the example JSON file above. You can overwrite the default value from the JSON config file, and you can overwrite the JSON config file from the command line. Refer to the sample below for how to do that using the command line.

Shell
split-proxy -config "/etc/splitio.config.json" -log-level=info -admin-username="admin" -admin-password="somePass"

CLI Configuration options and its equivalents in JSON and Environment variables​

The following table includes the available command line, JSON, and environment variable options and their descriptions. It specifies configuration options for the Split Synchronizer. You can configure the synchronizer using command line arguments, environment variables when you run it as a docker container, and a JSON file when you run it locally. All of these configuration options can be used regardless of the configuration method.

Split Proxy v5.0 boolean options change

With the Split Synchronizer v5.0.0, the only accepted values for boolean flags are "true" and "false" in lowercase. Values such as "enabled", "on", "yes", or "True" result in an error when you start up. This applies to JSON, CLI arguments, and environment variables.

Command line optionJSON optionEnvironment variable (container-only)Description
log-levellevelSPLIT_PROXY_LOG_LEVELLog level (error|warning|info|debug|verbose).
log-outputoutputSPLIT_PROXY_LOG_OUTPUTWhere to output logs (defaults to stdout).
log-rotation-max-filesrotationMaxFilesSPLIT_PROXY_LOG_ROTATION_MAX_FILESMax number of files to keep when rotating logs.
log-rotation-max-size-kbrotationMaxSizeKbSPLIT_PROXY_LOG_ROTATION_MAX_SIZE_KBMax file size to keep before rotating log files.
admin-hosthostSPLIT_PROXY_ADMIN_HOSTHost where the admin server will listen.
admin-portportSPLIT_PROXY_ADMIN_PORTAdmin port where incoming connections will be accepted.
admin-usernameusernameSPLIT_PROXY_ADMIN_USERNAMEHTTP basic auth username for admin endpoints.
admin-passwordpasswordSPLIT_PROXY_ADMIN_PASSWORDHTTP basic auth password for admin endpoints.
admin-secure-hcsecureChecksSPLIT_PROXY_ADMIN_SECURE_HCSecure Healthcheck endpoints as well.
admin-tls-enabledenabledSPLIT_PROXY_ADMIN_TLS_ENABLEDEnable HTTPS on proxy endpoints.
admin-tls-client-validationclientValidationSPLIT_PROXY_ADMIN_TLS_CLIENT_VALIDATIONEnable client cert validation.
admin-tls-server-nameserverNameSPLIT_PROXY_ADMIN_TLS_SERVER_NAMEServer name as it appears in provided server-cert.
admin-tls-cert-chain-fncertChainFnSPLIT_PROXY_ADMIN_TLS_CERT_CHAIN_FNX509 Server certificate chain.
admin-tls-private-key-fnprivateKeyFnSPLIT_PROXY_ADMIN_TLS_PRIVATE_KEY_FNPEM Private key file name.
admin-tls-client-validation-root-certclientValidationRootCertFnSPLIT_PROXY_ADMIN_TLS_CLIENT_VALIDATION_ROOT_CERT.X509 root cert for client validation
admin-tls-min-tls-versionminTlsVersionSPLIT_PROXY_ADMIN_TLS_MIN_TLS_VERSIONMinimum TLS version to allow X.Y.
admin-tls-allowed-cipher-suitesallowedCipherSuitesSPLIT_PROXY_ADMIN_TLS_ALLOWED_CIPHER_SUITESComma-separated list of cipher suites to allow.
impression-listener-endpointendpointSPLIT_PROXY_IMPRESSION_LISTENER_ENDPOINTHTTP endpoint to forward impressions to.
impression-listener-queue-sizequeueSizeSPLIT_PROXY_IMPRESSION_LISTENER_QUEUE_SIZEmax number of impressions bulks to queue.
slack-webhookwebhookSPLIT_PROXY_SLACK_WEBHOOKslack webhook to post log messages.
slack-channelchannelSPLIT_PROXY_SLACK_CHANNELslack channel to post log messages.
apikeyapikeySPLIT_PROXY_APIKEYFME server-side SDK API key.
ip-address-enabledipAddressEnabledSPLIT_PROXY_IP_ADDRESS_ENABLEDBundle host's ip address when sending data to Harness FME.
timeout-mstimeoutMSSPLIT_PROXY_TIMEOUT_MSHow long to wait until the synchronizer is ready.
snapshotsnapshotSPLIT_PROXY_SNAPSHOTSnapshot file to use as a starting point.
force-fresh-startupforceFreshStartupSPLIT_PROXY_FORCE_FRESH_STARTUPWipe storage before starting the synchronizer
client-apikeysapikeysSPLIT_PROXY_CLIENT_APIKEYSApikeys that clients connecting to this Proxy will use.
server-hosthostSPLIT_PROXY_SERVER_HOSTHost/IP to start the proxy server on.
server-portportSPLIT_PROXY_SERVER_PORTPort to listen for incoming requests from SDKs.
server-tls-enabledenabledSPLIT_PROXY_SERVER_TLS_ENABLEDEnable HTTPS on proxy endpoints.
server-tls-client-validationclientValidationSPLIT_PROXY_SERVER_TLS_CLIENT_VALIDATIONEnable client cert validation.
server-tls-server-nameserverNameSPLIT_PROXY_SERVER_TLS_SERVER_NAMEServer name as it appears in provided server-cert.
server-tls-cert-chain-fncertChainFnSPLIT_PROXY_SERVER_TLS_CERT_CHAIN_FNX509 Server certificate chain.
server-tls-private-key-fnprivateKeyFnSPLIT_PROXY_SERVER_TLS_PRIVATE_KEY_FNPEM Private key file name.
server-tls-client-validation-root-certclientValidationRootCertFnSPLIT_PROXY_SERVER_TLS_CLIENT_VALIDATION_ROOT_CERTX509 root cert for client validation.
server-tls-min-tls-versionminTlsVersionSPLIT_PROXY_SERVER_TLS_MIN_TLS_VERSIONMinimum TLS version to allow X.Y.
server-tls-allowed-cipher-suitesallowedCipherSuitesSPLIT_PROXY_SERVER_TLS_ALLOWED_CIPHER_SUITESComma-separated list of cipher suites to allow.
http-cache-sizehttpCacheSizeSPLIT_PROXY_HTTP_CACHE_SIZEHow many responses to cache.
persistent-storage-fnfilenameSPLIT_PROXY_PERSISTENT_STORAGE_FNWhere to store flags and user-generated data. (Default: temporary file).
split-refresh-rate-mssplitRefreshRateMsSPLIT_PROXY_SPLIT_REFRESH_RATE_MSHow often to refresh feature flags.
segment-refresh-rate-mssegmentRefreshRateMsSPLIT_PROXY_SEGMENT_REFRESH_RATE_MSHow often to refresh segments.
streaming-enabledstreamingEnabledSPLIT_PROXY_STREAMING_ENABLEDEnable/disable streaming functionality.
http-timeout-mshttpTimeoutMsSPLIT_PROXY_HTTP_TIMEOUT_MSTotal http request timeout.
impressions-workersimpressionsWorkersSPLIT_PROXY_IMPRESSIONS_WORKERS#workers to forward impressions to Harness servers.
events-workerseventsWorkersSPLIT_PROXY_EVENTS_WORKERS#workers to forward events to Harness servers.
telemetry-workerstelemetryWorkersSPLIT_PROXY_TELEMETRY_WORKERS#workers to forward telemetry to Harness servers.
internal-metrics-rate-msinternalTelemetryRateMsSPLIT_PROXY_INTERNAL_METRICS_RATE_MSHow often to send internal metrics.
dependencies-check-rate-msdependenciesCheckRateMsSPLIT_PROXY_DEPENDENCIES_CHECK_RATE_MSHow often to check dependecies health.

Listener​

The Split Proxy provides an impression listener that bulks post impressions to a user-defined HTTP endpoint.

The endpoint should expect a POST request that contains a JSON body using the following format:

JSON Impression
{
 "impressions": [
  {
   "testName": "feature1",
   "keyImpressions": [
    {
     "keyName": "user1",
     "treatment": "on",
     "time": 1502754901182,
     "changeNumber": -1,
     "label": ""
    },
    {
     "keyName": "user2",
     "treatment": "off",
     "time": 1502754876144,
     "changeNumber": -1,
     "label": ""
    }
   ]
  }
 ],
 "sdkVersion": "php-5.2.2",
 "machineIP": "208.63.222.7",
 "MachineName": ""
}

The configuration options are available in the integrations.impressionListener section of the JSON configuration file detailed in Advanced configuration section.

Using a network proxy​

If you need to use a network proxy, configure the proxies by setting the environment variables as HTTP_PROXY and HTTPS_PROXY. The internal HTTP client reads those variables and uses them to perform a server request.

Example: Environment variables
$ export HTTP_PROXY="http://10.10.1.10:3128"
$ export HTTPS_PROXY="http://10.10.1.10:1080"

Admin tools​

Endpoints​

The split-proxy service has a set of endpoints and a dashboard that lets the DevOps and infra team monitor its status and cached data in real-time. By default, the port is 3010 and for security reason, it supports HTTP Basic Authentication configured by the user.

/info/ping

A ping endpoint to monitor the service status. If the service is running, it sends the text response pong and the HTTP status code 200.

/info/version

Returns the split-proxy version in JSON format.

{
  "version" : "1.1.0"
}

/info/uptime

Returns the uptime string representation in JSON format.

{
  "uptime" : "5d 3h 36m 39s"
}

/info/config

Returns a JSON object describing the current configuration of the proxy.

{
  "config": {
    "apikey": "*",
    "ipAddressEnabled": true,
    "initialization": {
      "timeoutMS": 10000,
      "snapshot": "",
      "forceFreshStartup": false
    },
    "server": {
      "apikeys": [
        "YOUR_SDK_KEY"
      ],
      "host": "0.0.0.0",
      "port": 3000,
      "httpCacheSize": 1000000
    },
    "admin": {
      "host": "0.0.0.0",
      "port": 3010,
      "username": "",
      "password": "",
      "secureChecks": false
    },
    "storage": {
      "volatile": {},
      "persistent": {
        "filename": ""
      }
    },
    "sync": {
      "splitRefreshRateMs": 60000,
      "segmentRefreshRateMs": 60000,
      "advanced": {
        "streamingEnabled": true,
        "httpTimeoutMs": 30000,
        "impressionsBufferSize": 500,
        "eventsBufferSize": 500,
        "telemetryBufferSize": 500,
        "impressionsWorkers": 10,
        "eventsWorkers": 10,
        "telemetryWorkers": 10,
        "internalTelemetryRateMs": 3600000
      }
    },
    "integrations": {
      "impressionListener": {
        "endpoint": "",
        "queueSize": 100
      },
      "slack": {
        "webhook": "",
        "channel": ""
      }
    },
    "logging": {
      "level": "info",
      "output": "stdout",
      "rotationMaxFiles": 10,
      "rotationMaxSizeKb": 0
    },
    "healthcheck": {
      "dependencies": {
        "dependenciesCheckRateMs": 3600000
      }
    }
  }
}

/health/application

Returns a JSON object describing whether the proxy is healthy or not.

{
  "healthy": true,
  "healthySince": "2021-11-20T19:17:23.372708-03:00",
  "items": [
    {
      "name": "Feature flags",
      "healthy": true,
      "lastHit": "2021-11-20T19:17:36.147349-03:00"
    },
    {
      "name": "Segments",
      "healthy": true,
      "lastHit": "2021-11-20T19:17:36.324172-03:00"
    }
  ]
}

/health/dependencies

Returns a JSON object describing whether the servers the proxy depends on are healthy or not.

{
  "serviceStatus": "healthy",
  "dependencies": [
    {
      "service": "https://telemetry.split.io/health",
      "healthy": true,
      "healthySince": "2021-11-20T19:17:23.372741-03:00"
    },
    {
      "service": "https://auth.split.io/health",
      "healthy": true,
      "healthySince": "2021-11-20T19:17:23.372752-03:00"
    },
    {
      "service": "https://sdk.split.io/api/version",
      "healthy": true,
      "healthySince": "2021-11-20T19:17:23.372753-03:00"
    },
    {
      "service": "https://events.split.io/api/version",
      "healthy": true,
      "healthySince": "2021-11-20T19:17:23.372755-03:00"
    },
    {
      "service": "https://streaming.split.io/health",
      "healthy": true,
      "healthySince": "2021-11-20T19:17:23.372755-03:00"
    }
  ]
}

/admin/snapshot

Returns a binary snapshot file that can be used with the snapshot environment variable or command line argument when starting up the Split Proxy.

Admin Dashboard​

Split Proxy has a web admin user interface out of the box that exposes all available endpoints. Browse to /admin/dashboard to see it.

The dashboard is organized into four sections for easy visualization:

  • Dashboard: Tile-sorted summary information, including these metrics:
    • Uptime: Uptime metric
    • Healthy Since: Time passed without errors
    • Logged Errors: Total count of error messages
    • SDKs Total Hits: Total SDKs requests
    • Backend Total Hits: Total backend requests between split-proxy and Harness servers
    • Cached Feature flags: Number of feature flags cached in memory
    • Cached Segments: Number of segments cached in memory
    • SDK Server: displays the status of server for SDK
    • Events Server: displays the status of server for Events
    • Streaming Server: displays the status of streaming service
    • Auth Server: displays the status of server for initial streaming authentication
    • Telemetry Server: displays the status of server for telemetry capturing
    • Storage: (only Sync mode) displays the status of the storage
    • Sync: displays the status of the Proxy
    • Last Errors Log: List of the last 10 error messages
  • SDK stats: Metrics numbers and a latency graph, measured between SDKs requests integration and proxy
  • Split stats: Metrics numbers and a latency graph, measured between proxy requests integration with Harness servers
  • Data inspector: Cached data showing feature flags and segments; filters to find keys and feature flag definitions

Dashboard refresh rate

The dashboard numbers are committed every 60 seconds. The Logged Errors, Last Errors Log tiles, and Data inspector section are populated each time the dashboard is refreshed.

For Impressions and Events Queue size, the numbers are refreshed every 10 seconds.

Service shutdown​

The split-proxy service can catch a kill sig command and start a graceful shutdown, flushing all cached data progressively. Additionally, you can perform graceful stop and force stop (kill -9) with one click from the admin dashboard.

If you configure a Slack channel and a Slack Webhook URL, an alert is sent to the channel when an initialization or shutdown is performed.