Using Split involves using one of our SDKs. The Split team builds and maintains these SDKs for some of the most popular language libraries and the SDKs are available under open source licenses. For languages where there is no native SDK support, Split offers the Split Evaluator, a small service capable of evaluating some or all available features for a given customer via a REST endpoint.
Setup
The service is available via Docker or command line and its source code is available at https://github.com/splitio/split-evaluator.
Docker (recommended)
- Pull the image:
docker pull splitsoftware/split-evaluator
-
Run as:
docker run \
-e SPLIT_EVALUATOR_API_KEY={YOUR_SDK_TYPE_API_KEY} \
-p 7548:7548 splitsoftware/split-evaluator
Note
See the configuration section for details on port usage, specifically the use of the SPLIT_EVALUATOR_SERVER_PORT
environment variable.
Docker ports
In the example above, the service can be reached via curl using port 7548.
Command line
To install the service via command line:
- Clone the repository:
git clone https://github.com/splitio/split-evaluator
- Prepare the sources:
npm install
Previous Versions
Split Evaluator 2.0.0
is a breaking change. This version adds supports for all the APIs that our current SDKs have but be aware of using some deprecated APIs if you continue to use an older version of this service.
SPLIT_EVALUATOR_API_KEY=<YOUR_SDK_TYPE_API_KEY> \
SPLIT_EVALUATOR_AUTH_TOKEN=<YOUR_CUSTOM_AUTHENTICATION> \
npm start
Endpoints
The following section will describe the APIs that evaluator can manage. There are grouped in four different resources depending on what they want to achieve.
- Client: it corresponds to the APIs used to send impressions (get treatments) and track events.
- Manager: it corresponds to the APIs that will give you information of the available splits.
- Admin: it corresponds to the APIs that will give you information of the Split Evaluator itself.
- api-docs: it will contain the Swagger specification of Split Evaluator.
/api-docs
Swagger
Split Evaluator uses Swagger to document all API endpoints available in this service. They are available by default in this url: http://localhost:7548/api-docs.
If the port has been modified from the default(7548), make sure to set the environment variable SPLIT_EVALUATOR_SWAGGER_URL to match it.
Client APIs
Corresponds to the Client APIs that is generating impressions and tracking events.
- get-treatment
- get-treatments
- get-treatment-with-config
- get-treatments-with-config
- get-all-treatments
- get-all-treatments-with-config
- track
/client/get-treatment
Evaluates a single feature (split-name) for a single key.
Query params
- key: The key used in the
getTreatment
call. - split-name: The name of the split you want to include in the
getTreatment
call. - bucketing-key: (Optional) The bucketing key used in the
getTreatment
call. - attributes: (Optional) A JSON string of the attributes to include in the
getTreatment
call of the SDK.
Example
curl 'http://localhost:7548/client/get-treatment?key=my-customer-key&split-name=my-experiment&attributes=\{"attribute1":"one","attribute2":2,"attribute3":true\}' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"splitName": "my-experiment",
"treatment": "on"
}
/client/get-treatments
Provides a way of doing multiple evaluations at once.
Query params
- key: The key used in the
getTreatments
call. - split-names: The names of the splits you want to include in the
getTreatments
call separeted by commas. - bucketing-key: (Optional) The bucketing key used in the
getTreatments
call. - attributes: (Optional) A JSON string of the attributes to include in the
getTreatments
call of the SDK.
Example
curl 'http://localhost:7548/client/get-treatments?key=my-customer-key&split-names=my-experiment,my-second-experiment&attributes=\{"attribute1":"one","attribute2":2,"attribute3":true\}' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"my-experiment": {
"treatment": "on"
},
"my-second-experiment": {
"treatment": "off"
}
}
/client/get-treatment-with-config
Evaluates a single feature (split-name) for a single key and adds config in the result.
Query params
- key: The key used in the
getTreatmentWithConfig
call. - split-name: The name of the split you want to include in the
getTreatmentWithConfig
call. - bucketing-key: (Optional) The bucketing key used in the
getTreatmentWithConfig
call. - attributes: (Optional) A JSON string of the attributes to include in the
getTreatmentWithConfig
call of the SDK.
Example
curl 'http://localhost:7548/client/get-treatment-with-config?key=my-customer-key&split-name=my-experiment&attributes=\{"attribute1":"one","attribute2":2,"attribute3":true\}' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"splitName": "my-experiment",
"treatment": "on",
"config": "{/"color/": /"black/" }"
}
/client/get-treatments-with-config
Provides a way of doing multiple evaluations at once and attachs configs for each split evaluated.
Query params
- key: The key used in the
getTreatmentsWithConfig
call. - split-names: The names of the splits you want to include in the
getTreatmentsWithConfig
call separeted by commas. - bucketing-key: (Optional) The bucketing key used in the
getTreatmentsWithConfig
call. - attributes: (Optional) A JSON string of the attributes to include in the
getTreatmentsWithConfig
call of the SDK.
Example
curl 'http://localhost:7548/client/get-treatments-with-config?key=my-customer-key&split-names=my-second-experiment,my-experiment2&attributes=\{"attribute1":"one","attribute2":2,"attribute3":true\}' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"my-experiment": {
"treatment": "on",
"config": "{/"color/": /"black/" }"
},
"my-second-experiment": {
"treatment": "off",
"config": null
}
}
/client/get-all-treatments
Performs multiple evaluations at once. In this case it will match all the splits for a given traffic-type and will perform a getTreatments
call with the key provided. You can send more than one {matchingKey,bucketingKey,trafficType}
object.
Query params
- keys: The array of keys to be used in the
getTreatments
call. Each key should specifymatchingKey
andtrafficType
. You can also specifybucketingKey
. - attributes: (optional) A JSON string of the attributes to include in the
getTreatments
call of the SDK.
Example
curl 'http://localhost:7548/client/get-all-treatments?keys=\[\{"matchingKey":"my-first-key","trafficType":"account"\},\{"matchingKey":"my-second-key","bucketingKey":"my-bucketing-key","trafficType":"user"\}\]&attributes=\{"attribute1":"one","attribute2":2,"attribute3":true\}' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"account": {
"my-experiment": {
"treatment": "on"
},
"my-second-experiment": {
"treatment": "off"
}
},
"user": {
"my-last-experiment": {
"treatment": "off"
}
}
}
/client/get-all-treatments-with-config
Performs multiple evaluations at once. In this case it will match all the splits for a given traffic-type and will perform a getTreatmentsWithConfig
call with the key provided. You can send more than one {matchingKey,bucketingKey,trafficType}
object. This endpoint will also adds the configurations for particular split.
Query params
- keys: The array of keys to be used in the
getTreatmentsWithConfig
call. Each key should specifymatchingKey
andtrafficType
. You can also specifybucketingKey
. - attributes: (optional) A JSON string of the attributes to include in the
getTreatmentsWithConfig
call of the SDK.
Example
curl 'http://localhost:7548/client/get-all-treatments-with-config?keys=\[\{"matchingKey":"my-first-key","trafficType":"account"\},\{"matchingKey":"my-second-key","bucketingKey":"my-bucketing-key","trafficType":"user"\}\]&attributes=\{"attribute1":"one","attribute2":2,"attribute3":true\}' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"account": {
"my-experiment": {
"treatment": "on",
"config": "{/"color/": /"black/" }"
},
"my-second-experiment": {
"treatment": "off",
"config": null
}
},
"user": {
"my-last-experiment": {
"treatment": "off",
"config": "{/"copy/": /"better copy/" }"
}
}
}
/client/track
Records any actions your customers perform. Each action is known as an event and corresponds to an event type. Calling track allows you to measure the impact of your splits on your users' actions and metrics.
Query params
- key: The key used in the
track
call. - traffic-type: The traffic type of the key that you want to include in the
track
call. - event-type: The event type that this event should correspond to the
track
call of the SDK. - value: (Optional) value to be used in creating the metric.
- properties: (Optional) A JSON string of the properties to include in the
track
call of the SDK for filtering your metrics.
Example
curl 'http://localhost:7548/client/track?key=my-customer-key&event-type=my-event&traffic-type=account&properties=\{"prop1":"one","prop2":2,"attribute3":true\}' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
Successfully queued event
Manager APIs
Provides information of all the available splits.
- split
- splits
- names
/manager/split
Provides information of one particular split.
Query params
- split-name: The name of the split you want to have information. It uses
split
call of the SDK.
Example
curl 'http://localhost:7548/manager/split?split-name=my-experiment' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"name": "my-experiment",
"trafficType": "user",
"killed": false,
"changeNumber": 1563394983932,
"treatments": ["on", "off"],
"configs": {
"on": "{/"color/": /"black/" }",
"off": "{/"color/": /"red/" }"
}
}
/manager/splits
Provides information of all the available splits by calling splits
method from the SDK.
Example
curl 'http://localhost:7548/manager/splits' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"splits": [{
"name": "my-experiment",
"trafficType": "user",
"killed": false,
"changeNumber": 1563394983932,
"treatments": ["on", "off"],
"configs": {
"on": "{/"color/": /"black/" }",
"off": "{/"color/": /"red/" }"
}
}, {
"name": "my-second-experiment",
"trafficType": "user",
"killed": false,
"changeNumber": 1563394983933,
"treatments": ["on", "off"],
"configs": {
"on": "{/"color/": /"yellow/" }",
"off": "{/"color/": /"green/" }"
}
}]
}
/manager/names
Provides the names of the available splits. It calls names
of the SDK.
Example
curl 'http://localhost:7548/manager/names' -H 'Authorization: {SPLIT_EVALUATOR_AUTH_TOKEN}'
Response
{
"splits": ["my-experiment", "my-second-experiment"]
}
Admin
Provides information about Split Evaluator itself.
- ping
- uptime
- healthcheck
- version
- machine
/admin/ping
A ping endpoint to monitor the service status. If the service is running, it responds with pong
and the HTTP status code 200
.
Example
curl 'http://localhost:7548/admin/ping'
/admin/uptime
Returns the uptime of the service in a human-readable string.
Example
curl 'http://localhost:7548/admin/uptime'
Response
"5d 3h 36m 39s"
/admin/healthcheck
Checks that everything is working as expected before sending evaluations. It returns a status code of either 200
or 500
, depending on the result of the check, along with a message explaining the status.
Example
curl 'http://localhost:7548/admin/healthcheck'
Response
// For 200 status code
"Split Evaluator working as expected."
// For 500 status code
"Split evaluator engine not evaluating traffic properly."
/admin/version
Version information for the evaluator and the SDK within.
Example
curl 'http://localhost:7548/admin/version'
Response
{
"version": "1.0.2",
"sdk": "nodejs",
"sdkVersion": "9.3.4"
}
/admin/machine
Returns the data for the machine where this service is running.
Example
curl 'http://localhost:7548/admin/machine'
Response
{
"ip": "10.0.0.125",
"name": "machine_name"
}
Impression Listener
The Split Evaluator provides an impression listener (SPLIT_EVALUATOR_IMPRESSION_LISTENER_ENDPOINT
) 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.
If an Impression Listener is provided when the Split Evaluator is initialized, a task will run in background that will post impressions. There will be two ways of posting impressions to the provided endpoint:
1) Every 30 seconds by the Evaluator.
2) When the queue of impressions reached the max amount of impressions.
For further information, about how configuring the Impression Listener, see Configuration.
{
"impressions": [{
"feature": "my-experiment",
"keyName": "key-experiment",
"treatment": "on",
"time": 987654321,
"changeNumber": 987654321,
"label": "label"
}, {
"feature": "my-experiment",
"keyName": "key-experiment",
"treatment": "off",
"time": 123456789,
"changeNumber": 123456789,
"label": "default rule"
}
}
Configuration
The available configuration variables are listed below. Always use -e <VARIABLE>=<VALUE>
with Docker.
Variable | Description | Default |
---|---|---|
SPLIT_EVALUATOR_API_KEY | Split API key to authenticate against Split services. | - |
SPLIT_EVALUATOR_AUTH_TOKEN | Authentication key used to authenticate every request via the Authorization header. This is not a Split API key but an arbitrary value defined by the user. | No authentication |
SPLIT_EVALUATOR_LOG_LEVEL | Use for setting the log level for service (NONE | INFO |
SPLIT_EVALUATOR_SERVER_PORT | TCP port of the server inside the container. When using in Docker, make sure to match the right side of `-p : with the value of this variable. | 7548 |
SPLIT_EVALUATOR_IMPRESSION_LISTENER_ENDPOINT | Use it for providing a webhook to send a bulk of Impressions | - |
SPLIT_EVALUATOR_SPLITS_REFRESH_RATE | The SDK polls Split servers for changes to feature roll-out plans. This parameter controls this polling period in seconds. | 5 |
SPLIT_EVALUATOR_SEGMENTS_REFRESH_RATE | The SDK polls Split servers for changes to segment definitions. This parameter controls this polling period in seconds. | 60 |
SPLIT_EVALUATOR_METRICS_POST_RATE | The SDK sends diagnostic metrics to Split servers. This parameters controls this metric flush period in seconds. | 60 |
SPLIT_EVALUATOR_IMPRESSIONS_POST_RATE | The SDK sends information on who got what treatment at what time back to Split servers to power analytics. This parameter controls how often this data is sent to Split servers. The parameter should be in seconds. | 60 |
SPLIT_EVALUATOR_EVENTS_POST_RATE | The SDK sends tracked events to Split servers. This setting controls that flushing rate in seconds. | 60 |
SPLIT_EVALUATOR_EVENTS_QUEUE_SIZE | The max amount of events we queue. If the queue is full, the SDK flushes the events and reset the timer. | 500 |
SPLIT_EVALUATOR_SWAGGER_URL | The url used as base for any Swagger test curl commands. | http://localhost:7548 |
SPLIT_EVALUATOR_IP_ADDRESSES_ENABLED | Flag to disable IP addresses and host name from being sent to the Split backend. | 'true' |
HTTPS/SSL
This service does not currently support a secured connection. We recommend running this service in a redundant manner behind a load balancer such as AWS ELB or Nginx, with SSL termination.
Reach out to us any time at support@split.io if you have questions.
Comments
0 comments
Please sign in to leave a comment.