IBM InfoSphere Streams Version 4.1.0

Configuring the checkpoint data store

The checkpoint data store is configured for the domain or instance that is running any operator that calls the checkpoint API.

About this task

For each domain or instance, you choose the type and location of the backend store, which the checkpoint API writes to. Any changes to the configuration do not take effect until the instance or domain is stopped and restarted. The domain level properties are automatically inherited by all the instances in that domain unless the instance has its own instance level property.

Any instance that runs jobs that use checkpointing or consistent region features is required to set instance.checkpointRepository and instance.checkpointRepositoryConfiguration instance properties to specify a backend store for hosting checkpoint data. Typically, operators in a consistent region require checkpointing. Also, applications with the config checkpoint option set require a checkpoint data store.

The following properties are used to configure the checkpoint data store.

domain.checkpointRepository: This domain property can have the value redis, fileSystem, or notSpecified. The default value of notSpecified indicates that no checkpoint backend store is provided for the domain. You must configure your domain or instance to specify either redis or fileSystem before you run jobs that call the checkpoint API.
domain.checkpointRepositoryConfiguration: This domain property contains a string that contains the configuration information. For redis, it contains a list of redis server host names and port numbers. For fileSystem, it contains the absolute path to an existing directory that is the root of the checkpointing directory.
instance.checkpointRepository: This instance property can have the value redis or fileSystem.
instance.checkpointRepositoryConfiguration: This instance property contains a string that contains the configuration information. For redis, it contains a list of redis server host names and port numbers. For fileSystem, it contains the absolute path to an existing directory that is the root of the checkpointing directory.

For more information about domain and instance properties, use the streamtool man domainproperties and streamtool man properties commands.

Procedure

Configuring a redis checkpoint store:
Redis is an open source key-value data store. To use this store for checkpointing, you need to set up your Redis servers and provide their location to InfoSphere® Streams with host names and ports in the checkpointRepositoryConfiguration string. Multiple Redis servers can be configured and checkpoint data is distributed among the servers through sharding and replication.

The value of checkpointRepositoryConfiguration is in a JSON format.

For redis, operators' checkpoint data are stored on one or multiple Redis servers through sharding and replication. The Redis servers are organized as K shards and N replica groups (K x N servers in total). Checkpoint data is distributed among the K shards, and each checkpoint data is replicated on N Redis servers. The number of shards (K) determines the capacity of the backend store. The number of replicas (N) determines the reliability of backend store. Provisioning 2n+1 replica groups can tolerate n server failures. The following example contains the JSON format for specifying the information of Redis servers.
```
{
    "replicas" : N, 
    "shards" : K,
    "replicaGroups" : [replicaGroup1, replicaGroup2, ..., replicaGroupN]
}
```
The value of "shards" (K) specifies number of shards and it must be a positive integer value. The value of "replicas" (N) specifies number of replica groups and it must be an odd integer value (for example, 3). The "replicaGroups" is an array of N JSON objects. Each JSON object in the replicaGroups array corresponds to a replica group and is specified as follows:
```
{
    "servers" : [HostAndPortOfServer1, HostAndPortOfServer2, ..., HostAndPortOfServerK], 
    "description" : StringOfOptionalDescription
}
```
The value of "servers" is a JSON array that contains K "host:port" for the K Redis servers in the replica group. host can be host name or IP address and port is the port number that is used by the Redis server. The "description" is optional.

As an example, the setup for 24 Redis servers with 8 shards and 3 replicas has the following configuration value.
```
instance.checkpointRepositoryConfiguration=" {
\"replicas\" : 3,
\"shards\" : 8,
\"replicaGroups\" : [
    { \"servers\" : [\"host0:port0\", \"host1:port1\", \"host2:port2\", \"host3:port3\",
      \"host4:port4\", \"host5:port5\",\"host6:port6\", \"host7:port7\"],
      \"description\" : \"rack1\" }, 
    { \"servers\" : [\"host8:port8\", \"host9:port9\", \"host10:port10\", \"host11:port11\",
      \"host12:port12\",\"host13:port13\", \"host14:port14\", \"host15:port15\"],
      \"description\" : \"rack2\" }, 
    { \"servers\" : [\"host16:port16\", \"host17:port17\", \"host18:port18\",
      \"host19:port19\", \"host20:port20\",\"host21:port21\", \"host22:port22\",
      \"host23:port23\"],  \"description\" : \"rack3\" }
]
}"
```
Configuring a fileSystem checkpoint store:
For fileSystem, the domain.checkpointRepositoryConfiguration or instance.checkpointRepositoryConfiguration properties specify an absolute path to an existing directory as the root checkpointing directory. If the instance needs to run jobs with restartable and relocatable operators, then place the checkpointing directory in a shared file system.

The value of checkpointRepositoryConfiguration is in a JSON format.
```
instance.checkpointRepositoryConfiguration = " { \"Dir\" : path } " 
```
Where path is the absolute path to an existing directory.

The following example sets the checkpoint store within the user's home directory.
```
instance.checkpointRepositoryConfiguration=" { \"Dir\" : \"/home/user/ckpt\" } "
```
You can set these domain and instance properties with the streamtool setdomainproperty and streamtool setproperty commands. Use the streamtool getdomainproperty and streamtool getproperty commands to display property values.