By default, Split’s SDKs keep segment and split data synchronized as users navigate across disparate systems, treatments, and conditions. However, some languages, do not have a native capability to keep a shared local cache of this data to properly serve treatments. For these cases, we built the Split Synchronizer service.
Split synchronizer can run in two different modes:
- Synchronizer mode (default): Coordinates the sending and receiving of data to a remote datastore that all of your processes can share to pull data for the evaluation of treatments. Out of the box, Split supports Redis as a remote datastore, and so the Split Synchronizer uses Redis as the cache for your SDKs when evaluating treatments. It also posts impression data and metrics generated by the SDKs back to Split’s servers, for exposure in the web console or sending to the data integration of your choice.
- Proxy mode: Use proxy mode to reduce connection latencies from the SDKs to the Split server in a way that is completely transparent to the SDKs and when a single connection from a private network to the oustide is required for security reasons.
The Synchronizer service runs as a standalone process in dedicated or shared servers and it does not affect the performance of your code, or Split’s SDKs.
Split Synchronizer version 2.0 available!
Since version 2.0.0 of the split-synchronizer, we use a more efficient scheme to store impressions in redis. This approach is faster and easier on your redis instances, since it yields better throughput of impressions to the backend.
In order to use this feature you will need the newest versions of our SDKs, but to ease the migration process, Split-Sync 2.0 is backwards compatible by default with older versions of the SDK. However as long as this backwards-compatibility is enabled, you will not be able to enjoy the new performance boost. It is recommended that once you're using SDK versions compatible with Split-Sync 2.0 on all your applications pointing to the redis instance maintained by the Split-Sync, you disable backards compatibility (this is as easy as changing a parameter to true on the JSON config or an environment variable to on if you're using the docker image). Since version 3.0.0 we removed backwards compatibility.
Currently, the SDKs supported by this versions are:
Ruby 6.0.0
PHP 6.0.0
Node.js 10.6.0
GO 3.0.0
Python 7.0.0
.NET 4.0.0
Supported SDKs
The Split Synchronizer works with most of the languages that Split supports.
- PHP SDK
- Python SDK
- .NET SDK
- Node.js SDK
- Ruby SDK
- GO SDK
- Java SDK (Proxy mode only)
If you are looking for a language that is not listed here, contact the support team at support@split.io to discuss your options.
Overall Architecture
The service performs five actions:
- Fetch splits: Retrieve the split definitions.
- Fetch segments: Retrieve your set segments lists.
- Post impressions: Send to Split servers the generated impressions by the SDK.
- Post metrics: Send to Split servers different metrics of the SDK, such as latencies.
- Post events: Send to Split servers the generated events by the SDK
.track
method.
Synchronizer mode
Proxy mode
Setup
Docker (recommended)
The service is available via Docker or command line and its source code is available at https://github.com/splitio/split-synchronizer.
- Pull the image:
docker pull splitsoftware/split-synchronizer
- Run as:
docker run --rm --name split-synchronizer \
-p 3010:3010 \
-e SPLIT_SYNC_API_KEY="your-sdk-api-key" \
-e SPLIT_SYNC_REDIS_HOST=<your-redis-host> \
-e SPLIT_SYNC_REDIS_PORT=<your_redis_port> \
splitsoftware/split-synchronizer
docker run --rm --name split-synchronizer \
-p 3010:3010 \
-e SPLIT_SYNC_API_KEY="your-api-key" \
-e SPLIT_SYNC_REDIS_SENTINEL_REPLICATION="on" \
-e SPLIT_SYNC_REDIS_SENTINEL_MASTER="MASTER_SERVICE_NAME" \
-e SPLIT_SYNC_REDIS_SENTINEL_ADDRESSES="SENTINEL_HOST_1:SENTINEL_PORT_1,SENTINEL_HOST_2:SENTINEL_PORT_2" \
splitsoftware/split-synchronizer
docker run --rm --name split-synchronizer \
-p 3010:3010 \
-e SPLIT_SYNC_API_KEY="your-api-key" \
-e SPLIT_SYNC_REDIS_CLUSTER_MODE="on" \
-e SPLIT_SYNC_REDIS_CLUSTER_NODES="CLUSTER_NODE_1:CLUSTER_PORT_1,CLUSTER_NODE_2:CLUSTER_PORT_2,CLUSTER_NODE_3:CLUSTER_PORT_3" \
splitsoftware/split-synchronizer
docker run --rm --name split-synchronizer-proxy \
-p 3000:3000 \
-p 3010:3010 \
-e SPLIT_SYNC_API_KEY="your-api-key" \
-e SPLIT_SYNC_PROXY="on" \
-e SPLIT_SYNC_PROXY_SDK_APIKEYS="123456,qwerty" \
splitsoftware/split-synchronizer
Synchronizer mode with local redis instance
Sometimes, when building POCs or testing the synchronizer locally, you might want to launch our docker container image, pointing to a local redis server (or another container with redis, whose port has been mapped to a local one). In such case, you should consider adding the option --network="host"
(appending it to the command shown above) when launching the synchronizer. This will allow you to use -e SPLIT_SYNC_REDIS_HOST="localhost"
, with the split-synchronizer container properly reaching your local redis server.
Docker configuration
The Advanced configuration section includes additional Docker information in the column Docker environment variable.
Command line
To install and run the service from command line, follow the steps below depending of your platform.
Linux
On Linux systems, the Synchronizer service install script is invoked with this.
curl -L -o install_linux.bin http://downloads.split.io/synchronizer/install_linux.bin && chmod 755 install_linux.bin && ./install_linux.bin
OSX
On OSX systems, the Synchronizer service install script is invoked with this.
curl -L -o install_osx.bin http://downloads.split.io/synchronizer/install_osx.bin && chmod 755 install_osx.bin && ./install_osx.bin
Windows
On Microsoft Windows systems, follow these steps:
-
Download the app from http://downloads.split.io/synchronizer/split-sync-win.zip.
-
Unzip the downloaded file.
-
Run it!
Download previous versions
The links above point to the latest version. To download a previous version of split-sync, go to http://downloads.split.io/synchronizer/versions.html.
Run the service
To run the service, paste the snippet below into your command line terminal and add in your API-Key.
Linux/Mac
split-sync -api-key "split_sdk_api_key"
split-sync -api-key "your_api_key" -proxy -proxy-apikeys "sdk_api_key_1,sdk_api_key_2"
Windows
Open the cmd terminal or the PowerShell terminal, go to (cd) unzipped Split Synchronizer folder, and type:
split-sync.exe -api-key "split_sdk_api_key"
split-sync.exe -api-key "your_api_key" -proxy -proxy-apikeys "sdk_api_key_1,sdk_api_key_2"
Redis instance
On the samples above, Redis is running as a local service with default host: localhost and default port: 6379. For further information, see Advanced configuration.
Redis database
To maximize performance and isolation, we recommend connecting to a Redis database dedicated to the Split Synchronizer. For further information, see Advanced configuration.
Redis Sentinel support
Split Synchronizer also supports Redis Sentinel (v2) replication. For further information about Redis Sentinel, refer to the Sentinel Documentation.
Redis Cluster support
Split Synchronizer supports Redis Cluster with Redis^3.0.0. For further information about Redis Cluster, refer to the Cluster Documentation.
Recommended configuration for production
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 synchronizer via supervisord, a daemon that launches other processes and ensures they stay running.
To use supervisord, make sure that it is installed on your machine. You can get help on the installation at the official Supervisord documentation.
When supervisord is installed into your project, copy and paste the program below anywhere into the supervisord.conf
file that should now be in your project.
[program:splitio_sync]
command=/usr/local/bin/split-sync -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 Synchronizer service has a number of 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, Redis, and logging.
The splitio.config.json
file provided via the -config
option lets you control how often the synchronizer fetches data from Split servers. You can create a sample JSON file automatically with default values by running this command.
./split-sync -write-default-config "/home/someuser/splitio.config.json"
Configuration path file
Save the JSON config file on your server in your desired folder. For instance, on Linux systems, it could be saved in the etc
folder.
Remember to set the right path as the -config
parameter.
{
"apiKey": "YOUR API KEY",
"proxy": {
"port": 3000,
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": "",
"persistInFilePath": "",
"impressionsMaxSize": 10485760,
"eventsMaxSize": 10485760,
"auth": {
"sdkAPIKeys": [
"SDK_API_KEY"
]
}
},
"redis": {
"host": "localhost",
"port": 6379,
"db": 0,
"password": "",
"prefix": "",
"network": "tcp",
"maxRetries": 0,
"dialTimeout": 5,
"readTimeout": 10,
"writeTimeout": 5,
"poolSize": 10
},
"sync": {
"admin": {
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": ""
}
},
"log": {
"verbose": false,
"debug": false,
"stdout": false,
"file": "/tmp/split-agent.log",
"fileMaxSizeBytes": 2000000,
"fileBackupCount": 3,
"slackChannel": "",
"slackWebhookURL": ""
},
"impressionListener": {
"endpoint": ""
},
"splitsRefreshRate": 60,
"segmentsRefreshRate": 60,
"impressionsPostRate": 20,
"impressionsPerPost": 5000,
"impressionsThreads": 1,
"eventsPostRate": 60,
"eventsPerPost": 10000,
"eventsThreads": 1,
"metricsPostRate": 60,
"httpTimeout": 60
}
{
"apiKey": "YOUR API KEY",
"proxy": {
"port": 3000,
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": "",
"persistInFilePath": "",
"impressionsMaxSize": 10485760,
"eventsMaxSize": 10485760,
"auth": {
"sdkAPIKeys": [
"SDK_API_KEY"
]
}
},
"redis": {
"prefix": "",
"sentinelReplication": true,
"sentinelMaster": "MASTER_SERVICE_NAME",
"sentinelAddresses": "SENTINEL_HOST_1:SENTINEL_PORT_1, SENTINEL_HOST_2:SENTINEL_PORT_2,SENTINEL_HOST_3:SENTINEL_PORT_3"
},
"sync": {
"admin": {
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": ""
}
},
"log": {
"verbose": false,
"debug": false,
"stdout": false,
"file": "/tmp/split-agent.log",
"fileMaxSizeBytes": 2000000,
"fileBackupCount": 3,
"slackChannel": "",
"slackWebhookURL": ""
},
"impressionListener": {
"endpoint": ""
},
"splitsRefreshRate": 60,
"segmentsRefreshRate": 60,
"impressionsPostRate": 60,
"impressionsPerPost": 1000,
"impressionsThreads": 1,
"eventsPostRate": 60,
"eventsPerPost": 10000,
"eventsThreads": 1,
"metricsPostRate": 60,
"httpTimeout": 60
}
{
"apiKey": "YOUR API KEY",
"proxy": {
"port": 3000,
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": "",
"persistInFilePath": "",
"impressionsMaxSize": 10485760,
"eventsMaxSize": 10485760,
"auth": {
"sdkAPIKeys": [
"SDK_API_KEY"
]
}
},
"redis": {
"prefix": "",
"clusterMode": true,
"clusterNodes": "CLUSTER_NODE_1:CLUSTER_PORT_1, CLUSTER_NODE_2:CLUSTER_PORT_2,CLUSTER_NODE_3:CLUSTER_PORT_3"
},
"sync": {
"admin": {
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": ""
}
},
"log": {
"verbose": false,
"debug": false,
"stdout": false,
"file": "/tmp/split-agent.log",
"fileMaxSizeBytes": 2000000,
"fileBackupCount": 3,
"slackChannel": "",
"slackWebhookURL": ""
},
"impressionListener": {
"endpoint": ""
},
"splitsRefreshRate": 60,
"segmentsRefreshRate": 60,
"impressionsPostRate": 60,
"impressionsPerPost": 1000,
"impressionsThreads": 1,
"eventsPostRate": 60,
"eventsPerPost": 10000,
"eventsThreads": 1,
"metricsPostRate": 60,
"httpTimeout": 60
}
Command line parameters
All the options available 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 service
You can configure the Split synchronizer service 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. See a sample below for how to do that via command line.
split-sync -config "/etc/splitio.config.json" -log-debug -redis-pass "somePass"
Common configuration (synchronizer and proxy mode)
JSON field | CLI parameter | Docker environment variable | Type | Default value | Description |
---|---|---|---|---|---|
apiKey | -api-key | SPLIT_SYNC_API_KEY | string | None | Split SDK API Key. |
splitsRefreshRate | -split-refresh-rate | SPLIT_SYNC_SPLITS_REFRESH_RATE | int | 5 | Refresh rate of splits fetcher. The value is expressed in seconds. |
segmentsRefreshRate | -segment-refresh-rate | SPLIT_SYNC_SEGMENTS_REFRESH_RATE | int | 60 | Refresh rate of segments fetcher. The value is expressed in seconds. |
metricsPostRate | -metrics-post-rate | SPLIT_SYNC_METRICS_POST_RATE | int | 60 | Post rate of metrics recorder. The value is expressed in seconds. |
impressionsPostRate | -impressions-post-rate | SPLIT_SYNC_IMPRESSIONS_POST_RATE | int | 60 | Post rate of impressions recorder. The value is expressed in seconds. |
httpTimeout | http-timeout | SPLIT_SYNC_HTTP_TIMEOUT | int | 60 | Timeout specifies a time limit for requests. The timeout includes connection time, any redirects, and reading the response body. |
endpoint | impression-listener-endpoint | SPLIT_SYNC_IMPRESSION_LISTENER_ENDPOINT | - | - | - |
eventsPostRate | events-post-rate | SPLIT_SYNC_EVENTS_POST_RATE | int | 60 | Post rate of event recorder (seconds) |
IPAddressesEnabled | ip-addresses-enabled | SPLIT_SYNC_IP_ADDRESSES_ENABLED | bool/flag | true | Flag to disable IP addresses and host name from being sent to the Split backend. |
streamingEnabled | streaming-enabled | SPLIT_SYNC_STREAMING_ENABLED | bool/flag | true | Boolean flag to enable the streaming service as default synchronization mechanism. In the event of an issue with streaming, the SDK will fallback to the polling mechanism. If false, the SDK will poll for changes as usual without attempting to use streaming. |
impressionsMode | impressions-mode | SPLIT_SYNC_IMPRESSIONS_MODE | string | optimized |
This configuration defines how impressions are queued on the SDK. Supported modes are OPTIMIZED and DEBUG. In OPTIMIZED mode, only unique impressions are queued and posted to Split. In DEBUG mode, ALL impressions are queued and sent to Split. Use DEBUG mode when you want every impression to be logged in Split's webconsole when trying to debug your SDK setup. This setting does not impact the impression listener which will receives all generated impressions. |
Impressions throughput tuning
Depending on the number of impressions your application generates per time unit, you might need to update the configuration of the Split Synchronizer to make sure that it can handle the load and that impressions don't start accumulating on the synchronizer's storage. Use the options impressionsPostRate
, impressionsPerPost
, and impressionsThreads
.
Synchronizer configuration
The Synchronizer mode adds four new parameters to post impressions and events accurately and for its Redis dependency.
JSON field | CLI parameter | Docker environment variable | Type | Default value | Description |
---|---|---|---|---|---|
impressionsPerPost | -impressions-per-post | SPLIT_SYNC_IMPRESSIONS_PER_POST | int | 50000 | Number of impressions to send in a POST request |
impressionsThreads | -impressions-threads | SPLIT_SYNC_IMPRESSIONS_THREADS | int | 1 | Number of threads to post impressions in parallel |
eventsPerPost | -events-per-post | SPLIT_SYNC_EVENTS_PER_POST | int | 10000 | Number of events to send in a POST request |
eventsThreads | -events-threads | SPLIT_SYNC_EVENTS_THREADS | int | 1 | Number of threads to post events in parallel |
Configure Redis
Custom set Redis parameters by plugging them into the Redis section in the JSON configuration file or as command line parameters.
JSON field | CLI parameter | Docker environment variable | Type | Default value | Description |
---|---|---|---|---|---|
host | -redis-host | SPLIT_SYNC_REDIS_HOST | string | localhost | Redis instance server host. Could be IP address or hostname |
port | -redis-port | SPLIT_SYNC_REDIS_PORT | int | 6379 | Redis instance server port |
db | -redis-db | SPLIT_SYNC_REDIS_DB | int | 0 | Database to be selected after connecting to the server |
password | -redis-pass | SPLIT_SYNC_REDIS_PASS | string | Optional password | |
prefix | -redis-prefix | SPLIT_SYNC_REDIS_PREFIX | string | Optional prefix to set with keys | |
network | -redis-network | * | string | tcp | The network type, either tcp or unix |
maxRetries | -redis-max-retries | * | int | 0 | Maximum number of retries before giving up. Default is to not retry failed commands |
dialTimeout | -redis-dial-timeout | * | int | 5 | Dial timeout for establishing new connections |
readTimeout | -redis-read-timeout | * | int | 10 | Timeout for socket reads. If reached, commands will fail with a timeout instead of blocking |
writeTimeout | -redis-write-timeout | * | int | 5 | Timeout for socket writes. If reached, commands will fail with a timeout instead of blocking |
poolSize | -redis-pool | * | int | 10 | Maximum number of socket connections |
enableTLS | redis-tls | SPLIT_SYNC_REDIS_TLS | bool/flag | false | Enable encrypted connections to redis |
tlsServerName | redis-tls-server-name | SPLIT_SYNC_REDIS_TLS_SERVER_NAME | string | Name of the redis server as it appears in the server certificate (defaults to the host) | |
tlsSkipNameValidation | redis-tls-skip-name-validation | SPLIT_SYNC_REDIS_TLS_SKIP_NAME_VALIDATION | bool/flag | false | Don't check the server name in the received certificate |
caCertificates | redis-tls-ca-certs | SPLIT_SYNC_REDIS_TLS_CA_ROOT_CERTS | string | Comma-separated list of CA root certificate file names | |
tlsClientKey | redis-tls-client-key | SPLIT_SYNC_REDIS_TLS_CLIENT_KEY | string | Path to the client's PEM-encoded private key | |
tlsClientCertificate | redis-tls-client-certificate | SPLIT_SYNC_REDIS_TLS_CLIENT_CERTIFICATE | string | Path to the client's certificate with a signed public key | |
forceFreshStartup | force-fresh-startup | SPLIT_SYNC_REDIS_FORCE_CLEANUP | bool/flag | false | Wipe all data (honouring specified prefix) prior to starting. |
Configure Redis Sentinel
Custom set Redis Sentinel parameters by plugging them in to the Redis section in the JSON configuration file or as command line parameters (you can add the others parameter options listed in previous section without considering host
and port
).
JSON field | CLI parameter | Docker environment variable |
---|---|---|
sentinelReplication | -redis-sentinel-replication | SPLIT_SYNC_REDIS_SENTINEL_REPLICATION |
sentinelMaster | -redis-sentinel-master | SPLIT_SYNC_REDIS_SENTINEL_MASTER |
sentinelAddresses | -redis-sentinel-addresses | SPLIT_SYNC_REDIS_SENTINEL_ADDRESSES |
Configuring Redis Cluster
Custom set Redis Cluster parameters by plugging them in to the Redis section in the JSON configuration file or as command line parameters (you can add the others parameters options listed in previous section also without considering host
and port
).
JSON field | CLI parameter | Docker environment variable |
---|---|---|
clusterMode | -redis-cluster-mode | SPLIT_SYNC_REDIS_CLUSTER_MODE |
clusterNodes | -redis-cluster-nodes | SPLIT_SYNC_REDIS_CLUSTER_NODES |
keyHashTag | -redis-cluster-key-hashtag | SPLIT_SYNC_REDIS_CLUSTER_KEYHASHTAG |
Docker environment variable
Use the special environment variable SPLIT_SYNC_ADVANCED_PARAMETERS
to specify the Redis parameters above that do not have a Docker Env. variable
or additional configuration for the CLI.
For example: SPLIT_SYNC_ADVANCED_PARAMETERS="-redis-read-timeout=20 -redis-max-retries=10"
Proxy mode configuration
Set Synchronizer proxy mode parameters in the proxy section of the JSON file or as command line parameters.
JSON field | CLI parameter | Docker environment variable | Type | Default value | Description |
---|---|---|---|---|---|
port | -proxy-port | - | int | 3000 | Proxy port to listen connections. |
adminPort | -proxy-admin-port | - | int | 3010 | Proxy port for admin endpoints. |
adminUsername | -proxy-admin-userrname | SPLIT_SYNC_PROXY_ADMIN_USER | string | - | HTTP basic auth username for admin endpoints. |
adminPassword | -proxy-admin-password | SPLIT_SYNC_PROXY_ADMIN_PASS | string | - | HTTP basic auth password for admin endpoints. |
persistInFilePath | -proxy-mmap-path | - | string | - | File path to persist memory in proxy mode. |
impressionsMaxSize | -proxy-impressions-max-size | SPLIT_SYNC_PROXY_IMPRESSIONS_MAX_SIZE | int | 10485760 (10MB) | Max size, in bytes, to send impressions in proxy mode. |
sdkAPIKeys | -proxy-apikeys | SPLIT_SYNC_PROXY_SDK_APIKEYS | String list (string comma separated for CLI) | - | List of allowed custom API keys for SDKs to connect to Split Synchronizer, it can be any string of characters. |
eventsMaxSize | -proxy-events-max-size | SPLIT_SYNC_PROXY_EVENTS_MAX_SIZE | int | 10485760 (10MB) | Max size, in bytes, to send events in proxy mode |
proxy | -proxy | SPLIT_SYNC_PROXY | string | on | Parameter to turn on proxy mode. |
Docker exposed ports
The Split Synchronizer Docker image exposes both ports 3000
and 3010
. These ports can be mapped to your preferred host ports using the -p
option at the Docker run command.
Listener
The Split Synchronizer provides an impression listener that bulks post impressions to a user-defined HTTP endpoint.
The endpoint should expect a POST request, containing a JSON body with the following format.
{
"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": ""
}
Currently, the configuration options are available in the impressionListener
section of the JSON configuration file detailed in Advanced configuration.
Logging
Set the logging parameters in the log section of the JSON file or as command line parameters.
JSON field | CLI parameter | Docker environment variable | Type | Default value | Description |
---|---|---|---|---|---|
verbose | -log-verbose | SPLIT_SYNC_LOG_VERBOSE | bool/flag | false | Enable verbose mode. |
debug | -log-debug | SPLIT_SYNC_LOG_DEBUG | bool/flag | false | Enable debug mode. |
stdout | -log-stdout | SPLIT_SYNC_LOG_STDOUT | bool/flag | false | Enable log standard output. |
file | -log-file | SPLIT_SYNC_LOG_FILE | string | /tmp/split-agent.log | Set path to the log file. If file doesn't exist, it is created. |
fileMaxSizeBytes | -log-file-max-size | SPLIT_SYNC_LOG_FILE_MAX_SIZE | int | 2000000 (2MB) | Max file log size in bytes. |
fileBackupCount | -log-file-backup-count | SPLIT_SYNC_LOG_BACKUP_COUNT | int | 3 | Number of last log files to keep in filesystem after log rotation. |
slackChannel | -log-slack-channel | SPLIT_SYNC_LOG_SLACK_CHANNEL | string | Set the Slack channel or user to report a summary in realtime of ERROR log level. | |
slackWebhookURL | -log-slack-webhook-url | SPLIT_SYNC_LOG_SLACK_WEBHOOK | string | Set the Slack webhook URL to report a summary in realtime of ERROR log level. |
Log level
The ERROR log level is enabled by default and cannot be disabled. Only DEBUG and VERBOSE are configurable. Do not enable DEBUG and VERBOSE for production environments in order to prevent write larger log files.
Using a network proxy
If you need to use a network proxy, configure proxies by setting the environment variables HTTP_PROXY and HTTPS_PROXY. The internal HTTP client reads those variables and uses them to perform the server request.
$ export HTTP_PROXY="http://10.10.1.10:3128"
$ export HTTPS_PROXY="http://10.10.1.10:1080"
Admin tools
Endpoints
The split-sync
service has a set of endpoints and a dashboard to let DevOps and infra team monitor its status and cached data in real-time. By default the port is 3010
and for security reason supports HTTP Basic Authentication configured by the user.
/admin/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
.
/admin/version
Returns the split-sync
version in JSON format.
{
"version" : "1.1.0"
}
/admin/uptime
Returns the uptime string representation in JSON format.
{
"uptime" : "5d 3h 36m 39s"
}
/admin/stats
Returns stats, latencies, and counters of service behavior.
{
"counters" : {
"backend::request.ok" : 403760,
"request.error" : 303,
"request.ok" : 4530342
},
"latencies" : {
"/api/segmentChanges/*" : [
2317783,
36,
32,
773024,
7756,
252273,
20617,
9588,
9371,
4054,
580,
131,
14,
2,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
}
}
/admin/healthcheck
Returns a JSON object describing whether the synchronizer is healthy or not.
PROXY
{
"events": {
"healthy": true,
"message": "Events service working as expected"
},
"healthySince": {
"date": "07-18-2019 22:17:25",
"time": "0d 20h 28m 44s"
},
"sdk": {
"healthy": true,
"message": "SDK service working as expected"
},
"proxy" : {
"healthy" : true,
"message" : "Proxy service working as expected"
},
"uptime": "0d 20h 28m 44s"
}
SYNC
{
"events": {
"healthy": true,
"message": "Events service working as expected"
},
"healthySince": {
"date": "07-18-2019 22:17:25",
"time": "0d 20h 28m 44s"
},
"sdk": {
"healthy": true,
"message": "SDK service working as expected"
},
"storage": {
"healthy": true,
"message": "Storage service working as expected"
},
"sync": {
"healthy": true,
"message": "Synchronizer service working as expected"
},
"uptime": "0d 20h 28m 44s"
}
/admin/userConfig
Returns a JSON object describing the current configuration of the Synchronizer.
PROXY
{
"admin": {
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": "Title"
},
"apiKey": "2uae...r7na",
"eventsPerPost": 10000,
"eventsThreads": 1,
"eventsPostRate": 30,
"httpTimeout": 60,
"impressionListener": {
"endpoint": ""
},
"impressionsPerPost": 1000,
"impressionsPostRate": 30,
"impressionsThreads": 1,
"log": {
"verbose": false,
"debug": true,
"stdout": false,
"file": "",
"fileMaxSizeBytes": 2000000,
"fileBackupCount": 3,
"slackChannel": "slack-channel",
"slackWebhookURL": ""
},
"metricsPostRate": 360,
"mode": "ProxyMode",
"proxy": {
"port": 3000,
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": "",
"persistInFilePath": "",
"impressionsMaxSize": 10485760,
"eventsMaxSize": 10485760,
"auth": {
"sdkAPIKeys": [
"SDK_API_KEY"
]
}
},
"redis": null,
"redisMode": null,
"segmentsRefreshRate": 30,
"splitRefreshRate": 30
}
SYNC
{
"admin": {
"adminPort": 3010,
"adminUsername": "",
"adminPassword": "",
"dashboardTitle": "Title"
},
"apiKey": "2uae...r7na",
"eventsPerPost": 10000,
"eventsThreads": 1,
"eventsPostRate": 30,
"httpTimeout": 60,
"impressionListener": {
"endpoint": ""
},
"impressionsPerPost": 1000,
"impressionsPostRate": 30,
"impressionsThreads": 1,
"log": {
"verbose": false,
"debug": true,
"stdout": false,
"file": "",
"fileMaxSizeBytes": 2000000,
"fileBackupCount": 3,
"slackChannel": "slack-channel",
"slackWebhookURL": ""
},
"metricsPostRate": 360,
"mode": "ProducerMode",
"proxy": null,
"redis": {
"host": "localhost",
"port": 6379,
"db": 0,
"password": "",
"prefix": "{SPLITIO}test:",
"network": "tcp",
"maxRetries": 0,
"dialTimeout": 5,
"readTimeout": 10,
"writeTimeout": 5,
"poolSize": 10,
"sentinelReplication": false,
"sentinelAddresses": "",
"sentinelMaster": "",
"clusterMode": true,
"clusterNodes": "NODE1,NODE2,NODE3",
"keyHashTag": ""
},
"redisMode": "Cluster",
"segmentsRefreshRate": 30,
"splitRefreshRate": 30
}
SYNC Endpoints
/admin/events/queueSize & /admin/impressions/queueSize
Returns a JSON with the amount of elements stored in redis.
{
"queueSize": Number
}
/admin/events/drop & /admin/impressions/drop
Discard Events or Impressions
Method: POST
Data In
- Name size
Validation: 1..X
Optional
QueryParam
RESPONSE:
- 200 if no error occurs
- 400 if wrong size parameter is passed
- 5XX if server error
/admin/events/flush & /admin/impressions/flush
Flush Events or Impressions by sending them to the Split Servers
Method: POST
Data In
- Name size
Validation: 1..25000
Optional
QueryParam
RESPONSE:
- 200 if no error occurs
- 400 if wrong size parameter is passed
- 5XX if server error
Admin Dashboard
Split-sync has a web admin UI out of the box that exposes all available endpoints. Browse to /admin/dashboard
to see it.
Proxy Mode Main
Sync Mode Main
The dashboard is organized in four sections for ease of 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-sync and Split servers
- Cached Splits: Number of splits cached in memory
- Cached Segments: Number of segments cached in memory
- Impressions Queue Size: shows the total amount of Impressions stored in Redis (only Producer Mode).
- Impressions Lambda: shows the eviction rate for Impressions (only Producer Mode).
- Events Queue Size: shows the total amount of Events stored in Redis (only Producer Mode).
- Events Lambda: shows the eviction rate for Events (only Producer Mode).
- SDK Server: displays the status of Split Server for SDK.
- Events Server: displays the status of Split Server for Events.
- Storage: (only Sync mode) displays the status of the storage.
- Sync: displays the status of the Synchronizer.
- 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 Split servers.
- Data inspector: Cached data showing splits and segments; filters to find keys and split definitions.
- Queue Manager: expose sizes of Impressions and Events queues. Allows to drop/flush Events or Impressions. Displays the eviction rate for Impressions and Events.
Dashboard refresh rate
The dashboard numbers are committed every 60 seconds. The Logged Errors
, Last Errors Log
tiles, and the 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-sync
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 have configured a Slack channel and the Slack Webhook URL, see the Logging section. An alert is sent to the channel when and initialization or shutdown is performed.
Comments
1 comment
Can this be updated with more explicit instruction for disabling backwards compatibility for impressions storage?
This is described here "as easy as changing a parameter to true on the JSON config or an environment variable to on if you're using the docker image," but the parameter/environment variable is not specified. (I'm guessing that this is "disableLegacyImpressions," but shouldn't have to guess.)
Thanks.
Please sign in to leave a comment.