Setting up Sauna - snowplow-archive/sauna GitHub Wiki

HOME > GUIDE FOR DEVOPS > Setting up Sauna

You should have Java Runtime Environment 8 installed.

You can download an archive containing a Sauna fatjar from our Bintray repository or clone the repo from Github and compile Sauna yourself (sbt assembly or whatever you prefer).

To start Sauna from the command-line, pass the required option --configurations pointing to a directory with self-describing Avro configurations:

$ ./sauna --configurations /path/to/avros

Sauna uses self-describing Avros for configuration. While we're referring to configuration files as Avros, in practice you can consider them regular JSON. Sauna's configuration files always use Avro's JSON Encoding (as opposed to binary encoding) unless stated otherwise. A configuration file must have an *.avro or .json extension (filenames are not important.)

Each Sauna entity is configured using an Avro file with the following common structure:

{
    "schema": "iglu:com.snowplowanalytics.sauna.entity/SomeEntity/avro/1-0-0",
    "data": {
        "enabled": true,
        "id": "MySaunaEntity",
        "parameters": {
            "configurationKey": "configurationValue"
        }
    }
}

All the fields above (except a dummy configurationKey) are required.

• schema and data fields represent envelopes for self-describing instances. You can read more about self-describing data in Iglu documentation. Sauna only understands instances with schemas published on Iglu Central with the com.snowplowanalytics.sauna vendor, so you can always refer to these schemas as a template for what your configuration should look like.

• id allows Sauna to internally identify a running entity, such as a responder or an observer. (All Sauna entities are modeled as Akka actors - id is used as an actor's name.) id must be a non-empty string containing only URL-safe symbols and be unique throughout the configuration.

• enabled simply indicates whether an entity should be enabled. If it's set to false, the entity will be ignored - but an exception with still be thrown if the content of data doesn't conform to the referenced schema.

• parameters is the main body of an entitie's configuration and contains keys and values intended only for this entity.

To find out more about Sauna's entity types and available entities of each type, you can browse these setup guides:

• Observers
• Responders
• Loggers

Note that multiple observers can be created as long as they have different ids, but each type of responder and logger must have at most one enabled instance.

Sauna is designed as a long-running server process; it needs to run constantly so that it can observe new events as they occur. Once started, the Sauna server will stay in the foreground - you can use your standard toolkit to daemonize and supervise it.

Sauna will fail to start if:

• There is not at least one enabled observer and one enabled responder.
• Any configuration fails to validate against its corresponding schema.
• Sauna does not yet support a given observer, responder or logger.
• More than one responder or logger is enabled for each type. (Multiple observers with different ids are supported.)