GraphDB-Enterprise Management and Control

{toc}

h1. Managing the cluster through the JMX interface

During initialisation, the GraphDB-Enterprise master node registers a JMX Bean component, which provides methods for monitoring and managing the running cluster. It is registered under "ReplicationCluster:name=ClusterInfo" signature and can be accessed through the standard Java instrumentation tools, e.g. JConsole. The rest of this section provides details about the attributes and operations available.


h2. Attributes

\\
|| Name | {{AutoReplication}} ||
|| Type | Boolean ||
|| Description | Indicates whether the cluster has the auto-replication enabled. ||
|| Possible values | Any non-negative integer. ||
|| Interface method | {{public int getAutoReplication();}} \\
{{public void setAutoReplication(boolean enabled);}} ||
\\
|| Name | {{AverageReadTime}} ||
|| Type | Integer ||
|| Description | Indicates the average time required across the whole cluster for processing a read request in milliseconds. ||
|| Possible values | Any non-negative integer. ||
|| Interface method | {{public int getAverageReadTime();}} ||
\\
|| Name | {{AverageTaskTimes}} ||
|| Type | Integer array ||
|| Description | Indicates the average time required for each node for processing a read request in milliseconds. ||
|| Possible values | An array of non-negative integer. ||
|| Interface method | {{public int\[\] getAverageTaskTimes();}} ||
\\
|| Name | {{CompletedReads}} ||
|| Type | Integer ||
|| Description | Indicates the total number of successfully processed read requests. ||
|| Possible values | The value is not persistent and will be 0 after initialisation. ||
|| Interface method | {{public int getCompletedReads();}} ||
\\
|| Name | {{CompletedTasks}} ||
|| Type | Integer array ||
|| Description | A list of values indicating the number of successful read requests for each node in the cluster, provided in the same order as NodeStatus. ||
|| Possible values | A list of non-negative integers ||
|| Interface method | {{public int\[\] getCompletedTasks();}} ||
\\
|| Name | {{CompletedWrites}} ||
|| Type | Integer ||
|| Description | Indicates the total number of successful updates processed by the cluster. This value is not persistent and is set to 0 after each cluster initialisation. ||
|| Possible values | Any non-negative integer value ||

{{public void setConfiguredWritable(boolean writable);}} ||
\\
|| Name | {{FailedReads}} ||
|| Type | Integer ||
|| Description | Indicates the total number of failed read requests for the cluster. The value is not persistent and will be 0 after initialisation. ||
|| Possible values | Any non-negative integer ||
|| Interface method | {{public int getFailedReads();}} ||
\\
|| Name | {{FailedTasks}} ||
|| Type | Integer array ||
|| Description | Indicates the total number of failed read requests for each node in the cluster. ||
|| Possible values | A list of non-negative integers ||
|| Interface method | {{public int\[\] getFailedTasks();}} ||
\\
|| Name | {{FailedWrites}} ||
|| Type | Integer ||
|| Description | Indicates the total number of failed updates. An update may fail if there is a problem with the control node on which the update is first probed. The value may also reflect the number of rejected updates, because some node is not available or needs replication. ||
|| Possible values | Any non-negative integer value ||
|| Interface method | {{public int getFailedWrites();}} ||
\\
|| Name | {{Fingerprints}} ||
|| Type | String array ||
|| Description | Retrieve a list of values representing the fingerprints of the individual nodes in the cluster. ||
|| Possible values | Unspecified ||
|| Interface method | {{public String\[\] getFingerprints();}} ||
\\
|| Name | {{IsWritable}} ||
|| Type | Boolean ||
|| Description | Indicates whether the current state of the cluster allows for the processing of update requests. ||
|| Possible values | True or false ||
|| Interface method | {{public boolean getIsWritable();}} ||
\\
|| Name | {{MasterReplicationPort}} ||
|| Type | Integer ||
|| Description | The port number used by the master node for replication (for online backup/restore or remote replication) ||
|| Possible values | 1 to 65536 ||
|| Interface method | {{public int getMasterReplicationPort();}} \\
{{public void setMasterReplicationPort(int value);}} ||
\\
|| Name | {{MasterUrl}} ||
|| Type | String ||
|| Description | The repository URL used by the master node for replication (for online backup/restore or remote replication) ||
|| Possible values | Any valid URL ||
|| Interface method | {{public String getMasterUrl();}} \\
{{public void setMasterUrl(String value);}} ||
\\
|| Name | {{NodeStatus}} ||
|| Type | String array ||
|| Description | Indicates the status of the registered nodes in the cluster as an array of strings, where values have the following format: \\
"\[<node status>\] <node URI>" ||
|| Possible values | \[OK\] - up to date and available for serving requests \\
\[NEEDS-UPDATE\] - the finger-print of the node is not the most recent - should be replicated but still be able to serve requests \\
\[MASTER\] - indicate that the node is a SERVER of an undergoing replication procedure and could not serve requests until is available again \\
\[SLAVE\] - indicate that the node is being replicated from a healthy node. Could not serve requests \\
\[DISABLED\] - the node do not respond on status requests - either not connected or not running at all ||
|| Interface method | {{public String\[\] getNodeStatus();}} ||
\\
|| Name | {{NumberOfExplicitTriples}} ||
|| Type | Long ||
|| Description | Indicates the number of explicit triples asserted in the cluster. ||
|| Possible values | Any non-negative long integer value ||
|| Interface method | {{public long getNumberOfExplicitTriples();}} ||
\\
|| Name | {{NumberOfTriples}} ||
|| Type | Long ||
|| Description | Indicates the total number of statements indexed with regard to the most recent update. ||
|| Possible values | Any non-negative long integer value ||
|| Interface method | {{public long getNumberOfTriples();}} ||
\\
|| Name | {{PendingWrites}} ||
|| Type | Integer ||
|| Description | Indicates the number of updates in the queue waiting to be processed by the cluster. ||
|| Possible values | Any non-negative integer. ||
|| Interface method | {{public int getPendingWrites();}} ||
\\
|| Name | {{PendingWritesLimit}} ||
|| Type | Integer ||
|| Description | Indicates the maximum number of updates that can be queued for processing by the cluster. ||
|| Possible values | Any non-negative integer. ||
|| Interface method | {{public int getPendingWritesLimit();}} \\
{{public void setPendingWritesLimit(int limit);}} ||
\\
|| Name | {{RemoteMaster}} ||
|| Type | Boolean ||
|| Description | Indicates if this cluster master can be used for 'remote replication', i.e. whether or not it accepts updates from another cluster master. ||
|| Possible values | True or false ||
|| Interface method | {{public boolean getRemoteMaster();}} \\
{{public void setRemoteMaster(boolean value);}} ||
\\
|| Name | {{RunningReads}} ||
|| Type | Integer array ||
|| Description | Indicates the total number of read requests currently being processed by the whole cluster. ||
|| Possible values | An array of any non-negative integers. ||
|| Interface method | {{public int getRunningReads();}} ||
\\
|| Name | {{RunningTasks}} ||
|| Type | Integer array ||
|| Description | Indicates the number of read requests currently being processed by each node in the cluster. ||
|| Possible values | An array of any non-negative integers. ||
|| Interface method | {{public int getRunningTasks();}} ||
\\
|| Name | {{RunningWrites}} ||
|| Type | Integer ||
|| Description | Indicates the number of updates currently being processed by the cluster. ||
|| Possible values | Currently only a single update could be processed at given point of time so the only possible values are 0 or 1. ||
|| Interface method | {{public int getRunningWrites();}} ||
\\
|| Name | {{Status}} ||
|| Type | Integer ||
|| Description | Indicates the current status of the cluster. ||
|| Possible values | 0 - available, all nodes up to date and in synch; \\
1 - needs attention, the attached worker nodes are not in synch or need to be updated \\
2 - not available - no worker nodes are available for processing requests ||
|| Interface method | {{public int getStatus();}} ||
\\
|| Name | {{StatusAsText}} ||
|| Type | String ||
|| Description | Indicates the current status of the cluster in text form. ||
|| Possible values | "AVAILABLE" - all nodes up to date and in synch; \\
"NEEDS_ATTENTION" - the attached worker nodes are not in synch or need to be updated \\
"UNAVAILABLE" - no worker nodes are available for processing requests ||
|| Interface method | {{public String getStatusAsText();}} ||
\\
|| Name | {{Timeout}} ||
|| Type | Integer ||
|| Description | The cluster timeout period used when executing update operations in seconds. ||
|| Possible values | Any non-negative integer value ||
|| Interface method | {{public long getTimeout();}} \\
{{public void setTimeout(int timeout);}} ||
\\



h2. Management Operations

\\
|| Name | {{addClusterNode}} ||
|| Parameters | \\
* {{nodeURI}}: String - A string holding the full URI of the Sesame end point of the new node, e.g. [http://58.181.33.153:8080/openrdf-sesame/repositories/worker1]
* {{replicationPort}}: int - The port number to use for replication activity.
* {{remoteNotificationsPort}}: int - The port number used for emitting remote notifications, this can be left blank if it is not required, see [remote notifications|GraphDB-SE Experimental Features].
* {{readable}}: boolean - If set to false (the default is true), then this worker node will receive only updates and will not particpate in sharing the cluster's query load. ||
|| Description | Add a new worker node to the cluster. If the node is a duplicate of an existing one then no error is logged. The same will also happen if the node pointed by the argument is not available. ||
|| Interface method | {{public void addClusterNode(String nodeURI, int replicationPort);}} ||

\\
|| Name | {{addSyncPeer}} ||
|| Parameters | \\
* {{id}}: String - ID of the peer master, e.g. "master2"
* {{url}}: String - A string holding the full URI of the Sesame end point of the new node, e.g. [http://58.181.33.153:8080/openrdf-sesame/repositories/master2] ||
|| Description | Add a new peer master to the cluster. ||
|| Interface method | {{public void addSyncPeer(String id, String url);}} ||

\\
|| Name | {{removeSyncPeer}} ||
|| Parameters | * {{url}}: String - A string holding the full URI of the Sesame end point of the new node, e.g. [http://58.181.33.153:8080/openrdf-sesame/repositories/master2] ||
|| Description | Remove the peer master from the cluster. ||
|| Interface method | {{public void removeSyncPeer(String url);}} ||

\\
|| Name | {{backup}} ||
|| Parameters | {{backupDirectory}} : String - The full path to a directory on the master node where a backup image will be stored ||
|| Description | Initiates a backup from a healthy, in-synch worker node to the given directory on the master node. ||
|| Interface method | {{public void backup(String backupDirectory);}} ||

\\
|| Name | {{cancelReplication}} ||
|| Parameters | none ||
|| Description | Cancels a full replication operation. This can be useful for recovering from stalled replication events, such as when two workers start replicating between themselves, but a network failure prevents this from finishing. ||
|| Interface method | {{public void cancelReplication();}} ||

\\
|| Name | {{changeSystemTransactionPassword}} ||
|| Parameters | {{oldPassword}} : String - The old password
* {{newPassword}} : String - The new password
* {{newPasswordRetype}} : String - The new password repeated ||
|| Description | Change the system transaction password. System transactions include a statement with a special predicate that instructs GraphDB to allow modifications to the imported, read-only schemas/ontologies. The replication cluster introduces a password for such transactions and this must appear in the object position of the 'special' statement, e.g.
{noformat}
_:b1 <http://www.ontotext.com/owlim/system#schemaTransaction> "the_password"
{noformat}
This operation is used to set/change the password. \\ ||
|| Interface method | {{public void changeSystemTransactionPassword(String oldPassword, String newPassword, String newPasswordRetype); ||

\\
|| Name | {{clearTransactionLog}} ||
|| Parameters | none ||
|| Description | Clear the transaction log. ||
|| Interface method | {{public void clearTransactionLog();}} ||

\\
|| Name | {{removeClusterNode}} ||
|| Parameters | {{nodeURI}} : String - A string holding the full URI of the Sesame end point of the node to be removed. ||
|| Description | Removes a node from the cluster. Invoking this operation will neither generate an exception nor log an error message. ||
|| Interface method | {{public void removeClusterNode(String message);}} ||

\\
|| Name | {{restoreFromImage}} ||
|| Parameters | {{backupDirectory}} : String - The full path to a directory on the master node where a backup image will be restored from. ||
|| Description | Initiates a restore from the given directory on the master node. The image will be replicated to each worker node in turn. ||
|| Interface method | {{public void restoreFromImage(String backupDirectory);}} ||

\\
|| Name | {{startReplication}} ||
|| Parameters | none ||
|| Description | Manually initiate a replication procedure. A random node with the most recent state is selected to propagate its state to those that are in \[NEEDS-UPDATE\] state. During the operation the node that replicates its state is excluded from available nodes and does not process read requests until it is finished with the replication. ||
|| Interface method | {{public void startReplication();}} ||


h2. Notifications

The ReplicationCluster MBean generates notifications for certain events. Users can receive these notifications by subscribing to this MBean (using jconsole, click on the notifications element, then click subscribe). The type and text of these notifications varies, but the following kinds of events are notified:

* A control query has completed or failed to complete;
* An RDF statement update has failed, been delayed or timed-out;
* An RDF read event could not occur (no available workers);
* A cluster worker node has been added or removed;
* A worker node status has changed;
* A worker node update has failed;
* A worker node is low on disk space;
* Replication (full/incremental) has started, stopped, failed.