• 510.205.3525

  • hello at getvariant.com

Variant Experiment Server Installation
and Configuration Guide

Release 1.4.0, September 2024

1. Installing Variant Experiment Server

Variant server is entirely self-contained and does not have any external dependencies. It requires Java runtime 17 or later. To install Variant server:

□ Unpack the distribution in a directory of your choice:

$ unzip /path/to/variant-server-<release>.zip

This will create a server installation with the following directory structure:

DirectoryDescription
bin/Contains the server startup shell script variant along with dependent scripts which you should never have to use.
conf/Configuration directory, containing the server config file variant.conf, logging config file logback.xml, and other dependent configuration artifacts.
lib/System libraries.
spi/User provided Java classes, developed on top of the Server-side SPI, and their dependencies. The distribution contains the the standard extension library variant-spi-stdlib-<release>.jar. All JAR files in the spi/ directory are added to Variant server’s runtime classpath.
log/Default destination for the server log files.
schemata/Default location of the experiment schema files. The distribution contains the example.yaml file for inspiration, which can be safely removed.

□ Change directory to Variant server top level directory:

$ cd variant-server-<release>

□ Start Variant server in the foreground:

$ bin/variant start

If all goes well, the server console output should look something like this:

$ bin/variant.sh start
2024-01-05 13:58:49,745 INFO - c.v.s.boot.ConfigLoader$ - Found  config resource [/variant.conf] as [/Users/variant/variant-server-1.0.1/conf/variant.conf]
2024-01-05 13:58:50,549 INFO - c.v.s.schema.SchemaDeployerFileSystem - Mounted schemata directory [/Users/variant/variant-server-1.0.1/schemata]
2024-01-05 13:58:50,553 INFO - c.v.s.schema.SchemaDeployerFileSystem - [421] Deploying schema from file [/Users/variant/variant-server-1.0.1/schemata/example.yaml]
2024-01-05 13:58:50,608 INFO - c.v.s.schema.ServerFlusherService - [431] Initialized flusher [TraceEventFlusherCsv] for schema [example]
2024-01-05 13:58:50,615 INFO - c.v.s.schema.Schemata - [422] Deployed schema [example] from file [example.yaml]
2024-01-05 13:58:50,645 INFO - c.v.s.impl.VariantServerImpl - [410] Variant Experiment Server release 1.3.1 started on port [5377] in 1.477s

You can deploy any other schema file by copying it into the schemata/ directory.

By default, the server binds to port 5377. To start the server on a different port, change the value of the configuration parameter variant.http.port  in the config file config/variant.conf.

You may always ping a running server by typing its URL into a Web browser, or from the command line with the curl command:

$ curl localhost:5377
{
  "name" : "Variant Experiment Server",
  "version" : "1.3.1",
  "uptimeSeconds" : 10,
  "build" : {
    "timestamp" : "2023-09-29T16:28:51.749146Z",
    "scalaVersion" : "2.13.4",
    "javaVersion" : "17.0.7",
    "javaVmName" : "OpenJDK 64-Bit Server VM",
    "javaVmVersion" : "17.0.7+7-LTS"
  },
  "schemata" : [ {
    "name" : "bookworms",
    "description" : "Variant experiment schema for the Bookworms demo application"
  } ]
}

A running server can be stopped by typing Control-C in the shell where it was started, or by typing in a different shell window

$ bin/variant.sh stop

Either will trigger a graceful shutdown whereby the Variant server will stop accepting new connections but will drain all existing sessions.

If you require an emergency server shutdown that may compromise user experience of the currently in-flight sessions, type

$ bin/variant.sh halt

2. Variant Experiment Server CLI

Variant server is written in Scala and runs on a JVM. It is controlled by the bin/variant shell script, which supports the following operations:

□ To get help on the supported command line options type:

$ variant help

□ To start Variant server in the foreground:

$ variant start

Any additional parameters will be passed to the underlying java without interpretation. In particular, you may pass any Java system property by appending the -D... to the start command.

At startup, Variant server looks for the default configuration file conf/variant.conf. If it is found, its contents override the default settings, listed in the next section. If you need to modify any configuration properties, you may either update them directly in the conf/variant.conf file, or provide an alternate configuration file. Variant supports two ways for doing so: as a file system file or as a JVM classpath resource. Either way, the contents of the alternate config file override those in the default config file conf/variant.conf, if any.

To supply an alternate configuration file as a file system file, use the variant.config.file JVM system property:

$ variant start -Dvariant.config.file=/path/to/alt/config/as/file

To supply an alternate configuration fileas a classpath resource , use the variant.config.resource JVM system property:

$ variant start -Dvariant.config.resource=resource-name

The simplest way to add a resource to the server classpath is to place it in the server’s conf directory, which is automatically added to the server’s runtime classpath at the root level. In other words, the file conf/extra.conf should be referenced as

$ variant.sh start -Dvariant.config.resource=/extra.conf

It is an error to set both variant.config.file and variant.config.resource system properties.

Similarly, any individual config parameter may be overridden from the command line via the JVM system variable of the same name, e.g.:

$ variant.sh start -Dvariant.schemata.dir=/Users/variant/schemata

□ To stop Variant server:

Either type Control-C in the shell where there the server was started in the foreground, or type in a different shell

$ variant stop

Either action will send the SIGINT signal to the server, which initiates a graceful shutdown:

  1. Each currently mounted experiment schema will be put in a draining state, whereby no new connections will be accepted, but the existing sessions will be waited for for up to a configurable period of time.
  2. Each schema’s pending trace events are flushed to disk.
  3. The embedded RocksDB is properly closed.

If you need to halt Variant server without waiting for the existing sessions to drain, use

$ bin/variant halt

This will send the SIGTERM signal, which initiates an emergency shutdown:

  1. Each currently mounted experiment schema is dismounted without draining existing sessions. This may cause in-flight sessions to see unintended user experiences.
  2. Each schema’s pending trace events are flushed to disk.
  3. The embedded RocksDB is properly closed.

You should avoid using non-maskable interrupts such as SIGKILL (i.e. running kill -9).

□ To find out the status of the Variant server:

$ variant status

3. Configuring Variant Experiment Server

Variant server is configured using the Lightbend Config library . The following table lists all config properties recognized by Variant server.

PropertyDefault Value / Description
variant.event.flusher.class.namecom.variant.server.api.EventFlusherAppLogger Default event flusher implementation, implicitly provided to those experiment schemata that do not define their own.
variant.event.flusher.nameThe name by which this flusher will be referred to in logs. The default is the simple name of the flusher class.
variant.event.flusher.class.initnull Arbitrary JSON object, whose parsed representation will be passed to the constructor of the event flusher implementation. Not required by the default com.variant.server.api.EventFlusherAppLogger above.
variant.event.writer.buffer.sizeMemory size in bytes allocated for each schema’s event buffers.
variant.event.writer.flush.size500 Maximum number of trace events passed to a single call to flush().
variant.event.writer.max.delay30 Maximum delay in seconds between the time when a trace event is triggered and the time it is passed to an event flusher. This ensures that events triggered by a low-traffic schema and not stuck in the asynchronous event writer for exessively long periods of time.
variant.event.writer.flush.parallelism2 The size of the flush thread pool. Event writer schedules calls to the flush() methods to be executed concurrently in a dedicated thread pool of this size. Buffers are flushed in the order they fill up. The flush pool is shared between all schemata.
variant.http.port5377 Variant server HTTP port.
variant.https.port5378 Variant server HTTPS port.
variant.schemata.dir"schemata" The directory where Variant server looks for experiment schemata, as an OS file name. If starts with a slash, interpreted as an absolute path. Otherwise, as relative path to the server startup directory.
variant.session.timeout900 Session timeout. User sessions are expired after this many seconds of inactivity.
variant.session.vacuum.interval10 The session vacuum thread is woken up no less frequently than this many seconds. The session vacuum thread expires inactive sessions and reclaims the memory taken by them.
Index