Persistence Service Configuration Parameters

This topic presents the FTL server configuration parameters that apply to the persistence service.

Example

The example configuration file has two sections: globals and servers. 

#Sample yaml file that demonstrates how to start three FTLServers with non-default persistence cluster.
globals:
  core.servers:
    ftlserver1: localhost:8585
    ftlserver2: localhost:8685
    ftlserver3: localhost:8785

servers:
  ftlserver1:
    - realm:
        # Update this field accordingly (for windows use backward slashes)
        data: TIBCO_HOME/persistence/ftlserver1/realm/data
    # Starts a non-default persistence server name pserver1
    # that belongs to a non-default persistence cluster
    # a persistence cluster with this server name needs to be configured
    - persistence:
        name: pserver1
        # Update this field accordingly (for windows use backward slashes)
        data: TIBCO_HOME/persistence/ftlserver1/pserver1/data
        savedir: TIBCO_HOME/persistence/ftlserver1/pserver1/dumpdata
  ftlserver2:
    - realm:
        # Update this field accordingly (for windows use backward slashes)
        data: TIBCO_HOME/persistence/ftlserver2/realm/data
    - persistence:
        name: pserver2
        # Update this field accordingly (for windows use backward slashes)
        data: TIBCO_HOME/persistence/ftlserver2/pserver2/data
        savedir: TIBCO_HOME/persistence/ftlserver2/pserver2/dumpdata
  ftlserver3:
    - realm:
        # Update this field accordingly (for windows use backward slashes)
        data: TIBCO_HOME/persistence/ftlserver3/realm/data
    - persistence:
        name: pserver3
        # Update this field accordingly (for windows use backward slashes)
        data: TIBCO_HOME/persistence/ftlserver3/pserver3/data
        savedir: TIBCO_HOME/persistence/ftlserver3/pserver3/dumpdata

Name

Parameter Arguments Description
name <service_name> Required.

Set the name of this persistence service. The <service_name> must match one of the service names defined in the persistence cluster definition.

To specify parameters for the default persistence service, set this to _default.

Note: The service name must be distinct for each FTL server.

File I/O

Parameter Arguments Description
data <path> Optional.

When present, the persistence service stores its working data files in this <path> location. (The directory at <path> must already exist, as the persistence service does not create it automatically.)

When absent, the default <path> is the current directory.

Ephemeral metadata is stored in this directory. If disk persistence is enabled, persistence data, including messages and acknowledgments, are written to this directory. If message swapping is enabled, data messages are swapped out to this directory by default. See swapdir later in this table.

savedir <path> Optional.

When present, the persistence service can write its state file in this <path> location. (The directory at <path> must exist, as the persistence service does not create it automatically.)

When absent, the default <path> is the current directory.

The state file name is always <service_name>.state.

A persistence service writes its state file only in response to an explicit command. This parameter specifies the location, but does not trigger a save operation. See Saving the State of a Persistence Service and POST persistence/clusters/<clus_name>/servers/<svc_name>.

This parameter does not affect loading a state file.

load <path> Optional.

Use this parameter when moving operations to a new physical location. After saving the state of the persistence service, copy the state file to <path> at the new location. Then use the load parameter to load that state when the persistence service starts at the new location.

When present, the persistence service loads its state from this state file. (Specify the complete file pathname, not only the directory path.)

When absent, the service loads its state from the default state file, <service_name>.state.

For more information, see Restarting a Persistence Cluster with Saved State.

swapdir <path> Optional.

When present and disk_swap is set to true, persistence service can write its message swap file in this <path> location. (The directory at <path> must exist, as the persistence service does not create it automatically.)

When absent, the default <path> is the designated data directory.

max.disk.fraction <path>

Optional.

The max.disk.fraction parameter monitors disk capacity and prevents a disk full state. You must also enable disk_persistence in the realm configuration.

The persistence service measures disk usage across the whole volume. Client publish calls fail once total disk usage approaches the max.disk.fraction setting multiplied by the capacity of the disk containing the persistence data directory.

The default value is 0.95. Values less than 0 and more than 1 are not allowed. A value of 0 disables the feature.

For more information, see Persistence Architecture, Handling Persistence Service Disk Capacity.

 
disk.prealloc.size <size>

Optional.

This parameter only takes effect if disk persistence is enabled for the persistence service.

Specify an integer representing the number of bytes to pre-allocate on disk. When specified, the persistence service extends an existing database to this size, or create a database of this size

Enabling pre-allocation can avoid the overhead of extending the database file in situations where the message backlog is growing.

  
force.disk.load  

By default, if the persistence service encounters a corrupt record in its database, the persistence service stops loading the database and exits. If other quorum members are running and up to date, the recommended course of action is to move or delete the corrupted database. On restart the persistence service syncs from the other quorum members.

If this is not possible because no other quorum members are running, you can use this parameter to force the persistence service to load the database. The corrupted record is discarded.

  

Also see: Saving and Loading Persistence State

Memory Reserve

Parameter Arguments Description
mem.reserve <size> Optional.

When present, the persistence service reserves memory so it can continue limited operations after exhausting available memory.

The <size> argument specifies the amount of memory in bytes. The minimum size is 100 megabytes.

When absent, the persistence service allocates the minimum size reserve.

For more information, see Memory Reserve for Persistence Services.

Performance

Parameter Arguments Description
max.working.memory <size>

Optional.

When present, set a soft limit on working memory (that is non-essential memory allocations). The value must be specified in bytes. The minimum value is 2 GB.

This is intended for performance tuning when additional memory is available on the server host. In high-load scenarios, the persistence service can allocate non-essential memory for performance reasons. (In low-load scenarios, the persistence service does not allocate this memory.)

Here are examples of situations where it may be beneficial to increase this value.

  • Client applications tend to send very large messages, or there are bursts of activity throughout the day. The persistence service can allocate memory to handle the burst without throttling client applications.

  • If the indexes on disk feature is enabled, the persistence service can allocate larger disk write buffers for improved write performance.

  • If the indexes on disk feature is enabled, the persistence service can increase the size of its read caches for improved consumer performance.

This is not intended as a method of limiting the overall memory usage of the persistence service. The following forces the persistence service to allocate additional memory, regardless of this setting.

  • Clients, producers, and consumers that are connected to the persistence service.

  • Message metadata for each pending non-persistent (non-replicated) message.

  • Message metadata for each pending persistent (replicated) message, unless the indexes on disk feature is enabled (in which case there is no per-message memory overhead for persistent messages).

  • Message data for each pending message, unless message swapping is enabled.

Mandatory memory allocations can be managed by setting limits on the allowable number or size of stored messages. See Persistence Limits.

For a broader overview of performance considerations, see Performance Considerations for Persistence.

Logging

Parameter Arguments Description
loglevel <level> When present, the persistence service logs protocol communication at this level of detail.

You may specify any of the standard log level strings. See “Tuning the Log Level” and its sub-topics in TIBCO FTL Development. You can set a general log level, or custom log levels for different elements.

When this parameter is absent, the default level is info.