This document details basic procedures for system administrators managing, maintaining, configuring and deploying Rhino 2.6 using the command-line console. To manage using a web interface, see the Rhino Element Manager documentation.
Topics
Administrative tasks for day-to-day management of the Rhino SLEE, its components and entities deployed in it, including: operational state, deployable units, services, resource adaptor entities, per-node activation state, profile tables and profiles, alarms, usage, user transactions, and component activation priorities. |
|
Procedures for configuring Rhino upon installation, and as needed (for example to tune performance), including: logging, staging, object pools, licenses, rate limiting, security and external databases. |
|
Finding Housekeeping MBeans, and finding, inspecting and removing one or all activities or SBB entities. |
|
Backing up and restoring the database, and exporting and importing SLEE deployment state. |
|
Managing the SNMP subsystem in Rhino, including: configuring the agent, managing MIB files, assigning OID mappings. |
|
Tools included with Rhino for system administrators to manage Rhino. |
Other documentation for the Rhino TAS can be found on the Rhino TAS product page.
SLEE Management
This section covers general administrative tasks for day-to-day management of the Rhino SLEE, its components and entities deployed in it.
JMX MBeans
Rhino SLEE uses Java Management Extension (JMX) MBeans for management functionality. This includes both functions defined in the JAIN SLEE 1.1 specification and Rhino extensions that allow additional functionality, beyond what’s in the specification.
Rhino’s command-line console is a front end for these MBeans, providing access to functions for managing:
Management may also be performed via the Rhino Element Manager web interface.
 |
See also Management Tools, and the Rhino Management Extension APIs. |
Namespaces
As well as an overview of Rhino namespaces, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples, and links to related javadocs:
| Procedure | rhino-console command | MBean → Operation |
|---|---|---|
createnamespace |
Namespace Management → createNamespace |
|
removenamespace |
Namespace Management → removeNamespace |
|
listnamespaces |
Namespace Management → getNamespaces |
|
|
Setting the active namespace |
-n <namespace> (command-line option) setactivenamespace (interactive command) |
Namespace Management → setActiveNamespace |
|
Getting the active namespace |
|
Namespace Management → getActiveNamespace |
About Namespaces
A namespace is an independent deployment environment that is isolated from other namespaces.
A namespace has:
-
its own SLEE operational state
-
its own set of deployable units
-
its own set of instantiated profile tables, profiles, and resource adaptor entities
-
its own set of component configuration state
-
its own set of activation states for services and resource adaptor entities.
All of these things can be managed within an individual namespace without affecting the state of any other namespace.
| |
A namespace can be likened to a SLEE in itself, where Rhino with multiple namespaces is a container of SLEEs. |
A Rhino cluster always has a default namespace that cannot be deleted. Any number of user-defined namespaces may also be created, managed, and subsequently deleted when no longer needed.
Management clients by default interact with the default namespace unless they explicitly request to interact with a different namespace.
Creating a Namespace
To create a new namespace, use the following rhino-console command or related MBean operation.
Console command: createnamespace
Command |
createnamespace <name>
Description
Create a new deployment namespace
|
|---|---|
Example |
$ ./rhino-console createnamespace testnamespace Namespace testnamespace created |
MBean operation: createNamespace
MBean |
|
|---|---|
Rhino extension |
public void createNamespace(String name)
throws NullPointerException, InvalidArgumentException,
NamespaceAlreadyExistsException, ManagementException;
|
Removing a Namespace
To remove an existing user-defined namespace, use the following rhino-console command or related MBean operation.
| |
The default namespace cannot be removed. |
 |
All deployable units (other than the deployable unit containing the standard JAIN SLEE-defined types) must be uninstalled and all profile tables removed from a namespace before that namespace can be removed. |
Console command: removenamespace
Command |
removenamespace <name>
Description
Remove an existing deployment namespace
|
|---|---|
Example |
$ ./rhino-console removenamespace testnamespace Namespace testnamespace removed |
MBean operation: removeNamespace
MBean |
|
|---|---|
Rhino extension |
public void removeNamespace(String name)
throws NullPointerException, UnrecognizedNamespaceException,
InvalidStateException, ManagementException;
|
Listing Namespaces
To list all user-defined namespaces in a SLEE, use the following rhino-console command or related MBean operation.
Console command: listnamespaces
Command |
listnamespaces
Description
List all deployment namespaces
|
|---|---|
Example |
$ ./rhino-console listnamespaces testnamespace |
MBean operation: getNamespaces
MBean |
|
|---|---|
Rhino extension |
public String[] getNamespaces() throws ManagementException; This operation returns the names of the user-defined namespaces that have been created. |
Setting the Active Namespace
Each individual authenticated client connection to Rhino is associated with a namespace.
This setting, known as the active namespace, controls which namespace is affected by management commands such as those that install deployable units or change operational states.
To change the active namespace for a client connection, use the following rhino-console command or related MBean operation.
Console command: setactivenamespace
Command and command-line option |
Interactive mode
In interactive mode, the setactivenamespace <-default|name>
Description
Set the active namespace
Non-interactive mode
In non-interactive mode, the |
|---|---|
Example |
Interactive mode
$ ./rhino-console Interactive Rhino Management Shell Rhino management console, enter 'help' for a list of commands [Rhino@localhost (#0)] setactivenamespace testnamespace The active namespace is now testnamespace [Rhino@localhost [testnamespace] (#1)] setactivenamespace -default The active namespace is now the default namespace [Rhino@localhost (#2)]
Non-interactive mode
$ ./rhino-console -n testnamespace start The active namespace is now testnamespace Starting SLEE on node(s) [101] SLEE transitioned to the Starting state on node 101 |
MBean operation: setActiveNamespace
MBean |
|
|---|---|
Rhino extension |
public void setActiveNamespace(String name)
throws NoAuthenticatedSubjectException, UnrecognizedNamespaceException,
ManagementException;
This operation sets the active namespace for the client connection. A |
Getting the Active Namespace
To get the active namespace for a client connection, use the following rhino-console information and related MBean operation.
Console:
Command prompt information |
The currently active namespace is reported in the command prompt within square brackets. If no namespace is reported, then the default namespace is active. |
|---|---|
Example |
$ ./rhino-console Interactive Rhino Management Shell Rhino management console, enter 'help' for a list of commands [Rhino@localhost (#0)] setactivenamespace testnamespace The active namespace is now testnamespace [Rhino@localhost [testnamespace] (#1)] setactivenamespace -default The active namespace is now the default namespace [Rhino@localhost (#2)] |
MBean operation: getActiveNamespace
MBean |
|
|---|---|
Rhino extension |
public String getActiveNamespace() throws NoAuthenticatedSubjectException, ManagementException; This operation returns the name of the namespace currently active for the client connection. |
Operational State
As well as an overview of SLEE operational states, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs:
| Procedure | rhino-console command | MBean → Operation |
|---|---|---|
start |
SLEE Management → start |
|
stop |
SLEE Management → stop |
|
|
Retrieving the basic operational state of nodes |
state |
SLEE Management → getState |
|
Retrieving detailed information for every node in the cluster |
getState |
Rhino Housekeeping → getClusterState |
|
Gracefully shutting nodes down |
shutdown |
SLEE Management → shutdown |
|
Forcefully terminating nodes |
kill |
SLEE Management → kill |
|
Gracefully rebooting nodes |
reboot |
SLEE Management → reboot |
|
Enabling the symmetric activation state mode |
enablesymmetricactivationstatemode |
Runtime Config Management → enableSymmetricActivationStateMode |
|
Disabling the symmetric activation state mode |
disablesymmetricactivationstatemode |
Runtime Config Management → disableSymmetricActivationStateMode |
|
Getting the current activation state mode |
getsymmetricactivationstatemode |
Runtime Config Management → isSymmetricActivationStateModeEnabled |
|
Listing nodes with per-node activation state |
getnodeswithpernodeactivationstate |
Node Housekeeping → getNodesWithPerNodeActivationState |
|
Copying per-node activation state to another node |
copypernodeactivationstate |
Node Housekeeping → copyPerNodeActivationState |
|
Removing per-node activation state |
removePerNodeActivationState |
Node Housekeeping → removePerNodeActivationState |
About SLEE Operational States
The SLEE specification defines the operational lifecycle of a SLEE — illustrated, defined, and summarised below.
SLEE lifecycle states
The SLEE lifecycle states are:
| State | Definition |
|---|---|
STOPPED |
The SLEE has been configured and initialised, and is ready to be started. Active resource adaptor entities have been loaded and initialised, and SBBs corresponding to active services have been loaded and are ready to be instantiated. The entire event-driven subsystem, however, is idle: resource adaptor entities and the SLEE are not actively producing events, the event router is not processing work, and the SLEE is not creating SBB entities. |
STARTING |
Resource adaptor entities in the SLEE that have been recorded in the management database as being in the ACTIVE state are started. The SLEE still does not create SBB entities. The node automatically transitions from this state to the RUNNING state when all startup tasks are complete, or to the STOPPING state if a startup task fails. |
RUNNING |
Activated resource adaptor entities in the SLEE can fire events, and the SLEE creates SBB entities and delivers events to them as needed. |
STOPPING |
Identical to the RUNNING state, except resource adaptor entities do not create (and the SLEE does not accept) new activity objects. Existing activity objects can end (according to the resource adaptor specification). The node automatically transitions out of this state, returning to the STOPPED state, when all SLEE activities have ended. The node can transition to this state directly from the STARTING state, effective immediately, if it has no activity objects. |
Independent SLEE states
Each namespace in each event-router node in a Rhino cluster maintains its own SLEE-lifecycle state machine, independent from other namespaces on the same or other nodes in the cluster. For example:
-
the default namespace on one node in a cluster might be in the RUNNING state
-
while a user-defined namespace on the same node is in the STOPPED state
-
while the default namespace on another node is in the STOPPING state
-
and the user-defined namespace on that node is in the RUNNING state.
The operational state of each namespace on each cluster node persists to the disk-based database.
Bootup SLEE state
After completing bootup and initialisation, a namespace on a node will enter the STOPPED state if:
-
the database has no persistent operational state information for that namespace on that node;
-
the namespace’s persistent operational state is STOPPED on that node; or
-
the node was started with the
-xoption (see Start Rhino in the Rhino Getting Started Guide).
Otherwise, the namespace will return to the same operational state that it was last in, as recorded in persistent storage.
Changing a namespace’s operational state
You can change the operational state of any namespace on any node at any time, as long as least one node in the cluster is available to perform the management operation (regardless of whether or not the node whose operational state being changed is a current cluster member). For example, you might set the operational state of the default namespace on node 103 to RUNNING before node 103 is started — then, when node 103 is started, after it completes initialising, the default namespace will enter the RUNNING state.
 |
Changing a quorum node’s operational state
You can also change the operational state of a node which is a current member of the cluster as a quorum node… but quorum nodes make no use of operational state information stored in the database, and will not respond to operational state changes. (A node only uses operational state information if it starts as a regular event-router node.) |
Starting the SLEE
To start a SLEE on one or more nodes, use the following rhino-console command or related MBean operation.
Console command: start
Command |
start [-nodes node1,node2,...] [-ifneeded]
Description
Start the SLEE (on the specified nodes)
|
|---|---|
Example |
To start nodes 101 and 102: $ ./rhino-console start -nodes 101,102 Starting SLEE on node(s) [101,102] SLEE transitioned to the Starting state on node 101 SLEE transitioned to the Starting state on node 102 |
MBean operation: start
MBean |
|
|---|---|
SLEE-defined |
Start all nodes
public void start() throws InvalidStateException, ManagementException; Rhino’s implementation of the SLEE-defined |
Rhino extension |
Start specific nodes
public void start(int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
InvalidStateException, ManagementException;
Rhino provides an extension that adds an argument which lets you control which nodes to start (by specifying node IDs). For this to work, the specified nodes must be in the STOPPED state. |
Stopping the SLEE
To stop SLEE event-routing functions on one or more nodes, use the following rhino-console command or related MBean operation.
Console command: stop
Command |
stop [-nodes node1,node2,...] [-reassignto -node3,node4,...] [-ifneeded]
Description
Stop the SLEE (on the specified nodes (reassigning replicated activities to the
specified nodes))
|
||
|---|---|---|---|
Examples |
To stop nodes 101 and 102: $ ./rhino-console stop -nodes 101,102 Stopping SLEE on node(s) [101,102] SLEE transitioned to the Stopping state on node 101 SLEE transitioned to the Stopping state on node 102 To stop only node 101 and reassign replicated activities to node 102: $ ./rhino-console stop -nodes 101 -reassignto 102 Stopping SLEE on node(s) [101] SLEE transitioned to the Stopping state on node 101 Replicated activities reassigned to node(s) [102] To stop node 101 and distribute replicated activities of each replicating resource adaptor entity to all other eligible nodes (those on which the resource adaptor entity is in the ACTIVE state and the SLEE is in the RUNNING state), specify an empty (zero-length) argument for the $ ./rhino-console stop -nodes 101 -reassignto "" Stopping SLEE on node(s) [101] SLEE transitioned to the Stopping state on node 101 Replicated activities reassigned to node(s) [102,103]
|
MBean operation: stop
MBean |
|
|---|---|
SLEE-defined |
Stop all nodes
public void stop() throws InvalidStateException, ManagementException; Rhino’s implementation of the SLEE-defined |
Rhino extensions |
Stop specific nodes
public void stop(int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
InvalidStateException, ManagementException;
Rhino provides an extension that adds an argument which lets you control which nodes to stop (by specifying node IDs). For this to work, specified nodes must begin in the RUNNING state.
Reassign activities to other nodes
public void stop(int[] stopNodeIDs, int[] reassignActivitiesToNodeIDs)
throws NullPointerException, InvalidArgumentException,
InvalidStateException, ManagementException;
Rhino also provides an extension that adds another argument, which lets you reassign ownership of replicated activities (from replicating resource adaptor entities) from the stopping nodes, distributing the activities of each resource adaptor entity equally among other event-router nodes where the resource adaptor entity is eligible to adopt them. With a smaller set of activities, the resource adaptor entities on the stopping nodes can more quickly return to the INACTIVE state (which is required for the SLEE to transition from the STOPPING to the STOPPED state). This only works for resource adaptor entities that are replicating activity state (see the description of the "Rhino-defined configuration property" on the MBean tab on Creating a Resource Adaptor Entity). See also Reassigning a Resource Adaptor Entity’s Activities to Other Nodes, in particular the Requirements tab. |
Basic Operational State of a Node
To retrieve the basic operational state of a node, use the following rhino-console command or related MBean operation.
Console command: state
Command |
state [-nodes node1,node2,...]
Description
Get the state of the SLEE (on the specified nodes)
|
|---|---|
Output |
The |
Examples |
To display the state of only node 101: $ ./rhino-console state -nodes 101 Node 101 is Stopped To display the state of every event-router node: $ ./rhino-console state Node 101 is Stopped Node 102 is Running |
MBean operation: getState
MBean |
|
|---|---|
SLEE-defined |
Return state of current node
public SleeState getState() throws ManagementException; Rhino’s implementation of the SLEE-defined |
Rhino extension |
Return state of specific nodes
public SleeState[] getState(int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
ManagementException;
Rhino provides an extension that adds an argument which lets you control which nodes to examine (by specifying node IDs). |
Detailed Information for Every Node in the Cluster
To retrieve detailed information for every node in the cluster (including quorum nodes), use the following rhino-console command or related MBean operation.
Console command: getclusterstate
Command |
getclusterstate
Description
Display the current state of the Rhino Cluster
|
|---|---|
Output |
For every node in the cluster, retrieves detailed information on the:
|
Example |
$ ./rhino-console getclusterstate
node-id active-alarms host node-type slee-state start-time up-time
-------- -------------- ----------------- ------------- ----------- ------------------ -----------------
101 0 host1.domain.com event-router Stopped 20080327 12:16:26 0days,2h,40m,3s
102 0 host2.domain.com event-router Running 20080327 12:16:30 0days,2h,39m,59s
103 0 host3.domain.com quorum n/a 20080327 14:36:25 0days,0h,20m,4s
|
MBean operation: getClusterState
MBean |
|
|---|---|
Rhino extension |
public TabularData getClusterState() throws ManagementException; (Refer to the |
| |
See also Basic operational state of a node. |
Terminating Nodes
To terminate cluster nodes, you can:
| |
You can stop functions on nodes and nodes themselves, by:
See also Stop Rhino in the Getting Started Guide, which details using the |
Shut Down Gracefully
To gracefully shut down one or more nodes, use the following rhino-console command or related MBean operation.
Console command: shutdown
Command |
shutdown [-nodes node1,node2,...] [-timeout timeout] [-restart]
Description
Gracefully shutdown the SLEE (on the specified nodes). The optional timeout is
specified in seconds. Optionally restart the node(s) after shutdown
|
|---|---|
Examples |
To shut down the entire cluster: $ ./rhino-console shutdown Shutting down the SLEE Shutdown successful To shut down only node 102: $ ./rhino-console shutdown -nodes 102 Shutting down node(s) [102] Shutdown successful |
MBean operation: shutdown
MBean |
|
|---|---|
SLEE-defined |
Shut down all nodes
public void shutdown() throws InvalidStateException, ManagementException; Rhino’s implementation of the SLEE-defined |
Rhino extension |
Shut down specific nodes
public void shutdown(int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
InvalidStateException, ManagementException;
Rhino provides an extension that adds an argument which lets you control which nodes to shut down (by specifying node IDs). |
| |
Event-router nodes can only be shut down when STOPPED — if any in the set of nodes that a shutdown operation targets is not in the STOPPED state, the shutdown operation will fail (and no nodes will shut down). Quorum nodes can be shut down at any time. |
Forcefully Terminate
To forcefully terminate a cluster node that is in any state where it can respond to management operations, use the following rhino-console command or related MBean operation.
Console command: kill
Command |
kill -nodes node1,node2,...
Description
Forcefully terminate the specified nodes (forces them to become non-primary)
|
|---|---|
Example |
To forcefully terminate nodes 102 and 103: $ ./rhino-console kill -nodes 102,103 Terminating node(s) [102,103] Termination successful |
MBean operation: kill
MBean |
|
|---|---|
Rhino operation |
public void kill(int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
ManagementException;
Rhino’s |
 |
Application state may be lost
Killing a node is not recommended — forcibly terminated nodes lose all non-replicated application state. |
Rebooting Nodes
To gracefully reboot one or more nodes, use the following rhino-console command or related MBean operation.
Console command: reboot
Command |
reboot [-nodes node1,node2,...] {-state state | -states state1,state2,...}
Description
Gracefully shutdown the SLEE (on the specified nodes), restarting into either
the running or stopped state.
Use either the -state argument to set the state for all nodes or the -states
argument to set it separately for each node rebooted.
If a list of nodes is not provided then -state must be used to set the state of
all nodes.
Valid states are (r)unning and (s)topped
|
|---|---|
Examples |
To reboot the entire cluster: $ ./rhino-console reboot -states running,running,stopped Restarting node(s) [101,102,103] (using Rhino's default shutdown timeout) Restarting To shut down only node 102: $ ./rhino-console reboot -nodes 102 -states stopped Restarting node(s) [102] (using Rhino's default shutdown timeout) Restarting |
MBean operation: reboot
MBean |
|
|---|---|
Rhino extension |
Reboot all nodes
public void reboot(SleeState[] states) throws InvalidArgumentException, InvalidStateException, ManagementException; Reboots every node in the cluster to the state specified. |
Rhino extension |
Reboot specific nodes
public void reboot(int[] nodeIDs, SleeState[]) throws NullPointerException, InvalidArgumentException, InvalidStateException, ManagementException; Extension to reboot that adds an argument which lets you control which nodes to shut down (by specifying node IDs). |
| |
Event-router nodes can restart to either the RUNNING state or the STOPPED state. Quorum nodes must have a state provided but do not use this in operation. |
Activation State
As well as an overview of activation state modes, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples, and links to related javadocs:
| Procedure | rhino-console command | MBean → Operation |
|---|---|---|
|
Enabling the symmetric activation state mode |
enablesymmetricactivationstatemode |
Runtime Config Management → enableSymmetricActivationStateMode |
|
Disabling the symmetric activation state mode |
disablesymmetricactivationstatemode |
Runtime Config Management → disableSymmetricActivationStateMode |
|
Getting the current activation state mode |
getsymmetricactivationstatemode |
Runtime Config Management → isSymmetricActivationStateModeEnabled |
|
Listing nodes with per-node activation state |
getnodeswithpernodeactivationstate |
Node Housekeeping → getNodesWithPerNodeActivationState |
|
Copying per-node activation state to another node |
copypernodeactivationstate |
Node Housekeeping → copyPerNodeActivationState |
|
Removing per-node activation state |
removePerNodeActivationState |
Node Housekeeping → removePerNodeActivationState |
About Activation State Modes
Rhino has two modes of operation for managing the activation state of services and resource adaptor entities: per-node and symmetric.
The activation state for the SLEE event-routing functions is always maintained on a per-node basis.
Per-node activation state
In the per-node activation state mode, Rhino maintains activation state for the installed services and created resource adaptor entities in a namespace on a per-node basis. That is, the SLEE records separate activation state information for each individual cluster node.
The per-node activation state mode is the default mode in a newly installed Rhino cluster.
Symmetric activation state
In the symmetric activation state mode, Rhino maintains a single cluster-wide activation state view for each installed service and created resource adaptor entity. So, for example, if a service is activated, then it is simultaneously activated on every cluster node. If a new node joins the cluster, then the services and resource adaptor entities on that node each enter the same activation state as for existing cluster nodes.
| |
MBean operations affecting the activation state of services or resource adaptor entities that accept a list of node IDs to apply the operation to, such as the Similary, MBean operations that inspect or manage per-node activation state, such as the |
Symmetric Activation State
This section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs:
| Procedure | rhino-console command | MBean → Operation |
|---|---|---|
enablesymmetricactivationstatemode |
Runtime Config Management → enableSymmetricActivationStateMode |
|
disablesymmetricactivationstatemode |
Runtime Config Management → disableSymmetricActivationStateMode |
|
getsymmetricactivationstatemode |
Runtime Config Management → isSymmetricActivationStateModeEnabled |
Enable Symmetric Activation State Mode
To switch from the per-node activation state mode to the symmetric activation state mode, use the following rhino-console command or related MBean operation.
Console command: enablesymmetricactivationstatemode
Command |
enablesymmetricactivationstatemode <template-node-id>
Description
Enable symmetric activation state mode of services and resource adaptor entities
across the cluster. Components across the cluster will assume the state of the
specified template node
|
|---|---|
Example |
$ ./rhino-console enablesymmetricactivationstatemode 101 Symmetric activation state mode enabled using node 101 as a template |
MBean operation: enableSymmetricActivationStateMode
MBean |
|
|---|---|
Rhino operation |
public void enableSymmetricActivationStateMode(int templateNodeID)
throws InvalidStateException, InvalidArgumentException,
ConfigurationException;
This operation activates and/or deactivates services and resource adaptor entities on other cluster nodes such that their activation state matches that of the template node. If a service or resource adaptor entity is deactivated on a node where the SLEE operational state is RUNNING or STOPPING, that service or resource adaptor entity will enter the STOPPING state and be allowed to drain before it transitions to the INACTIVE state. |
Disable Symmetric Activation State Mode
To switch from the symmetric activation state mode back to the per-node activation state mode, use the following rhino-console command or related MBean operation.
Console command: disablesymmetricactivationstatemode
Command |
disablesymmetricactivationstatemode
Description
Disable symmetric activation state mode of services and resource adaptor
entities across the cluster, such that components may have different activation
states on different nodes
|
|---|---|
Example |
$ ./rhino-console disablesymmetricactivationstatemode Symmetric activation state mode disabled |
MBean operation: disableSymmetricActivationStateMode
MBean |
|
|---|---|
Rhino operation |
public void disableSymmetricActivationStateMode()
throws InvalidStateException, ConfigurationException;
This operation disables the symmetric activation state mode, thus restoring the per-node activation state mode. The existing activation states of services and resource adaptor entities are not affected by this operation — the per-node activation state of each service and resource adaptor entity is simply set to the current corresponding symmetric state. |
Get the Current Activation State Mode
To determine if the symmetric activation state mode is enabled or disabled, use the following rhino-console command or related MBean operation.
If the symmetric activation state mode is disabled, then the per-node activation state mode consequently must be in force.
Console command: getsymmetricactivationstatemode
Command |
getsymmetricactivationstatemode
Description
Display the current status of the symmetric activation state mode
|
|---|---|
Example |
$ ./rhino-console getsymmetricactivationstatemode Symmetric activation state mode is currently enabled |
MBean operation: isSymmetricActivationStateModeEnabled
MBean |
|
|---|---|
Rhino operation |
public boolean isSymmetricActivationStateModeEnabled()
throws ConfigurationException;
|
Per-Node Activation State
This section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples, and links to related javadocs.
| Procedure | rhino-console command | MBean → Operation |
|---|---|---|
getnodeswithpernodeactivationstate |
Node Housekeeping → getNodesWithPerNodeActivationState |
|
copypernodeactivationstate |
Node Housekeeping → copyPerNodeActivationState |
|
removepernodeactivationstate |
Node Housekeeping → removePerNodeActivationState |
| |
See also Finding Housekeeping MBeans. |
Listing Nodes with Per-Node Activation State
To get a list of nodes with per-node activation state, use the following rhino-console command or related MBean operation.
Console command: getnodeswithpernodeactivationstate
Command |
getnodeswithpernodeactivationstate
Description
Get the set of nodes for which per-node activation state exists
|
|---|---|
Example |
$ ./rhino-console getnodeswithpernodeactivationstate Nodes with per-node activation state: [101,102,103] |
MBean operation: getNodesWithPerNodeActivationState
MBean |
|
|---|---|
Rhino operation |
public int[] getNodesWithPerNodeActivationState()
throws ManagementException;
This operation returns an array, listing the cluster node IDs for nodes that have per-node activation state recorded in the database). |
Copying Per-Node Activation State to Another Node
To copy per-node activation state from one node to another, use the following rhino-console command or related MBean operation.
Console command: copypernodeactivationstate
Command |
copypernodeactivationstate <from-node-id> <to-node-id>
Description
Copy per-node activation state from one node to another
|
||
|---|---|---|---|
Example |
To copy the per-node activation state from node 101 to node 102: $ ./rhino-console copypernodeactivationstate 101 102 Per-node activation state copied from 101 to 102
|
MBean operation: copyPerNodeActivationState
MBean |
|
|---|---|
Rhino operation |
public boolean copyPerNodeActivationState(int targetNodeID)
throws UnsupportedOperationException, InvalidArgumentException,
InvalidStateException, ManagementException;
This operation:
|
| |
The start-rhino.sh command with the Production version of Rhino also includes an option (-c) to copy per-node activation state from another node to the booting node as it initialises. (See Start Rhino in the Getting Started Guide.) |
Removing Per-Node Activation State
To remove per-node activation state, use the following rhino-console command or related MBean operation.
Console command: removepernodeactivationstate
Command |
removepernodeactivationstate <from-node-id>
Description
Remove per-node activation state from a node
|
||
|---|---|---|---|
Example |
To remove per-node activation state from node 103: $ ./rhino-console removepernodeactivationstate 103 Per-node activation state removed from 103
|
MBean operation: removePerNodeActivationState
MBean |
|
|---|---|
Rhino operation |
public boolean removePerNodeActivationState()
throws UnsupportedOperationException, InvalidStateException,
ManagementException;
This operation:
|
| |
The start-rhino.sh command with the Production version of Rhino also includes an option (-d) to remove per-node activation state from the booting node as it initialises. (See Start Rhino in the Getting Started Guide.) |
Startup and Shutdown Priority
Startup and shutdown priorities should be set when resource adaptors and services need to be activated or deactivated in a particular order when the SLEE is started or stopped. For example, the resource adaptors responsible for writing Call Detail Records often need to be deactivated last.
Valid priorities are between -128 and 127. Startup and shutdown occur from highest to lowest priority.
Console commands
Console command: getraentitystartingpriority
Command |
getraentitystartingpriority <entity-name>
Description
Get the starting priority for a resource adaptor entity
|
|---|---|
Examples |
./rhino-console getraentitystartingpriority sipra Resource adaptor entity sipra activation priority is currently 0 |
Console command: getraentitystoppingpriority
Command |
getraentitystoppingpriority <entity-name>
Description
Get the stopping priority for a resource adaptor entity
|
|---|---|
Examples |
./rhino-console getraentitystoppingpriority sipra Resource adaptor entity sipra deactivation priority is currently 0 |
Console command: getservicestartingpriority
Command |
getservicestartingpriority <service-id>
Description
Get the starting priority for a service
|
|---|---|
Examples |
./rhino-console getservicestartingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] activation priority is currently 0 |
Console command: getservicestoppingpriority
Command |
getservicestoppingpriority <service-id>
Description
Get the stopping priority for a service
|
|---|---|
Examples |
./rhino-console getservicestoppingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] deactivation priority is currently 0 |
Console command: setraentitystartingpriority
Command |
setraentitystartingpriority <entity-name> <priority>
Description
Set the starting priority for a resource adaptor entity. The priority must be
between -128 and 127 and higher priority values have precedence over lower
priority values
|
|---|---|
Examples |
./rhino-console setraentitystartingpriority sipra 127 Resource adaptor entity sipra activation priority set to 127 ./rhino-console setraentitystartingpriority sipra -128 Resource adaptor entity sipra activation priority set to -128 |
Console command: setraentitystoppingpriority
Command |
setraentitystoppingpriority <entity-name> <priority>
Description
Set the stopping priority for a resource adaptor entity. The priority must be
between -128 and 127 and higher priority values have precedence over lower
priority values
|
|---|---|
Examples |
./rhino-console setraentitystoppingpriority sipra 127 Resource adaptor entity sipra deactivation priority set to 127 ./rhino-console setraentitystoppingpriority sipra -128 Resource adaptor entity sipra deactivation priority set to -128 |
Console command: setservicestartingpriority
Command |
setservicestartingpriority <service-id> <priority>
Description
Set the starting priority for a service. The priority must be between -128 and
127 and higher priority values have precedence over lower priority values
|
|---|---|
Examples |
./rhino-console setservicestartingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 127 Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] activation priority set to 127 ./rhino-console setservicestartingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 -128 Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] activation priority set to -128 |
Console command: setservicestoppingpriority
Command |
setservicestoppingpriority <service-id> <priority>
Description
Set the stopping priority for a service. The priority must be between -128 and
127 and higher priority values have precedence over lower priority values
|
|---|---|
Examples |
./rhino-console setservicestoppingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 127 Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] deactivation priority set to 127 ./rhino-console setservicestoppingpriority name=SIP\ Presence\ Service,vendor=OpenCloud,version=1.1 -128 Service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] deactivation priority set to -128 |
MBean operations
Services
MBean |
|
|---|---|
Rhino extensions |
getStartingPriority
byte getStartingPriority(ServiceID service)
throws NullPointerException, UnrecognizedServiceException, ManagementException;
getStartingPriorities
Byte[] getStartingPriorities(ServiceID[] services)
throws NullPointerException, ManagementException;
getStoppingPriority
byte getStoppingPriority(ServiceID service) throws NullPointerException, UnrecognizedServiceException, ManagementException;
getStoppingPriorities
Byte[] getStoppingPriorities(ServiceID[] services)
throws NullPointerException, ManagementException;
setStartingPriority
void setStartingPriority(ServiceID service, byte priority)
throws NullPointerException, UnrecognizedServiceException, ManagementException;
setStoppingPriority
void setStoppingPriority(ServiceID service, byte priority)
throws NullPointerException, UnrecognizedServiceException, ManagementException;
|
Resource Adaptors
MBean |
|
|---|---|
Rhino extensions |
getStartingPriority
byte getStartingPriority(String entityName)
throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
getStartingPriorities
Byte[] getStartingPriorities(String[] entityNames)
throws NullPointerException, ManagementException;
getStoppingPriority
byte getStoppingPriority(String entityName) throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
getStoppingPriorities
Byte[] getStoppingPriorities(String[] entityNames)
throws NullPointerException, ManagementException;
setStartingPriority
void setStartingPriority(String entityName, byte priority)
throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
setStoppingPriority
void setStoppingPriority(String entityName, byte priority)
throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
|
Deployable Units
As well as an overview of deployable units, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:
| Procedure | rhino-console command(s) | MBean → Operation |
|---|---|---|
install installlocaldu |
DeploymentMBean → install |
|
uninstall |
DeploymentMBean → uninstall |
|
listdeployableunits |
DeploymentMBean → getDeployableUnits |
About Deployable Units
Below are a definition, preconditions for installing and uninstalling, and an example of a deployable unit.
What is a deployable unit?
A deployable unit is a jar file that can be installed in the SLEE. It contains:
-
a deployment descriptor
-
constituent jar files, with Java class files and deployment descriptors for components such as:
-
SBBs
-
events
-
profile specifications
-
resource adaptor types
-
resource adaptors
-
libraries
-
-
XML files for services.
| |
The JAIN SLEE 1.1 specification defines the structure of a deployable unit. |
Installing and uninstalling deployable units
You must install and uninstall deployable units in a particular order, according to the dependencies of the SLEE components they contain. You cannot install a deployable unit unless either it contains all of its dependencies, or they are already installed. For example, if your deployable unit contains an SBB which depends on a library jar, the library jar must either already be installed in the SLEE, or be included in that same deployable unit jar.
Pre-conditions
A deployable unit cannot be installed if any of the following is true:
-
A deployable unit with the same URL has already been installed in the SLEE.
-
The deployable unit contains a component with the same name, vendor and version as a component of the same type that is already installed in the SLEE.
-
The deployable unit contains a component that references other components that are not yet installed in the SLEE and are not included in the deployable unit jar. (For example, an SBB component may reference event-type components and profile-specification components that are not included or pre-installed.)
A deployable unit cannot be uninstalled if either of the following is true:
-
There are any dependencies on any of its components from components in other installed deployable units. For example, if a deployable unit contains an SBB jar that depends on a profile-specification jar contained in a second deployable unit, the deployable unit containing the profile-specification jar cannot be uninstalled while the deployable unit containing the SBB jar remains installed.
-
There are "instances" of components contained in the deployable unit. For example, a deployable unit containing a resource adaptor cannot be uninstalled if the SLEE includes resource adaptor entities of that resource adaptor.
Deployable unit example
The following example illustrates the deployment descriptor for a deployable unit jar file:
<deployable-unit> <description> ... </description> ... <jar> SomeProfileSpec.jar </jar> <jar> BarAddressProfileSpec.jar </jar> <jar> SomeCustomEvent.jar </jar> <jar> FooSBB.jar </jar> <jar> BarSBB.jar </jar> ... <service-xml> FooService.xml </service-xml> ... </deployable-unit>
The content of the deployable unit jar file is as follows:
META-INF/deployable-unit.xml META-INF/MANIFEST.MF ... SomeProfileSpec.jar BarAddressProfileSpec.jar SomeCustomEvent.jar FooSBB.jar BarSBB.jar FooService.xml ...
Installing Deployable Units
To install a deployable unit, use the following rhino-console command or related MBean operation.
Console commands: install, installlocaldu
Commands |
Installing from a URL
install <url> [-type <type>] [-installlevel <level>]
Description
Install a deployable unit jar or other artifact. To install something other
than a deployable unit, the -type option must be specified. The -installlevel
option controls to what degree the deployable artifact is installed
Installing from a local file
installlocaldu <file url> [-type <type>] [-installlevel <level>] [-url url]
Description
Install a deployable unit or other artifact. This command will attempt to
forward the file content (by reading the file) to rhino if the management client
is on a different host. To install something other than a deployable unit, the
-type option must be specified. The -installlevel option controls to what
degree the deployable artifact is installed. The -url option allows the
deployment unit to be installed with an alternative URL identifier
|
|---|---|
Examples |
To install a deployable unit from a given URL: $ ./rhino-console install file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar installed: DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar] To install a deployable unit from the local file system of the management client: $ ./rhino-console installlocaldu file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar installed: DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar] |
MBean operation: install
MBean |
|
|---|---|
SLEE-defined |
Install a deployable unit from a given URL
public DeployableUnitID install(String url)
throws NullPointerException, MalformedURLException,
AlreadyDeployedException, DeploymentException,
ManagementException;
Installs the given deployable unit jar file into the SLEE. The given URL must be resolvable from the Rhino node. |
Rhino extension |
Install a deployable unit from a given byte array
public DeployableUnitID install(String url, byte[] content)
throws NullPointerException, MalformedURLException,
AlreadyDeployedException, DeploymentException,
ManagementException;
Installs the given deployable unit jar file into the SLEE. The caller passes the actual file contents of the deployable unit in a byte array as a parameter to this method. The SLEE then installs the deployable unit as if it were from the URL. |
Uninstalling Deployable Units
To uninstall a deployable unit, use the following rhino-console command or related MBean operation.
| |
A deployable unit cannot be uninstalled if it contains any components that any other deployable unit installed in the SLEE depends on. |
Console command: uninstall
Command |
uninstall <url>
Description
Uninstall a deployable unit jar
|
|---|---|
Examples |
To uninstall a deployable unit which was installed with the given URL: $ ./rhino-console uninstall file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar uninstalled: DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar] |
Console command: cascadeuninstall
Command |
cascadeuninstall <type> <url|component-id> [-force] [-s]
Description
Cascade uninstall a deployable unit or copied component. The optional -force
argument prevents the command from prompting for confirmation before the
uninstall occurs. The -s argument removes the shadow from a shadowed component
and is not valid for deployable units
|
|---|---|
Examples |
To uninstall a deployable unit which was installed with the given URL and all deployable units that depend on this: $ ./rhino-console cascadeuninstall du file:du/ocsip-ra-2.3.1.17.du.jar
Cascade removal of deployable unit file:du/ocsip-ra-2.3.1.17.du.jar requires the following operations to be performed:
Deployable unit file:jars/sip-registrar-service.jar will be uninstalled
SBB with SbbID[name=RegistrarSbb,vendor=OpenCloud,version=1.8] will be uninstalled
Service with ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8] will be uninstalled
This service will first be deactivated
Deployable unit file:jars/sip-presence-service.jar will be uninstalled
SBB with SbbID[name=EventStateCompositorSbb,vendor=OpenCloud,version=1.0] will be uninstalled
SBB with SbbID[name=NotifySbb,vendor=OpenCloud,version=1.1] will be uninstalled
SBB with SbbID[name=PublishSbb,vendor=OpenCloud,version=1.0] will be uninstalled
Service with ServiceID[name=SIP Notification Service,vendor=OpenCloud,version=1.1] will be uninstalled
This service will first be deactivated
Service with ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1] will be uninstalled
This service will first be deactivated
Service with ServiceID[name=SIP Publish Service,vendor=OpenCloud,version=1.0] will be uninstalled
This service will first be deactivated
Deployable unit file:jars/sip-proxy-service.jar will be uninstalled
SBB with SbbID[name=ProxySbb,vendor=OpenCloud,version=1.8] will be uninstalled
Service with ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8] will be uninstalled
This service will first be deactivated
Deployable unit file:du/ocsip-ra-2.3.1.17.du.jar will be uninstalled
Resource adaptor with ResourceAdaptorID[name=OCSIP,vendor=OpenCloud,version=2.3.1] will be uninstalled
Resource adaptor entity sipra will be removed
This resource adaptor entity will first be deactivated
Link name OCSIP bound to this resource adaptor entity will be removed
Continue? (y/n): y
Deactivating service ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8]
Deactivating service ServiceID[name=SIP Notification Service,vendor=OpenCloud,version=1.1]
Deactivating service ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1]
Deactivating service ServiceID[name=SIP Publish Service,vendor=OpenCloud,version=1.0]
Deactivating service ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8]
All necessary services are inactive
Deactivating resource adaptor entity sipra
All necessary resource adaptor entities are inactive
Uninstalling deployable unit file:jars/sip-registrar-service.jar
Uninstalling deployable unit file:jars/sip-presence-service.jar
Uninstalling deployable unit file:jars/sip-proxy-service.jar
Unbinding resource adaptor entity link name OCSIP
Removing resource adaptor entity sipra
Uninstalling deployable unit file:du/ocsip-ra-2.3.1.17.du.jar
|
MBean operation: uninstall
MBean |
|
|---|---|
SLEE-defined |
public void uninstall(DeployableUnitID id)
throws NullPointerException, UnrecognizedDeployableUnitException,
DependencyException, InvalidStateException, ManagementException;
Uninstalls the given deployable unit jar file (along with all the components it contains) out of the SLEE. |
Listing Deployable Units
To list the installed deployable units, use the following rhino-console command or related MBean operation.
Console command: listdeployableunits
Command |
listdeployableunits
Description
List the current installed deployable units
|
|---|---|
Example |
To list the currently installed deployable units: $ ./rhino-console listdeployableunits DeployableUnitID[url=file:/home/rhino/rhino/examples/sip-examples-2.0/lib/jsip-library-du-1.2.jar] DeployableUnitID[url=file:/home/rhino/rhino/lib/javax-slee-standard-types.jar] |
MBean operation: getDeployableUnits
MBean |
|
|---|---|
SLEE-defined |
public DeployableUnitID[] getDeployableUnits()
throws ManagementException;
Returns the set of deployable unit identifiers that identify all the deployable units installed in the SLEE. |
Services
As well as an overview of SLEE services, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:
| Procedure | rhino-console command(s) | MBean → Operation(s) |
|---|---|---|
listservices |
Deployment → getServices |
|
listservicesbystate |
Service Management → getServices |
|
activateservice |
Service Management → activate |
|
deactivateservice |
Service Management → deactivate |
|
deactivateandactivateservice |
Service Management → deactivateAndActivate |
|
listserviceralinks |
Deployment → getServices |
|
listsbbs |
Deployment → getSbbs |
|
|
|
Deployment → getDescriptors |
|
getservicemetricsrecordingenabled |
ServiceManagementMBean → getServiceMetricsRecordingEnabled |
|
setservicemetricsrecordingenabled |
ServiceManagementMBean → setServiceMetricsRecordingEnabled |
|
About Services
The SLEE specification presents the operational lifecycle of a SLEE service — illustrated, defined and summarised below.
| |
What are SLEE services?
Services are SLEE components that provide the application logic to act on input from resource adaptors. |
Service lifecycle states
| State | Definition |
|---|---|
INACTIVE |
The service has been installed successfully and is ready to be activated, but not yet running. The SLEE will not create SBB entities of the service’s root SBB, to process events. |
ACTIVE |
The service is running. The SLEE will create SBB entities, of the service’s root SBB, to process initial events. The SLEE will also deliver events to SBB entities of the service’s SBBs, as appropriate. |
STOPPING |
The service is deactivating. Existing SBB entities of the service continue running and may complete their processing. But the SLEE will not create new SBB entities of the service’s root SBB, for new activities. |
| |
When the SLEE can reclaim all of a service’s SBB entities, it transitions out of the STOPPING state and returns to the INACTIVE state. |
Independent operational states
As explained in About SLEE Operational States, each event-router node in a Rhino cluster maintains its own lifecycle state machine, independent of other nodes in the cluster. This is also true for each service: one service might be INACTIVE on one node in a cluster, ACTIVE on another, and STOPPING on a third. The operational state of a service on each cluster node also persists to the disk-based database.
A service will enter the INACTIVE state, after node bootup and initialisation completes, if the database’s persistent operational state information for that service is missing, or is set to INACTIVE or STOPPING.
And, like node operational states, you can change the operational state of a service at any time, as long as least one node in the cluster is available to perform the management operation (regardless of whether or not the node whose operational state being changed is a current cluster member). For example, you might activate a service on node 103 before node 103 is booted — then, when node 103 boots, and after it completes initialisation, that service will transition to the ACTIVE state.
Configuring services
An administrator can configure a service before deployment by modifying its service-jar.xml deployment descriptor (in its deployable unit). This includes specifying:
-
the address profile table to use when a subscribed address selects initial events for the service’s root SBB
-
the default event-router priority for the SLEE to give to root SBB entities of the service when processing initial events.
Individual SBBs used in a service can also have configurable properties or environment entries. Values for these environment entries are defined in the sbb-jar.xml deployment descriptor included in the SBB’s component jar. Administrators can set or adjust the values for each environment entry before the SBB is installed in the SLEE.
The SLEE only reads the configurable properties defined for a service or SBB deployment descriptor at deployment time. If you need to change the value of any of these properties, you’ll need to:
-
uninstall the related component (service or SBB whose properties you want to configure) from the SLEE
-
change the properties
-
reinstall the component
-
uninstall and reinstall other components (as needed) to satisfy dependency requirements enforced by the SLEE.
All Available Services
To list all available services installed in the SLEE, use the following rhino-console command or related MBean operation.
Console command: listservices
Command |
listservices
Description
List the current installed services
|
|---|---|
Example |
$ ./rhino-console listservices ServiceID[name=SIP AC Location Service,vendor=OpenCloud,version=1.7] ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8] ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8] |
MBean operation: getServices
MBean |
|
|---|---|
SLEE-defined |
public ServiceID[] getServices() throws ManagementException; This operation returns an array of service component identifiers, identifying the services installed in the SLEE. |
| |
See also Services by State. |
Services by State
To list a specified activation state, use the following rhino-console command or related MBean operation.
Console command: listservicesbystate
Command |
listservicesbystate <state> [-node node]
Description
List the services that are in the specified state (on the specified node)
|
|---|---|
Output |
The activation state of a service is node-specific. If the |
Example |
To list the services in the ACTIVE state on node 102: $ ./rhino-console listservicesbystate Active -node 102 Services in Active state on node 102: ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8] ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8] |
MBean operation: getServices
MBean |
|
|---|---|
SLEE-defined |
Get services on all nodes
public ServiceID[] getServices(ServiceState state) throws NullPointerException, ManagementException; Rhino’s implementation of the SLEE-defined |
Rhino extension |
Get services on specific nodes
public ServiceID[] getServices(ServiceState state, int nodeID)
throws NullPointerException, InvalidArgumentException,
ManagementException;
Rhino provides an extension that adds an argument that lets you control the nodes on which to list services in a particular state (by specifying node IDs). |
| |
See also All Available Services. |
Activating Services
To activate one or more services, use the following rhino-console command or related MBean operation.
Console command: activateservice
Command |
activateservice <service-id>* [-nodes node1,node2,...] [-ifneeded]
Description
Activate a service (on the specified nodes)
|
|---|---|
Example |
To activate the Call Barring and Call Forwarding services on nodes 101 and 102: $ ./rhino-console activateservice \ "name=Call Barring Service,vendor=OpenCloud,version=0.2" \ "name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \ -nodes 101,102 Activating services [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2], ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.2]] on node(s) [101,102] Services transitioned to the Active state on node 101 Services transitioned to the Active state on node 102 |
MBean operation: activate
MBean |
|
|---|---|
SLEE-defined |
Activate on all nodes
public void activate(ServiceID id)
throws NullPointerException, UnrecognizedServiceException,
InvalidStateException, InvalidLinkNameBindingStateException,
ManagementException;
public void activate(ServiceID[] ids)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
InvalidLinkNameBindingStateException, ManagementException;
Rhino’s implementation of the SLEE-defined |
Rhino extension |
Activate on specific nodes
public void activate(ServiceID id, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
ManagementException;
public void activate(ServiceID[] ids, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
ManagementException;
Rhino provides an extension that adds a argument to let you control the nodes on which to activate the specified services (by specifying node IDs). For this to work, the specified services must be in the INACTIVE state on the specified nodes. |
| |
A service may require resource adaptor entity link names to be bound to appropriate resource adaptor entities before it can be activated. (See Getting Link Bindings Required by a Service and Managing Resource Adaptor Entity Link Bindings.) |
Deactivating Services
To deactivate one or more services on one or more nodes, use the following rhino-console command or related MBean operation.
Console command: deactivateservice
Command |
deactivateservice <service-id>* [-nodes node1,node2,...] [-ifneeded]
Description
Deactivate a service (on the specified nodes)
|
|---|---|
Example |
To deactivate the Call Barring and Call Forwarding services on nodes 101 and 102: $ ./rhino-console deactivateservice \
"name=Call Barring Service,vendor=OpenCloud,version=0.2" \
"name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \
-nodes 101,102
Deactivating services [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2],
ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.2]] on node(s) [101,102]
Services transitioned to the Stopping state on node 101
Services transitioned to the Stopping state on node 102
|
MBean operation: deactivate
MBean |
|
|---|---|
SLEE-defined |
Deactivate on all nodes
public void deactivate(ServiceID id)
throws NullPointerException, UnrecognizedServiceException,
InvalidStateException, ManagementException;
public void deactivate(ServiceID[] ids)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
ManagementException;
Rhino’s implementation of the SLEE-defined |
Rhino extension |
Deactivate on specific nodes
public void deactivate(ServiceID id, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
ManagementException;
public void deactivate(ServiceID[] ids, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
ManagementException;
Rhino provides an extension that adds an argument that lets you control the nodes on which to deactivate the specified services (by specifying node IDs). For this to work, the specified services must be in the ACTIVE state on the specified nodes. |
Console command: waittilserviceisinactive
Command |
waittilserviceisinactive <service-id> [-timeout timeout] [-nodes node1,node2,...]
Wait for a service to finish deactivating (on the specified nodes) (timing out after N seconds)
|
|---|---|
Example |
To wait for the Call Barring and Call Forwarding services on nodes 101 and 102: $ ./rhino-console waittilserviceisinactive \
"name=Call Barring Service,vendor=OpenCloud,version=0.2" \
"name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \
-nodes 101,102
Service ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2] is in the Inactive state on node(s) [101,102]
Service ServiceID[Call Forwarding Service,vendor=OpenCloud,version=0.2] is in the Inactive state on node(s) [101,102]
|
Upgrading (Activating & Deactivating) Services
To activate some services and deactivate others, use the following rhino-console command or related MBean operation.
| |
Activating and deactivating in one operation
The SLEE specification defines the ability to deactivate some services and activate other services in a single operation. As one set of services deactivates, the existing activities being processed by those services continue to completion, while new activities (started after the operation is invoked) are processed by the activated services. The intended use of this is to upgrade a service or services with new versions (however the operation does not have to be used strictly for this purpose). |
Console command: deactivateandactivateservice
Command |
deactivateandactivateservice Deactivate <service-id>* Activate <service-id>*
[-nodes node1,node2,...]
Description
Deactivate some services and Activate some other services (on the specified
nodes)
|
|---|---|
Example |
To deactivate version 0.2 of the Call Barring and Call Forwarding services and activate version 0.3 of the same services on nodes 101 and 102: $ ./rhino-console deactivateandactivateservice \
Deactivate "name=Call Barring Service,vendor=OpenCloud,version=0.2" \
"name=Call Forwarding Service,vendor=OpenCloud,version=0.2" \
Activate "name=Call Barring Service,vendor=OpenCloud,version=0.3" \
"name=Call Forwarding Service,vendor=OpenCloud,version=0.3" \
-nodes 101,102
On node(s) [101,102]:
Deactivating service(s) [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.2],
ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.2]]
Activating service(s) [ServiceID[name=Call Barring Service,vendor=OpenCloud,version=0.3],
ServiceID[name=Call Forwarding Service,vendor=OpenCloud,version=0.3]]
Deactivating service(s) transitioned to the Stopping state on node 101
Activating service(s) transitioned to the Active state on node 101
Deactivating service(s) transitioned to the Stopping state on node 102
Activating service(s) transitioned to the Active state on node 102
|
MBean operation: deactivateAndActivate
MBean |
|
|---|---|
SLEE-defined |
Deactivate and activate on all nodes
public void deactivateAndActivate(ServiceID deactivateID, ServiceID activateID)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
InvalidLinkNameBindingStateException, ManagementException;
public void deactivateAndActivate(ServiceID[] deactivateIDs, ServiceID[] activateIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
InvalidLinkNameBindingStateException, ManagementException;
Rhino’s implementation of the SLEE-defined |
Rhino extension |
Deactivate and activate on specific nodes
public void deactivateAndActivate(ServiceID deactivateID, ServiceID activateID, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
ManagementException;
public void deactivateAndActivate(ServiceID[] deactivateIDs, ServiceID[] activateIDs, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedServiceException, InvalidStateException,
ManagementException;
Rhino provides an extension that adds an argument that lets you control the nodes on which to activate and deactivate services (by specifying node IDs). For this to work, the services to deactivate must be in the ACTIVE state, and the services to activate must be in the INACTIVE state, on the specified nodes. |
Getting Link Bindings Required by a Service
To find the resource adaptor entity link name bindings needed for a service, and list the service’s SBBs, use the following rhino-console commands or related MBean operations.
Console commands
listserviceralinks
Command |
listserviceralinks service-id
Description
List resource adaptor entity links required by a service
|
|---|---|
Example |
To list the resource adaptor entity links that the JCC VPN service needs: $ ./rhino-console listserviceralinks "name=JCC 1.1 VPN,vendor=Open Cloud,version=1.0"
In service ServiceID[name=JCC 1.1 VPN,vendor=Open Cloud,version=1.0]:
SBB SbbID[name=AnytimeInterrogation sbb,vendor=Open Cloud,version=1.0] requires entity link bindings: slee/resources/map
SBB SbbID[name=JCC 1.1 VPN sbb,vendor=Open Cloud,version=1.0] requires entity link bindings: slee/resources/cdr
|
listsbbs
Command |
listsbbs [service-id]
Description
List the current installed SBBs. If a service identifier is specified only the
SBBs in the given service are listed
|
|---|---|
Example |
To list the SBBs in the JCC VPN service: $ ./rhino-console listsbbs "name=JCC 1.1 VPN,vendor=Open Cloud,version=1.0" SbbID[name=AnytimeInterrogation sbb,vendor=Open Cloud,version=1.0] SbbID[name=JCC 1.1 VPN sbb,vendor=Open Cloud,version=1.0] SbbID[name=Proxy route sbb,vendor=Open Cloud,version=1.0] |
MBean operations: getServices, getSbbs, and getDescriptors
MBean |
|||
|---|---|---|---|
SLEE-defined |
Get all services in the SLEE
public ServiceID[] getServices()
throws ManagementException;
Get all SBBs in a service
public SbbID[] getSbbs(ServiceID service)
throws NullPointerException, UnrecognizedServiceException,
ManagementException;
Get the component descriptor for a component
public ComponentDescriptor[] getDescriptors(ComponentID[] ids)
throws NullPointerException, ManagementException;
|
Configuring service metrics recording status
To check and configure the status for recording service metrics, use the following rhino-console commands or related MBean operations.
The details for metrics stats are listed in Metrics.Services.cmp and Metrics.Services.lifecycle.
| |
The default is set to disabled for performance consideration. |
Console commands
getservicemetricsrecordingenabled
Command |
getservicemetricsrecordingenabled <service-id>
Description
Determine if metrics recording for a service has been enabled
|
|---|---|
Example |
To check the status for recording metrics: $ ./rhino-console getservicemetricsrecordingenabled name=service1,vendor=OpenCloud,version=1.0 Metrics recording for ServiceID[name=service1,vendor=OpenCloud,version=1.0] is currently disabled |
setservicemetricsrecordingenabled
Command |
setservicemetricsrecordingenabled <service-id> <true|false>
Description
Enable or disable the recording of metrics for a service
|
|---|---|
Example |
To enable the recording metrics: $ ./rhino-console setservicemetricsrecordingenabled name=service1,vendor=OpenCloud,version=1.0 true Metrics recording for ServiceID[name=service1,vendor=OpenCloud,version=1.0] has been enabled |
MBean operations: getServiceMetricsRecordingEnabled and setServiceMetricsRecordingEnabled
MBean |
|
|---|---|
Rhino extension |
Determine if the recording of metrics for a service is currently enabled or disabled.
public boolean getServiceMetricsRecordingEnabled(ServiceID service)
throws NullPointerException, UnrecognizedServiceException, ManagementException;
Enable or disable the recording of metrics for a service.
public void setServiceMetricsRecordingEnabled(ServiceID service, boolean enabled)
throws NullPointerException, UnrecognizedServiceException, ManagementException;
|
Resource Adaptor Entities
As well as an overview of resource adaptor entities, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:
| Procedure | rhino-console command | MBean → Operation |
|---|---|---|
listraconfigproperties |
Resource Management → getConfigurationProperties |
|
createraentity |
Resource Management → createResourceAdaptorEntity |
|
removeraentity |
Resource Management → removeResourceAdaptorEntity |
|
listraentityconfigproperties |
Resource Management → getConfigurationProperties |
|
updateraentityconfigproperties |
Resource Management → updateConfigurationProperties |
|
activateraentity |
Resource Management → activateResourceAdaptorEntity |
|
deactivateraentity |
Resource Management → deactivateResourceAdaptorEntity |
|
reassignactivities |
Resource Management → reassignActivities |
|
getraentitystate |
Resource Management → getState |
|
listraentitiesbystate |
Resource Management → getResourceAdaptorEntities |
|
bindralinkname |
Resource Management → bindLinkName |
|
unbindralinkname |
Resource Management → unbindLinkName |
|
listralinknames |
Resource Management → getLinkNames |
About Resource Adaptor Entities
Resource adaptors (RAs) are SLEE components which let particular network protocols or APIs be used in the SLEE.
They typically include a set of configurable properties (such as address information of network endpoints, URLs to external systems, or internal timer-timeout values). These properties may include default values. A resource adaptor entity is a particular configured instance of a resource adaptor, with defined values for all of that RA’s configuration properties.
The resource adaptor entity lifecycle
The SLEE specification presents the operational lifecycle of a resource adaptor entity — illustrated, defined, and summarised below.
Resource adaptor entity lifecycle states
The SLEE lifecycle states are:
| State | Definition |
|---|---|
INACTIVE |
The resource adaptor entity has been configured and initialised. It is ready to be activated, but may not yet create activities or fire events to the SLEE. Typically, it is not connected to network resources. |
ACTIVE |
The resource adaptor entity is connected to the resources it needs to function (assuming they are available), and may create activities and fire events to the SLEE. |
STOPPING |
The resource adaptor entity may not create new activities in the SLEE, but may fire events to the SLEE on already existing activities. A resource adaptor entity transitions out of the STOPPING state, returning to the INACTIVE state, when all activities it owns have either ended or been assigned to another node for continued processing. |
| |
Creating activities in the STOPPING state
By default, Rhino 2.6 prevents a resource adaptor from creating an activity in the This behaviour is controlled by the When set to The default value in earlier versions of Rhino was |
Independent lifecycle state machines
As explained in About SLEE Operational States, each event-router node in a Rhino cluster maintains its own lifecycle state machine, independent of other nodes in the cluster. This is also true for each resource adaptor entity: one resource adaptor entity might be INACTIVE on one node in a cluster, ACTIVE on another, and STOPPING on a third. The operational state of a resource adaptor entity on each cluster node also persists to the disk-based database.
A resource adaptor entity will enter the INACTIVE state, after node bootup and initialisation completes, if the database’s persistent operational state information for that resource adaptor entity is missing, or is set to INACTIVE or STOPPING.
And, like node operational states, you can change the operational state of a resource adaptor entity at any time, as long as least one node in the cluster is available to perform the management operation (regardless of whether or not the node whose operational state being changed is a current cluster member). For example, you might activate a resource adaptor entity on node 103 before node 103 is booted — then, when node 103 boots, and after it completes initialisation, that resource adaptor entity will transition to the ACTIVE state.
Finding RA Configuration Properties
To determine resource adaptor configuration properties (which you need to know when Creating a Resource Adaptor Entity) use the following rhino-console command or related MBean operation.
Console command: listraconfigproperties
Command |
listraconfigproperties <resource-adaptor-id>
Description
List the configuration properties (and any default values) for a resource
adaptor
|
|---|---|
Example |
To list the configuration properties of the OpenCloud SIP Resource Adaptor: $ ./rhino-console listraconfigproperties name=OCSIP,vendor=OpenCloud,version=2.1 Configuration properties for resource adaptor name=OCSIP,vendor=OpenCloud,version=2.1: Automatic100TryingSupport (java.lang.Boolean): true CRLLoadFailureRetryTimeout (java.lang.Integer): 900 CRLNoCRLLoadFailureRetryTimeout (java.lang.Integer): 60 CRLRefreshTimeout (java.lang.Integer): 86400 CRLURL (java.lang.String): ... |
MBean operation: getConfigurationProperties
MBean |
|
|---|---|
SLEE-defined |
public ConfigProperties getConfigurationProperties(ResourceAdaptorID id)
throws NullPointerException, UnrecognizedResourceAdaptorException,
ManagementException
|
Output |
This operation returns a |
Creating a Resource Adaptor Entity
To create a resource adaptor entity use the following rhino-console command or related MBean operation.
Console command: createrantity
Command |
createraentity <resource-adaptor-id> <entity-name>
[<config-params>|(<property-name> <property-value)*]
Description
Create a resource adaptor entity with the given name. Optionally configuration
properties can be specified, either as a single comma-separated string of
name=value pairs, or as a series of separate name and value argument pairs
|
||
|---|---|---|---|
Example |
To create an instance of the OpenCloud SIP resource adaptor, called $ ./rhino-console createraentity name=OCSIP,vendor=OpenCloud,version=2.1 sipra \
IPAddress=192.168.0.100,Port=5160,SecurePort=5161
Created resource adaptor entity sipra
|
||
Notes |
Entering configuration properties
When creating a resource adaptor entity, determine its configuration properties and then enter them in
|
MBean operation: createResourceAdaptorEntity
MBean |
|||||
|---|---|---|---|---|---|
SLEE-defined |
public void createResourceAdaptorEntity(ResourceAdaptorID id, String entityName, ConfigProperties properties)
throws NullPointerException, InvalidArgumentException,
UnrecognizedResourceAdaptorException,
ResourceAdaptorEntityAlreadyExistsException,
InvalidConfigurationException, ManagementException;
|
||||
Arguments |
This operation requires that you specify the resource adaptor entity’s:
|
Removing a Resource Adaptor Entity
To remove a resource adaptor entity use the following rhino-console command or related MBean operation.
| |
You can only remove a resource adaptor entity from the SLEE when it is in the INACTIVE state on all event-router nodes currently in the primary component. |
Console command: removeraentity
Command |
removeraentity <entity-name>
Description
Remove a resource adaptor entity
|
|---|---|
Example |
To remove the resource adaptor entity named $ ./rhino-console removeraentity sipra Removed resource adaptor entity sipra |
MBean operation: removeResourceAdaptorEntity
MBean |
|
|---|---|
SLEE-defined |
public void removeResourceAdaptorEntity(String entityName)
throws NullPointerException,
UnrecognizedResourceAdaptorEntityException,
InvalidStateException, DependencyException, ManagementException;
|
Listing configuration properties for a Resource Adaptor Entity
To list the configuration properties for a resource adaptor entity use the following rhino-console command or related MBean operation.
Console command: listraentityconfigproperties
Command |
listraentityconfigproperties <entity-name>
Description
List the configuration property values for a resource adaptor entity
|
|---|---|
Example |
To list the resource adaptor entity called $ ./rhino-console listraentityconfigproperties sipra Configuration properties for resource adaptor entity sipra: Automatic100TryingSupport (java.lang.Boolean): true AutomaticOptionsResponses (java.lang.Boolean): true CRLLoadFailureRetryTimeout (java.lang.Integer): 900 CRLNoCRLLoadFailureRetryTimeout (java.lang.Integer): 60 CRLRefreshTimeout (java.lang.Integer): 86400 CRLURL (java.lang.String): ClientAuthentication (java.lang.String): NEED EnableDialogActivityTests (java.lang.Boolean): false EnabledCipherSuites (java.lang.String): ExtensionMethods (java.lang.String): IPAddress (java.lang.String): AUTO Keystore (java.lang.String): sip-ra-ssl.keystore KeystorePassword (java.lang.String): KeystoreType (java.lang.String): jks MaxContentLength (java.lang.Integer): 131072 OffsetPorts (java.lang.Boolean): false Port (java.lang.Integer): 5060 PortOffset (java.lang.Integer): 101 ReplicatedDialogSupport (java.lang.Boolean): false RetryAfterInterval (java.lang.Integer): 5 SecurePort (java.lang.Integer): 5061 TCPIOThreads (java.lang.Integer): 1 Transports (java.lang.String): udp,tcp Truststore (java.lang.String): sip-ra-ssl.truststore TruststorePassword (java.lang.String): TruststoreType (java.lang.String): jks UseVirtualAddressInURIs (java.lang.Boolean): true ViaSentByAddress (java.lang.String): VirtualAddresses (java.lang.String): WorkerPoolSize (java.lang.Integer): 4 WorkerQueueSize (java.lang.Integer): 50 slee-vendor:com.opencloud.rhino_max_activities (java.lang.Integer): 0 slee-vendor:com.opencloud.rhino_replicate_activities (java.lang.String): mixed |
MBean operation: getConfigurationProperties
MBean |
|
|---|---|
SLEE-defined |
public ConfigProperties getConfigurationProperties(String entityName)
throws NullPointerException, UnrecognizedResourceAdaptorEntityException, ManagementException;
|
Output |
This operation returns a |
Updating configuration properties for a Resource Adaptor Entity
To update configuration properties for a resource adaptor entity use the following rhino-console command or related MBean operation.
| |
When is it appropriate to update configuration properties?
A resource adaptor may elect to support reconfiguration when its resource adaptor entities are active using the If the value of the If the value of the |
Console command: updateraentityconfigproperties
Command |
updateraentityconfigproperties <entity-name> [<config-params>|(<property-name>
<property-value)*]
Description
Update configuration properties for a resource adaptor entity. Properties can be
specified either as a single comma-separated string of name=value pairs or as a
series of separate name and value argument pairs
|
|---|---|
Example |
To update the $ ./rhino-console updateraentityconfigproperties sipra Port 5061 SecurePort 5062 Updated configuration parameters for resource adaptor entity sipra |
MBean operation: updateConfigurationProperties
MBean |
|
|---|---|
SLEE-defined |
public void updateConfigurationProperties(String entityName, ConfigProperties properties)
throws NullPointerException, UnrecognizedResourceAdaptorEntityException,
InvalidStateException, InvalidConfigurationException,
ManagementException;
|
Input |
This operation requires a |
Activating a Resource Adaptor Entity
To activate a resource adaptor entity on one or more nodes use the following rhino-console command or related MBean operation.
Console command: activateraentity
Command |
activateraentity <entity-name> [-nodes node1,node2,...] [-ifneeded]
Description
Activate a resource adaptor entity (on the specified nodes)
|
|---|---|
Example |
To activate the resource adaptor entity called $ ./rhino-console activateraentity sipra -nodes 101,102 Activating resource adaptor entity sipra on node(s) [101,102] Resource adaptor entity transitioned to the Active state on node 101 Resource adaptor entity transitioned to the Active state on node 102 |
MBean operation: activateResourceAdaptorEntity
MBean |
|
|---|---|
SLEE-defined |
Activate on all nodes
public void activateResourceAdaptorEntity(String entityName)
throws NullPointerException, UnrecognizedResourceAdaptorEntityException,
InvalidStateException, ManagementException;
Rhino’s implementation of the SLEE-defined |
Rhino extension |
Activate on specific nodes
public void activateResourceAdaptorEntity(String entityName, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedResourceAdaptorEntityException,
InvalidStateException, ManagementException;
Rhino provides an extension that adds an argument that lets you control the nodes on which to activate the resource adaptor entity (by specifying node IDs). For this to work, the resource adaptor entity must be in the INACTIVE state on the specified nodes. |
Deactivating a Resource Adaptor Entity
To deactivate a resource adaptor entity on one or more nodes use the following rhino-console command or related MBean operation.
| |
See also Reassigning a Resource Adaptor Entity’s Activities to Other Nodes, particularly the Requirements tab. |
Console command: deactivateraentity
Command |
deactivateraentity <entity-name> [-nodes node1,node2,... [-reassignto
node3,node4,...]] [-ifneeded]
Description
Deactivate a resource adaptor entity (on the specified nodes (reassigning
replicated activities to the specified nodes))
|
|---|---|
Examples |
To deactivate the resource adaptor entity named $ ./rhino-console deactivateraentity sipra -nodes 101,102 Deactivating resource adaptor entity sipra on node(s) [101,102] Resource adaptor entity transitioned to the Stopping state on node 101 Resource adaptor entity transitioned to the Stopping state on node 102 To deactivate the resource adaptor entity named $ ./rhino-console deactivateraentity sipra -nodes 101 -reassignto 102 Deactivating resource adaptor entity sipra on node(s) [101] Resource adaptor entity transitioned to the Stopping state on node 101 Replicated activities reassigned to node(s) [102] To deactivate the resource adaptor entity named $ ./rhino-console deactivateraentity sipra -nodes 101 -reassignto "" Deactivating resource adaptor entity sipra on node(s) [101] Resource adaptor entity transitioned to the Stopping state on node 101 Replicated activities reassigned to node(s) [102,103] |
MBean operation: deactivateResourceAdaptorEntity
MBean |
|
|---|---|
SLEE-defined |
Deactivate on all nodes
public void deactivateResourceAdaptorEntity(String entityName)
throws NullPointerException, UnrecognizedResourceAdaptorEntityException,
InvalidStateException, ManagementException;
Rhino’s implementation of the SLEE-defined |
Rhino extensions |
Deactivate on specific nodes
public void deactivateResourceAdaptorEntity(String entityName, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedResourceAdaptorEntityException, InvalidStateException,
ManagementException;
Rhino provides an extension that adds an argument that lets you control the nodes on which to deactivate the resource adaptor entity (by specifying node IDs). For this to work, the resource adaptor entity must be in the ACTIVE state on the specified nodes.
Reassign deactivating activities to other nodes
public void deactivateResourceAdaptorEntity(String entityName, int[] nodeIDs, int[] reassignActivitiesToNodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedResourceAdaptorEntityException, InvalidStateException,
ManagementException;
Rhino also provides an extension that adds another argument, that lets you reassign ownership of replicated activities (from a replicating resource adaptor entity), distributing them equally among other available event-router nodes. This reduces the set of activities on the nodes with the deactivating resource adaptor entity, so the resource adaptor entity can return to the INACTIVE state on those nodes quicker. This only works for resource adaptor entities that are replicating activity state (see the description of the "Rhino-defined configuration property" for the MBean on Creating a Resource Adaptor Entity). |
Reassigning a Resource Adaptor Entity’s Activities to Other Nodes
To reassign activities from a resource adaptor entity to a different node, use the following rhino-console command or related MBean operation, noting the requirements.
| |
Why reassign replicating activities?
A resource adaptor entity in the STOPPING state cannot return to the INACTIVE state until all the activities that it owns have ended. You can let a deactivating resource adaptor entity return to the INACTIVE state quicker by reassigning its replicating activities to other eligible nodes. |
Console command: reassignactivities
Command |
reassignactivities <entity-name> -from node1,node2,... -to node3,node4,...
Description
Reassign replicated activities of a resource adaptor entity from the specified
nodes to other nodes
|
||
|---|---|---|---|
Examples |
To reassign activities owned by the resource adaptor entity named $ ./rhino-console reassignactivities sipra -from 101 -to 102,103 Replicated activities for sipra reassigned to node(s) [102,103]
To reassign activities owned by the resource adaptor entity named $ ./rhino-console reassignactivities sipra -from 101 -to "" Replicated activities for sipra reassigned to node(s) [102,103] |
MBean operation: reassignActivities
MBean |
|
|---|---|
Rhino extension |
public void reassignActivities(String entityName, int[] fromNodeIDs, int[] toNodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedResourceAdaptorEntityException,
InvalidStateException, ManagementException;
This operation reassigns replicated activities owned by the named resource adaptor entity, on the nodes specified, using Rhino’s standard failover algorithm, to the nodes specified by the |
Requirements for reassigning activities
You can only reassign replicated activities from a resource adaptor entity to other nodes if the all the following conditions are satisfied:
-
The node is a current member of the primary component.
-
The node is an event-router node (not a quorum node).
-
The operational state of the SLEE on the node is RUNNING or STOPPING.
-
The operational state of the resource adaptor entity on the node is ACTIVE or STOPPING.
Further, a node can only take ownership of replicated activities if it satisfies all the following conditions:
-
The node is a current member of the primary component.
-
The node is an event-router node (not a quorum node).
-
The operational state of the SLEE on the node is RUNNING.
-
The operational state of the resource adaptor entity on the node is ACTIVE.
Also, non-replicated activities cannot be reassigned to other nodes, and a resource adaptor entity must end any non-replicated activities it created itself.
| |
You can choose to forcefully remove activities if a resource adaptor entity fails to end them in a timely manner. |
Retrieving a Resource Adaptor Entity’s State
To retrieve the operational state of a resource adaptor entity, use the following rhino-console command or related MBean operation.
Console command: getraentitystate
Command |
getraentitystate <entity-name> [-nodes node1,node2,...]
Description
Get the state of a resource adaptor entity (on the specified nodes)
|
|---|---|
Output |
The |
Examples |
To display the state of the resource adaptor entity with the name $ ./rhino-console getraentitystate sipra Resource adaptor entity is Inactive on node 101 Resource adaptor entity is Active on node 102 To display the state of the resource adaptor entity on only node 101: $ ./rhino-console getraentitystate sipra -nodes 101 Resource adaptor entity is Inactive on node 101 |
MBean operation: getState
MBean |
|
|---|---|
SLEE-defined |
Return state of resource adaptor entity on current node
public ResourceAdaptorEntityState getState(String entityName)
throws NullPointerException,
UnrecognizedResourceAdaptorEntityException,
ManagementException;
Rhino’s implementation of the SLEE-defined |
Rhino extension |
Return state of resource adaptor entity on specified node(s)
public ResourceAdaptorEntityState[] getState(String entityName, int[] nodeIDs)
throws NullPointerException, InvalidArgumentException,
UnrecognizedResourceAdaptorEntityException, ManagementException;
Rhino provides an extension that adds an argument which lets you control the nodes on which to return the state of the resource adaptor entity (by specifying node IDs). |
Listing Resource Adaptor Entities by State
To list resource adaptor entities in a particular operational state, use the following rhino-console command or related MBean operation.
Console command: listraentitiesbystate
Command |
listraentitiesbystate <state> [-node node]
Description
List the resource adaptor entities that are in the specified state (on the
specified node)
|
|---|---|
Examples |
To list the resource adaptor entities on the node where $ ./rhino-console listraentitiesbystate Active No resource adaptor entities in Active state on node 101 To list the resource adaptor entities that are active on node 102: $ ./rhino-console listraentitiesbystate Active -node 102 Resource adaptor entities in Active state on node 102: sipra |
MBean operation: getResourceAdaptorEntities
MBean |
|
|---|---|
SLEE-defined |
Return names of resource adaptor entities in specified state on current node
public String[] getResourceAdaptorEntities(ResourceAdaptorEntityState state)
throws NullPointerException, ManagementException;
Rhino’s implementation of the SLEE-defined |
Rhino extension |
Return names of resource adaptor entities in specified state on specified node
public String[] getResourceAdaptorEntities(ResourceAdaptorEntityState state, int nodeID)
throws NullPointerException, InvalidArgumentException,
ManagementException;
Rhino provides an extension that lets you specify the nodes (by specifying node IDs) on which to return the names of resource adaptor entities in the specified state. |
Managing Resource Adaptor Entity Link Bindings
| |
What are resource adaptor entity link name bindings?
When an SBB needs access to a resource adaptor entity, it uses JNDI to get references to Java objects that implement the resource adaptor interface (provided by the resource adaptor entity). The SBB declares (in its deployment descriptor) the resource adaptor type it expects, and an arbitrary link name. Before activating a service using the SBB, an administrator must bind a resource adaptor entity (of the type expected) to the specified link name. |
Rhino includes procedures for:
Binding a Resource Adaptor Entity to a Link Name
To bind a resource adaptor entity to a link name, use the following rhino-console command or related MBean operation.
| |
Only one resource adaptor entity can be bound to a link name at any time. |
Console command: bindralinkname
Command |
bindralinkname <entity-name> <link-name>
Description
Bind a resource adaptor entity to a link name
|
|---|---|
Example |
To bind the resource adaptor entity with the name $ ./rhino-console bindralinkname sipra sip Bound sipra to link name sip |
MBean operation: bindLinkName
MBean |
|
|---|---|
SLEE-defined |
public void bindLinkName(String entityName, String linkName)
throws NullPointerException, InvalidArgumentException,
UnrecognizedResourceAdaptorEntityException,
LinkNameAlreadyBoundException, ManagementException;
|
Unbinding Link Names
To unbind a resource adaptor entity from a link name, use the following rhino-console command or related MBean operation.
Console command: unbindralinkname
Command |
unbindralinkname <link-name>
Description
Unbind a resource adaptor entity from a link name
|
|---|---|
Example |
To unbind the link name $ ./rhino-console unbindralinkname sip Unbound link name sip |
MBean operation: unbindLinkName
MBean |
|
|---|---|
SLEE-defined |
public void unbindLinkName(String linkName)
throws NullPointerException, UnrecognizedLinkNameException,
DependencyException,ManagementException;
|
Listing Link Name Bindings
To list resource adaptor entity link names that have been bound in the SLEE, use the following rhino-console command or related MBean operation.
Console command: listralinknames
Command |
listralinknames [entity name]
Description
List the bound link names (for the specified resource adaptor entity)
|
|---|---|
Examples |
To list all resource adaptor entity link name bindings: $ ./rhino-console listralinknames slee/resources/cdr -> cdrra slee/resources/map -> mapra To list all link name bindings for the resource adaptor entity named $ ./rhino-console listralinknames mapra slee/resources/map |
MBean operation: getLinkNames
MBean |
|
|---|---|
SLEE-defined |
List all bound link names
public String[] getLinkNames()
throws ManagementException;
Rhino’s implementation of the SLEE-defined
List link names to which a specific resource adaptor entity has been bound
public String[] getLinkNames(String entityName)
throws NullPointerException,
UnrecognizedResourceAdaptorEntityException,
ManagementException;
The SLEE-defined operation also includes an argument for returning just link names to which a specified resource adaptor entity has been bound. If the resource adaptor entity has not been bound to any link names, the returned array is zero-length. |
Profile Tables and Profiles
As well as an overview of SLEE profiles, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:
| Procedure | rhino-console command(s) | MBean(s) → Operation |
|---|---|---|
createprofiletable |
Profile Provisioning → createProfileTable |
|
createprofile |
Profile Provisioning → createProfile |
|
listprofiletables |
Profile Provisioning → getProfileTables |
|
listprofiles |
Profile Provisioning → getProfiles |
|
listprofileattributes |
Profile Provisioning, Profile → getProfile |
|
setprofileattributes |
Profile Provisioning, Profile → getProfile |
|
listprofilesbyattribute |
Profile Provisioning → getProfilesByAttribute |
|
exportall |
Profile Provisioning → exportProfiles |
| |
See also the New SLEE 1.1 Profile Features How-to Guide on the OpenCloud Developer Portal. |
About Profiles
| |
What are profiles? profile tables? profile specifications?
A profile is an entry in a profile table. It has a name, may have values (called "attributes") and may have indexed fields. It’s like a row in SQL, but may also include business and management logic. A profile table is a "container" for profiles. Its specification schema, the profile specification deployment descriptor, may define queries for the profile table. The SLEE specification defines the format and structure of profile specification schemas. A profile table’s default profile is the initial set of profile attribute values for newly created profiles within that table (if not specified explicitly with the profile-creation command). |
Before deploying a profile into the SLEE, an administrator can configure its profile specification. You do this by modifying values in the profile’s profile-spec-jar.xml deployment descriptor (in its deployable unit). For example, you can specify:
-
static queries available to SLEE components, and administrators using the management interface
-
profile specification environment entries
-
indexing hints for profile attributes.
| |
For more on profile static queries, environment entires and indexing, see the SLEE 1.1 specification. |
Creating Profile Tables
To create a new profile table based on an already-deployed profile specification, use the following rhino-console command or related MBean operation.
| |
Name character restriction
The profile table name cannot include the |
Console command: createprofiletable
Command |
createprofiletable <profile-spec-id> <table-name>
Description
Create a profile table
|
|---|---|
Example |
$ ./rhino-console createprofiletable name=AddressProfileSpec,vendor=javax.slee,version=1.1 testtable Created profile table testtable |
MBean operation: createProfileTable
MBean |
|
|---|---|
SLEE-defined |
public void createProfileTable(javax.slee.profile.ProfileSpecificationID id, String newProfileTableName)
throws NullPointerException, UnrecognizedProfileSpecificationException,
InvalidArgumentException, ProfileTableAlreadyExistsException,
ManagementException;
|
Arguments |
This operation requires that you specify the profile table’s:
|
Creating Profiles
To create a profile in an existing profile table, use the following rhino-console command or related MBean operation.
Console command createprofile
Command |
createprofile <table-name> <profile-name> (<attr-name> <attr-value>)*
Description
Add a profile to a table, optionally setting attributes (see
-setProfileAttributes option)
Add a profile to a table, optionally setting attributes (See Setting Profile attributes) |
|---|---|
Example |
$ ./rhino-console createprofile testtable testprofile Profile testtable/testprofile created |
Notes |
Setting profile attributes
When creating a profile, decide the profile’s attribute names and then enter them in
White space, commas, quotes
If a profile or profile table name or an attribute name or value contains white space or a comma, you must quote the string. For example: $ ./rhino-console createprofile "testtable 2" "testprofile 2" SubscriberAddress "my address" forwarding true If the value requires quotes, you must escape them using a backslash "\" (to avoid them being removed by the parser). For example: $ ./rhino-console createprofile testtable testprofile attrib "\"The quick brown fox\""
Name uniqueness
The profile name must be unique within the scope of the profile table. |
MBean operation: createProfile
MBean |
|
|---|---|
SLEE-defined |
public javax.management.ObjectName createProfile(String profileTableName, String newProfileName)
throws NullPointerException, UnrecognizedProfileTableNameException,
InvalidArgumentException, ProfileAlreadyExistsException,
ManagementException;
|
Arguments |
This operation requires that you specify the profile’s:
|
Notes |
Profile MBean commit state
This operation returns an
Name uniqueness
The profile name must be unique within the scope of the profile table. |
Listing Profile Tables
To list all profile tables in a SLEE, use the following rhino-console command or related MBean operation.
Console command: listprofiletables
Command |
listprofiletables
Description
List the current created profile tables
|
|---|---|
Example |
$ ./rhino-console listprofiletables callbarring callforwarding |
MBean operation: getProfileTables
MBean |
|
|---|---|
SLEE-defined |
public Collection getProfileTables()
throws ManagementException;
|
Listing Profiles
To list all profiles of a specific profile table, use the following rhino-console command or related MBean operation.
Console command: listprofiles
Command |
listprofiles <table-name>
Description
List the profiles in a table
|
|---|---|
Example |
$ ./rhino-console listprofiles testtable testprofile |
MBean operation: getProfiles
MBean |
|
|---|---|
SLEE-defined |
public Collection getProfiles(String profileTableName)
throws NullPointerException, UnrecognizedProfileTableNameException,
ManagementException;
|
Arguments |
This operation requires that you specify the profile table’s:
|
Listing Profile Attributes
To list a profile’s attributes (names and current values), use the following rhino-console command or related MBean operation.
Console command: listprofileattributes
Command |
listprofileattributes <table-name> [profile-name]
Description
List the current values of a profile, or if no profile is specified the current
values of the default profile are listed
|
|---|---|
Example |
$ ./rhino-console listprofileattributes testtable testprofile
Address={null}
|
MBean operation: getProfile
MBean |
|||
|---|---|---|---|
SLEE-defined |
public javax.management.ObjectName getProfile(String profileTableName,String profileName)
throws NullPointerException, UnrecognizedProfileTableNameException,
UnrecognizedProfileNameException, ManagementException;
|
||
Arguments |
This operation requires that you specify the profile table’s:
|
||
Notes |
Profile MBean state
This operation returns an
|
Setting Profile Attributes
To set a profile’s attribute values, use the following rhino-console command or related MBean operation.
Console command: setprofileattributes
Command |
setprofileattributes <table-name> <profile-name> (<attr-name> <attr-value>)*
Description
Set the current values of a profile (use "" for default profile). The
implementation supports only a limited set of attribute types that it can
convert from strings to objects
|
|---|---|
Example |
$ ./rhino-console setprofileattributes testtable testprofile Address IP:192.168.0.1 Set attributes in profile testtable/testprofile |
Notes |
White space, commas, quotes
If a profile or profile table name or an attribute name or value contains white space or a comma, you must quote the string. For example: $ ./rhino-console setprofileattributes "testtable 2" "testprofile 2" SubscriberAddress "my address" forwarding true If the value requires quotes, you must escape them using a backslash "\" (to avoid them being removed by the parser). For example: $ ./rhino-console setprofileattributes testtable testprofile attrib "\"The quick brown fox\"" |
MBean operation: getProfile
MBean |
|||
|---|---|---|---|
SLEE-defined |
public javax.management.ObjectName getProfile(String profileTableName,String profileName)
throws NullPointerException, UnrecognizedProfileTableNameException,
UnrecognizedProfileNameException, ManagementException;
|
||
Arguments |
This operation requires that you specify the profile table’s:
|
||
Notes |
Profile MBean state
This operation returns an To put the MBean into the read-write state, invoke
|
Finding Profiles by Attribute Value
To retrieve all profiles with a specific attribute value, use the following rhino-console commands or related MBean operations:
Console command: listprofilesbyattribute
Command |
listprofilesbyattribute <table-name> <attr-name> <attr-value>
[display-attributes (true/false)]
Description
List the profile which have an attribute <attr-name> equal to <attr-value>. The
implementation supports only a limited set of attribute types that it can
convert from strings to objects
|
|---|---|
Example |
$ ./rhino-console listprofilesbyattribute testtable Address IP:192.168.0.1 1 profiles returned ProfileID[table=testtable,profile=testprofile] |
Notes |
SLEE 1.1- & SLEE 1.0-specific commands
Between SLEE 1.0 and SLEE 1.1, the underlying profile specification schema changed significantly. According to the SLEE 1.1 Specification, profile attributes no longer have to be indexed to be legally used by a find-by-attribute-value query. Therefore, the
Backwards compatibility
SLEE 1.1 demands backwards compatibility for SLEE 1.0-compliant profiles, which means a SLEE 1.0 -compliant profile specification can be deployed into the SLEE; and profile tables and profiles can be successfully created and managed. |
Console command: listprofilesbyindexedattribute
Command |
listprofilesbyindexedattribute <table-name> <attr-name> <attr-value>
[display-attributes (true/false)]
Description
List the profiles which have an indexed attribute <attr-name> equal to
<attr-value>. The implementation supports only a limited set of attribute types
that it can convert from strings to objects
|
|---|---|
Example |
$ ./rhino-console listprofilesbyindexedattribute testtable indexedAttrib someValue 1 profiles returned ProfileID[table=testtable,profile=testprofile] |
MBean operation: getProfilesByAttribute
MBean |
|
|---|---|
SLEE-defined |
public Collection getProfilesByAttribute(String profileTableName, String attributeName, Object attributeValue)
throws NullPointerException, UnrecognizedProfileTableNameException,
UnrecognizedAttributeException, InvalidArgumentException,
AttributeTypeMismatchException, ManagementException;
|
Arguments |
This operation requires that you specify the:
|
Notes |
SLEE 1.1- & SLEE 1.0-specific commands
Between SLEE 1.0 and SLEE 1.1, the underlying profile specification schema changed significantly. According to the SLEE 1.1 Specification, profile attributes no longer have to be indexed to be legally used by a find-by-attribute-value query. Therefore, the
Backwards compatibility
SLEE 1.1 demands backwards compatibility for SLEE 1.0-compliant profiles, which means a SLEE 1.0 compliant profile specification can be deployed into the SLEE; and profile tables and profiles can be successfully created and managed. |
MBean operation: getProfilesByIndexedAttribute
MBean |
|
|---|---|
SLEE-defined |
public Collection getProfilesByIndexedAttribute(String profileTableName, String attributeName, Object attributeValue)
throws NullPointerException, UnrecognizedProfileTableNameException,
UnrecognizedAttributeException, AttributeNotIndexedException,
AttributeTypeMismatchException, ManagementException;
|
Arguments |
This operation requires that you specify the:
|
Finding Profiles Using Static Queries
To retrieve all profiles match a static query (pre-defined in a profile table’s profile specification schema), use the following MBean operation.
| |
The Rhino SLEE does not use a rhino-console command for this function. |
MBean operation: getProfilesByStaticQuery
MBean |
|
|---|---|
SLEE-defined |
public Collection getProfilesByStaticQuery(String profileTableName, String queryName, Object[] parameters)
throws NullPointerException, UnrecognizedProfileTableNameException,
UnrecognizedQueryNameException, InvalidArgumentException,
AttributeTypeMismatchException, ManagementException;
|
Arguments |
This operation requires that you specify the:
|
| |
For more about static query methods, please see chapter 10.8.2 "Static query methods" in the SLEE 1.1 specification. |
Finding Profiles Using Dynamic Queries
To retrieve all profiles match a dynamic query (an expression the administrator constructs at runtime) , use the following MBean operation.
| |
The Rhino SLEE does not use a rhino-console command for this function. |
MBean operation: getProfilesByDynamicQuery
MBean |
|
|---|---|
SLEE-defined |
public Collection getProfilesByDynamicQuery(String profileTableName, QueryExpression expr)
throws NullPointerException, UnrecognizedProfileTableNameException,
UnrecognizedAttributeException, AttributeTypeMismatchException,
ManagementException;
|
Arguments |
This operation requires that you specify the:
|
| |
For more about dynamic query methods, please see chapter 10.20.3 "Dynamic Profile queries" in the SLEE 1.1 specification. |
Exporting Profiles
To export SLEE profiles, use the following rhino-console command or related MBean operation.
Console command: exportall
| |
The Rhino command console currently does not have a command specific to profile exports. Instead you use a more general export function, which (apart from SLEE profiles) also exports deployable units for services and RAs currently installed in the SLEE. |
Command |
exportall <target directory>
Description
Export the internal state of the SLEE including deployable units, profile
tables, and other component state. Uses JMX to export profiles and writes XML.
Use the standalone rhino-export utility to export profile snapshots
|
|---|---|
Example |
$ ./rhino-console exportall /home/userXY/myexport Exporting file:jars/incc-callbarring-service.jar... Exporting file:jars/incc-callforwarding-service.jar... Taking snapshot for callforwarding Saving callforwarding.jar (183kb) Streaming profile table 'callforwarding' snapshot to callforwarding.data (2 entries) [################################################################################] 2/2 entries Taking snapshot for callbarring Saving callbarring.jar (177kb) Streaming profile table 'callbarring' snapshot to callbarring.data (2 entries) [################################################################################] 2/2 entries Extracted 4 of 4 entries (157 bytes) Snapshot timestamp 2008-05-07 15:17:42.325 (1210130262325) Critical region time : 0.002 s Request preparation time : 0.053 s Data extraction time : 0.302 s Total time : 0.355 s Converting 2 profile table snapshots... Converting callforwarding... bean class=class com.opencloud.deployed.Profile_Table_2.ProfileOCBB_Bean [###########################################################################] converted 2 of 2 [###########################################################################] converted 2 of 2 Converted 2 records Converting callbarring... bean class=class com.opencloud.deployed.Profile_Table_1.ProfileOCBB_Bean [###########################################################################] converted 2 of 2 [###########################################################################] converted 2 of 2 Converted 2 records Export complete |
| |
Exported profile files
After the export, you will find the exported profiles as .xml files in the
Exporting "snapshots"
See also Profile Snapshots, to export profile snapshots in binary format and convert them into
Exporting a SLEE
See also Exporting a SLEE, to export all deployed components and configuration of a Rhino SLEE. |
MBean operation: exportProfiles
MBean |
|||
|---|---|---|---|
Rhino extension |
com.opencloud.rhino.management.profile.ProfileDataCollection exportProfiles(String profileTableName, String[] profileNames)
throws NullPointerException, UnrecognizedProfileTableNameException,
ManagementException;
|
||
Arguments |
This operation requires that you specify the profile table’s:
|
Importing Profiles
To import SLEE profiles, use the following rhino-console command or related MBean operation.
Console command: importprofiles
| |
Use the importprofiles command to import profile data from an xml file that has previously been created (for example, using the exportall command). |
Command |
importprofiles <filename.xml> [-table table-name] [-replace] [-max
profiles-per-transaction] [-noverify]
Description
Import profiles from xml data
|
|---|---|
Example |
$ ./rhino-console exportall /home/userXY/myexport ... ./rhino-console importprofiles /home/userXY/myexport/profiles/testtable.xml Importing profiles into profile table: testtable 2 profile(s) processed: 1 created, 0 replaced, 0 removed, 1 skipped |
Notes |
Referenced profile table must exist
For the profile import to run successfully, the profile table the xml data refers to must exist before invoking the |
MBean operation: importProfiles
MBean |
|||
|---|---|---|---|
Rhino extension |
com.opencloud.rhino.management.profile.ProfileImportResult importProfiles(com.opencloud.rhino.management.profile.ProfileDataCollection profileData)
throws NullPointerException, UnrecognizedProfileTableNameException,
InvalidArgumentException, ProfileAlreadyExistsException,
UnrecognizedProfileNameException, ManagementException;
|
||
Arguments |
This operation requires that you specify the profile table’s:
|
Alarms
As well as an overview and list of alarms, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs.
| Procedure | rhino-console command | MbBean → Operations |
|---|---|---|
listactivealarms |
Alarm → getAlarms Alarm → getDescriptors |
|
clearalarm |
Alarm → clearAlarm |
|
clearalarms |
Alarm → clearAlarms |
|
setalarmlogperiod getalarmlogperiod |
Logging Management → SetAlarmLogPeriod Logging Management → GetAlarmLogPeriod |
|
createthresholdrule removethresholdrule |
Threshold Rule Management → createRule Threshold Rule Management → removeRule |
|
listthresholdrules |
Threshold Rule Management → getRules |
|
|
getconfig exportconfig importconfig |
Threshold Rule → addTriggerCondition Threshold Rule → getTriggerConditions Threshold Rule → removeTriggerCondition Threshold Rule → getTriggerConditionsOperator Threshold Rule → setTriggerConditionsOperator Threshold Rule → getTriggerPeriod Threshold Rule → setTriggerPeriod Threshold Rule → addResetCondition Threshold Rule → getResetConditions Threshold Rule → removeResetCondition Threshold Rule → getResetConditionsOperator Threshold Rule → setResetConditionsOperator Threshold Rule → getResetPeriod Threshold Rule → setResetPeriod Threshold Rule → setAlarm Threshold Rule → getAlarmLevel Threshold Rule → getAlarmType Threshold Rule → getAlarmMessage |
activatethresholdrule |
Threshold Rule → activateRule Threshold Rule → deactivateRule |
|
getthresholdrulescanperiod setthresholdrulescanperiod |
Threshold Rule Management → getScanPeriod Threshold Rule Management → setScanPeriod |
About Alarms
Alarms in Rhino alert the SLEE administrator to exceptional conditions.
Application components in the SLEE raise them, as does Rhino itself (upon detecting an error condition). Rhino clears some alarms automatically when the error conditions are resolved. The SLEE administrator must clear others manually.
When an alarm is raised or cleared, Rhino generates a JMX notification from the Alarm MBean. Management clients may attach a notification listener to the Alarm MBean, to receive alarm notifications. Rhino logs all alarm notifications.
What’s new in SLEE 1.1?
While only SBBs could generate alarms in SLEE 1.0, other types of application components can also generate alarms in SLEE 1.1.
In SLEE 1.1, alarms are stateful — between being raised and cleared, an alarm persists in the SLEE, where an administrator may examine it. (In SLEE 1.0, alarms could be generated with a severity level that indicated a cleared alarm, but the fact that an error condition had occurred did not persist in the SLEE beyond the initial alarm generation.)
Sample log file messages
SLEE 1.1 |
|
|---|---|
SLEE 1.0 |
|
| |
For both SLEE 1.1 and 1.0, if the cause of an alarm is an Java exception, the log includes the exception and its stack trace (following the alarm description message). |
| |
See also the How Do I Use Stateful Alarms in SLEE 1.1 on the OpenCloud Developer Portal. |
Configuring alarm log period
To set and get the interval between periodic active alarm logs, use the following rhino-console commands or related MBean operations.
Rhino periodically logs active alarms and the default interval is 60 seconds.
setalarmlogperiod
Command |
setalarmlogperiod <seconds>
Description
Sets the interval between periodic active alarm logs.
Required Arguments
seconds The interval between periodic alarm logs. Setting to 0 will disable
logging of periodic alarms.
|
|---|---|
Example |
To set log period to 30 seconds: $ ./rhino-console setalarmlogperiod 30 Active alarm logging period set to 30 seconds. |
getalarmlogperiod
Command |
getalarmlogperiod
Description
Returns the interval between periodic active alarm logs.
|
|---|---|
Example |
To get alarm log period: $ ./rhino-console getalarmlogperiod Active alarm logging period is currently 30 seconds. |
MBean operations: setAlarmLogPeriod
MBean |
|
|---|---|
SLEE-defined |
Set the interval between periodic active alarm logs
public void setAlarmLogPeriod(int period) throws IllegalArgumentException, ConfigurationException; Sets the interval between periodic active alarm logs. Setting the period to 0 will disable periodic alarm logging.
Get the interval between periodic active alarm logs
public int getAlarmLogPeriod() throws ConfigurationException; Returns the interval between periodic active alarm logs. |
Viewing Active Alarms
To view active alarms, use the following rhino-console command or related MBean operation.
Console command: listactivealarms
Command |
listactivealarms [<type> <notif-source>] [-stack]
Description
List the alarms currently active in the SLEE (for a specific notification if
provided). Use -stack to display stack traces for alarm cause exceptions.
|
|---|---|
Example |
To list all active alarms in the SLEE: $ ./rhino-console listactivealarms 1 alarm: Alarm 101:193215480667648 [diameter.peer.connectiondown] Level : Warning InstanceID : diameter.peer.hss-instance Source : (RA Entity) sh-cache-ra Timestamp : 20161019 14:02:58 (active 15m 30s) Message : Connection to hss-instance:3868 is down The number value on the first line "101:193215480667648" is the The value in the square brackets "diameter.peer.connectiondown" is the |
MBean operations: getAlarms and getDescriptors
MBean |
|
|---|---|
SLEE-defined |
Get identifiers of all active alarms in the SLEE
public String[] getAlarms()
throws ManagementException;
Rhino’s implementation of the SLEE-defined
Get identifiers of active alarms raised by a specific notification source
public String[] getAlarms(NotificationSource notificationSource)
throws NullPointerException, UnrecognizedNotificationSourceException,
ManagementException;
This variant of
Get alarm descriptor for an alarm identifier
public Alarm[] getDescriptors(String[] alarmIDs)
throws NullPointerException, ManagementException;
This operation returns the |
Clear Individual Alarms
To clear an alarm using its alarm identifier, use the following rhino-console command or related MBean operation.
Console command: clearalarm console command
Command |
clearalarm <alarmid>
Description
Clear the specified alarm.
|
|---|---|
Example |
To clear the alarm with the identifier $ ./rhino-console clearalarm 101:102916243593:1 Alarm 101:102916243593:1 cleared |
MBean operation: clearAlarm
MBean |
|
|---|---|
SLEE-defined |
public boolean clearAlarm(String alarmID) throws NullPointerException, ManagementException; Rhino’s implementation of the SLEE-defined |
Clear Alarms Raised by a Particular Notification Source
To clear alarms raised by a particular notification source, use the following rhino-console command or related MBean operation.
Console command: clearalarms
Command |
clearalarms <type> <notification-source> [<alarm type>]
Description
Clear all alarms raised by the notification source (of the specified alarm type)
This command clears all alarms of the specified alarm type (or all alarms if no alarm-type is specified), that have been raised by the specified notification source. |
|---|---|
Example |
To clear all alarms raised by a resource adaptor entity named $ ./rhino-console clearalarms resourceadaptorentity insis-cap 2 alarms cleared To clear only "noconnection" alarms raised by the resource adaptor entity named $ ./rhino-console clearalarms resourceadaptorentity insis-cap noconnection 1 alarm cleared |
MBean operation: clearAlarms
MBean |
|
|---|---|
SLEE-defined |
Clear all active alarms raised by a notification source
public int clearAlarms(NotificationSource notificationSource)
throws NullPointerException, UnrecognizedNotificationSourceException,
ManagementException
Rhino’s implementation of the SLEE-defined
Clear active alarms of a specified type raised by a notification source
public int clearAlarms(NotificationSource notificationSource, String alarmType)
throws NullPointerException, UnrecognizedNotificationSourceException,
ManagementException;
This variant of |
Threshold Alarms
To supplement standard alarms (which Rhino and installed components raise), an administrator may configure custom alarms (which Rhino will raise or clear automatically based on SLEE Statistics.
These are known as threshold alarms, and you manage them using the Threshold Rule Management MBean.
Threshold rules
You configure the threshold rules governing each threshold alarm using a Threshold Rule MBean.
Each threshold rule consists of:
-
a unique name identifying the rule
-
one or more trigger conditions
-
an alarm level, type and message text
-
and optionally:
-
one or more reset conditions
-
how long (in milliseconds) the trigger conditions must remain before Rhino raises the alarm
-
how long (in milliseconds) the reset conditions must remain before Rhino clears the alarm.
-
| |
You can combine condition sets using either an AND or an OR operator. (AND means all conditions must be satisfied, whereas OR means any one of the conditions may be satisfied — to raise or clear the alarm.) |
Parameter sets
Threshold rules use the same parameter sets as the statistics client. You can discover them either by using the statistics client graphically or by using its command-line mode from a command shell as shown below.
$ ./rhino-stats -l The following root parameter sets are available for monitoring: Activities, ActivityHandler, ByteArrayBuffers, CGIN, DatabaseQuery, Diameter, EndpointLimiting, EventRouter, Events, HTTP, JDBCDatasource, JVM, LicenseAccounting, Limiters, LockManagers, MemDB-Local, MemDB-Replicated, MemDB-Timestamp, Metrics, ObjectPools, SIP, SIS-SIP, SLEE-Usage, Services, StagingThreads, StagingThreads-Misc, TimerFacility, TransactionManager For parameter set type descriptions and a list of available parameter sets use the -l <root parameter set name> option
$ ./rhino-stats -l JVM
Connecting to localhost:1199
Parameter Set: JVM
Parameter Set Type: JVM
Description: JVM Statistics
Counter type statistics:
Id: Name: Label: Description:
0 heapUsed husd Used heap memory
1 heapCommitted hcomm Committed heap memory
2 heapInitial hinit Initial heap memory
3 heapMaximum hmax Maximum heap memory
4 nonHeapUsed nhusd Used non-heap memory
5 nonHeapCommitted nhcomm Committed non-heap memory
6 nonHeapInitial nhinit Initial non-heap memory
7 nonHeapMaximum nhmax Maximum non-heap memory
8 classesCurrentLoaded cLoad Number of classes currently loaded
9 classesTotalLoaded cTotLoad Total number of classes loaded since JVM start
10 classesTotalUnloaded cTotUnload Total number of classes unloaded since JVM start
Sample type statistics: (none defined)
Found 1 parameter sets under 'JVM':
-> "JVM"
How Rhino evaluates threshold rules
Rhino periodically evaluates the trigger conditions of each configured rule. When a trigger condition is satisfied and its trigger period has been met or exceeded, Rhino raises the corresponding alarm. If the rule has reset conditions, Rhino evaluates those too, and when the reset condition is satisfied and the reset trigger period has been met or exceeded, clears the alarm. If the rule does not have reset conditions, an administrator must clear the alarm manually.
You can configure the frequency of threshold alarm rule evaluation, using the Threshold Rule Management MBean. An administrator can specify a polling frequency in milliseconds, or enter 0 to disable rule evaluation. The Rhino default is 0 (which must be changed to enable threshold-rule evaluation). Ideal polling frequency is highly dependent on the nature of alarms configured.
Simple and relative rule conditions
There are two types of threshold rule conditions, explained in the tables below.
Simple rule conditions
| What it compares | Operators for comparison | Conditions | Example |
|---|---|---|---|
|
The value of a counter-type Rhino statistic against a constant value. |
>, >=, <, ⇐, ==, != |
The constant value to compare against may be any floating-point number. The condition can either compare against the absolute value of the statistic (suitable for gauge-type statistics), or against the observed difference between successive samples (suitable for pure counter-type statistics). |
A condition that selects the statistic |
Relative rule conditions
| What it compares | Operators for comparison | Conditions | Example |
|---|---|---|---|
|
The ratio between two monitored statistics against a constant value. |
>, >=, <, ⇐, ==, != |
The constant value to compare against may be any floating-point number. |
A condition that selects the statistics |
| |
For definitions of counter, guage and sample type statistics, see About Rhino Statistics. |
| |
See also:
|
Creating and Removing Rules
To create or remove a threshold-alarm rule, use the following rhino-console commands or related MBean operations.
Console command: createthresholdrule
Command |
createthresholdrule <name>
Description
Create a threshold alarm rule
|
|---|---|
Example |
To create a rule named "low memory": $ ./rhino-console createthresholdrule "low memory" Threshold rule low memory created |
MBean operation: createRule
MBean |
|
|---|---|
Rhino operation |
public ObjectName createRule(String ruleName)
throws ConfigurationException, ValidationException;
This operation creates a rule with the name given, and returns the JMX object name of a |
Console command: removethresholdrule
Command |
removethresholdrule <name>
Description
Remove a threshold alarm rule
|
|---|---|
Example |
To remove a rule named "low memory": $ ./rhino-console removethresholdrule "low memory" Threshold rule low memory removed |
MBean operation: removeRule
MBean |
|
|---|---|
Example |
public void removeRule(String ruleName)
throws ConfigurationException, ValidationException;
This operation removes the rule with the name given. |
Listing Rules
To list all threshold alarm rules, use the following rhino-console command or related MBean operation.
Console command: listthresholdrules
Command |
listthresholdrules
Description
List threshold alarm rules
|
|---|---|
Example |
To list all threshold alarm rules, with their activation states: $ ./rhino-console listthresholdrules
Current threshold rules:
low memory (active)
low disk (inactive)
testrule (inactive)
|
MBean operation: getRules
MBean |
|
|---|---|
Rhino operation |
public String[] getRules()
throws ConfigurationException;
|
Configuring Rules
To configure a threshold alarm rule:
-
use the following rhino-console commands to view available rules, export a rule to an XML file, edit the rule file, and then re-import the edited file into the SLEE
-
or use Threshold Rule MBean operations.
View rules
To view a current threshold alarm rule., use the getconfig console command:
Command |
getconfig [-namespace] <configuration type> [configuration key]
Description
Extract and display content of a container configuration key. The optional
-namespace argument must be used to get the config of a namespace-specific key.
If no key is specified the configs of all keys of the given type are shown
|
|---|---|
Example |
To display the threshold alarm rule named "low_memory": $ ./rhino-console getconfig threshold-rules "rule/low_memory"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rhino-threshold-rules-config PUBLIC "-//Open Cloud Ltd.//DTD Rhino Threshold Rules Config 2.3//EN" "rhino-threshold-rules-config-2.3.dtd">
<rhino-threshold-rules-config config-version="2.3" rhino-version="Rhino (version='2.5', release='1.0', build=xxx, revision=xxx)" timestamp="xxx">
<!-- Generated Rhino configuration file: xxxx-xx-xx xx:xx:xx.xxx -->
<threshold-rules active="false" name="low_memory">
<trigger-conditions name="Trigger conditions" operator="OR" period="0">
<relative-threshold operator="<=" value="0.2">
<first-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="freePhysicalMemorySize"/>
<second-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="totalPhysicalMemorySize"/>
</relative-threshold>
</trigger-conditions>
<reset-conditions name="Reset conditions" operator="OR" period="0"/>
<trigger-actions>
<raise-alarm-action level="Major" message="Low on memory" type="MEMORY"/>
</trigger-actions>
<reset-actions>
<clear-raised-alarm-action/>
</reset-actions>
</threshold-rules>
</rhino-threshold-rules-config>
|
Export rules
To save a threshold rule configuration to a file for editing, use the exportconfig console command:
Command |
exportconfig [-namespace] <configuration type> [configuration key] <filename>
Description
Extract content of a container configuration key and save it to a file. The
optional -namespace argument must be used to export the config of a
namespace-specific key
|
|---|---|
Example |
To export the threshold alarm rule named "low memory" to the file $ ./rhino-console exportconfig threshold-rules "rule/low memory" rule_low_memory.xml Export threshold-rules: (rule/low memory) to rule_low_memory.xml Wrote rule_low_memory.xml |
| |
The structure of the exported data in the XML file is identical to that displayed by the getconfig command. |
Edit rules
You can modify a rule using a text editor. In the following example, a reset condition has been added to a rule previously exported, so that the alarm raised will automatically clear when free memory becomes greater than 30%. (Previously the reset-conditions element in this rule had no conditions.)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rhino-threshold-rule PUBLIC "-//Open Cloud Ltd.//DTD Rhino Threshold Rule 2.0//EN"
"http://www.opencloud.com/dtd/rhino-config-threshold-rules_2_0.dtd">
<rhino-threshold-rule config-version="2.3" rhino-version="Rhino (version='2.5', release='00',
build=xxx, revision=xxx)" timestamp=xxx>
<!-- Generated Rhino configuration file: xxxx-xx-xx xx:xx:xx.xxx -->
<threshold-rules active="false" name="low memory">
<trigger-conditions name="Trigger conditions" operator="OR" period="0">
<relative-threshold operator="<=" value="0.2">
<first-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="freePhysicalMemorySize"/>
<second-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="totalPhysicalMemorySize"/>
</relative-threshold>
</trigger-conditions>
<reset-conditions name="Reset conditions" operator="OR" period="0">
<relative-threshold operator=">" value="0.3">
<first-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="freePhysicalMemorySize"/>
<second-statistic calculate-delta="false" parameter-set="JVM.OperatingSystem" statistic="totalPhysicalMemorySize"/>
</relative-threshold>
</reset-conditions>
<trigger-actions>
<raise-alarm-action level="Major" message="Low on memory" type="MEMORY"/>
</trigger-actions>
<reset-actions>
<clear-raised-alarm-action/>
</reset-actions>
</threshold-rules>
</rhino-threshold-rule>
Import rules
To import the modified threshold alarm rule file, use the importconfig console command:
Command |
importconfig [-namespace] <configuration type> <filename> [-replace]
Description
Import a container configuration key. The optional -namespace argument must be
used to import a config for a namespace-specific key
|
|---|---|
Example |
To import the threshold alarm rule from the file $ ./rhino-console importconfig threshold-rules rule_low_memory.xml -replace Configuration successfully imported. |
| |
The -replace option is required when importing a rule with the same name as an existing rule, as there can be only one rule configuration with a given name present at any one time. |
Threshold Rule MBean Operations
To configure a threshold alarm rule, use the following MBean operations (defined on the Threshold Rule MBean interface), for:
-
adding, removing and getting trigger conditions, and getting and setting their operators and periods
-
adding, removing and getting reset conditions, and getting and setting their operators and periods
-
setting the alarm
-
getting an alarm’s level, type, and message.
| |
See also Configuring Rules. |
Trigger conditions
To add, remove and get threshold alarm trigger conditions, and get and set their operators and periods, use the following MBean operations:
| Operations | Usage |
|---|---|
|
To add a trigger condition to the rule:
public void addTriggerCondition(String parameterSetName, String statistic, String operator, double value)
throws ConfigurationException, UnknownStatsParameterSetException,
UnrecognizedStatisticException, ValidationException;
public void addTriggerCondition(String parameterSetName1, String statistic1, String parameterSetName2,
String statistic2, String operator, double value
throws ConfigurationException, UnknownStatsParameterSetException,
UnrecognizedStatisticException, ValidationException;
The first operation adds a simple trigger condition to the rule. The second operation adds a relative condition between two parameter set statistics (see Simple and relative rule conditions).
To get the current trigger conditions:
public String[] getTriggerConditions()
throws ConfigurationException;
To remove a trigger condition:
public void removeTriggerCondition(String key)
throws ConfigurationException, ValidationException;
To get or set the trigger condition operator:
public String getTriggerConditionsOperator()
throws ConfigurationException;
public void setTriggerConditionsOperator(String operator)
throws ConfigurationException, ValidationException;
The operator must be one of the logical operators
To get or set the trigger condition period:
public long getTriggerPeriod()
throws ConfigurationException;
public void setTriggerPeriod(long period)
throws ConfigurationException, ValidationException;
The trigger period is measured in milliseconds. If it is |
Reset conditions
To add, remove and get threshold alarm reset conditions, and get and set their operators and periods, use the following MBean operations:
| Operations | Usage |
|---|---|
|
To add a reset condition to the rule:
public void addResetCondition(String parameterSetName, String statistic, String operator, double value)
throws ConfigurationException, UnknownStatsParameterSetException,
UnrecognizedStatisticException, ValidationException;
public void addResetCondition(String parameterSetName1, String statistic1, String parameterSetName2,
String statistic2, String operator, double value)
throws ConfigurationException, UnknownStatsParameterSetException,
UnrecognizedStatisticException, ValidationException;
The first operation adds a simple reset condition to the rule. The second operation adds a relative condition between two parameter set statistics (see bxfref:threshold-alarms[Simple and relative rule conditions]).
To get the current reset conditions:
public String[] getResetConditions()
throws ConfigurationException;
To remove a reset condition:
public void removeResetCondition(String key)
throws ConfigurationException, ValidationException;
To get or set the reset condition operator:
public String getResetConditionsOperator()
throws ConfigurationException;
public void setResetConditionsOperator(String operator)
throws ConfigurationException, ValidationException;
The operator must be one of the logical operators
To get or set the reset condition period:
public long getResetPeriod()
throws ConfigurationException;
public void setResetPeriod(long period)
throws ConfigurationException, ValidationException;
The reset period is measured in milliseconds. If it is |
Setting alarms
To set the alarm to be raised by a threshold rule, use the following MBean operation:
| Operations | Usage |
|---|---|
public void setAlarm(AlarmLevel level, String type, String message)
throws ConfigurationException, ValidationException;
The alarm level may be any level other than |
Getting alarm information
To get a threshold alarm’s level, type, and message, use the following MBean operations:
| Operations | Usage |
|---|---|
public AlarmLevel getAlarmLevel()
throws ConfigurationException;
public String getAlarmType()
throws ConfigurationException;
public String getAlarmMessage()
throws ConfigurationException;
|
Activating and Deactivating Rules
To activate or deactivate a threshold-alarm rule, use the following rhino-console commands or related MBean operations.
Activate Rules
Console command: activatethresholdrule
Command |
activatethresholdrule <name>
Description
Activate a threshold alarm rule
|
|---|---|
Example |
To activate the rule with the name "low memory": $ ./rhino-console activatethresholdrule "low memory" Threshold rule low memory activated |
| |
You can also activate a rule by exporting it, modifying the XML, and then reimporting it (assuming the active parameter in the rule is set to true — see Configuring Rules). |
MBean operation: activateRule
MBean |
|
|---|---|
Rhino operation |
public void activateRule()
throws ConfigurationException;
This operation activates the threshold-alarm rule represented by the |
| |
threshold rule scan period must be configured to a non-zero value before Rhino will evaluate active threshold-alarm rules. |
Deactivate rules
Console command: deactivatethresholdrule
Command |
deactivatethresholdrule <name>
Description
Deactivate a threshold alarm rule
|
|---|---|
Example |
To deactivate the rule with the name "low memory": $ ./rhino-console deactivatethresholdrule "low memory" Threshold rule low memory deactivated |
MBean operation: deactivateRule
MBean |
|
|---|---|
Rhino operation |
public void deactivateRule()
throws ConfigurationException;
This operation deactivates the threshold-alarm rule represented by the |
Setting and Getting Rule-Scan Periods
To set or get the threshold rule scan period, use the following rhino-console commands or MBean operations.
| |
What is a rule-scan period?
A threshold-alarm rule-scan period determines when Rhino’s threshold-rule scanner evaluates active threshold-alarm rules. The scan period must be set to a valid non-zero value for Rhino to evaluate the rules. At the beginning of each scan period, Rhino evaluates each active threshold-alarm rule as follows:
(The same process applies to the reset conditions once a rule has been triggered.) |
Console command: setthresholdrulescanperiod
Command |
setthresholdrulescanperiod <period>
Description
Set the threshold alarm rule scan period, measured in ms. Must be > 500 or 0 to
disable rule checking
|
|---|---|
Example |
To set the threshold rule scan period to 30000ms (30s): $ ./rhino-console setthresholdrulescanperiod 30000 Threshold rule scan period set to 30000ms To disable threshold rule scanning: $ ./rhino-console setthresholdrulescanperiod 0 Threshold rule scanning disabled |
MBean operation: setScanPeriod
MBean |
|
|---|---|
Rhino operation |
public void setScanPeriod(int scanPeriod)
throws ConfigurationException, ValidationException;
The scan period is measured in milliseconds. |
Console command: getthresholdrulescanperiod
Command |
getthresholdrulescanperiod
Description
Get the threshold alarm rule scan period
|
|---|---|
Example |
$ ./rhino-console getthresholdrulescanperiod Threshold rule scan period set to 30000ms |
MBean operation: getScanPeriod
MBean |
|
|---|---|
Rhino operation |
public int getScanPeriod() throws ConfigurationException; The scan period is measured in milliseconds. |
Runtime Alarm List
To list all alarms that may be raised by Rhino and installed components (including their messages, and when raised and cleared), use the following rhino-console command.
Console command: alarmcatalog
Command |
alarmcatalog [-v]
Description
List the alarms that may be raised by Rhino and installed components. Using the
-v flag will display more detail.
|
|---|---|
Example |
And this displays more detail: |
Rhino Alarm List
This is a list of all alarms raised by this version of Rhino. For the management command that lists all alarms that may be raised by Rhino and installed components see Runtime Alarm List.
| Alarm Type | Description |
|---|---|
Category: AbnormalExecution (Alarms raised as a result of an abnormal execution condition being detected) |
|
An uncaught exception has been detected. |
|
Category: Activity Handler (Alarms raised by Rhino activity handler) |
|
The oldest activity handler snapshot is too old. |
|
Category: Clustering (Alarms raised by Rhino cluster state changes) |
|
A node left the cluster for some reason other than a management-initiated shutdown. |
|
Category: Configuration Management (Alarms raised by the Rhino configuration manager) |
|
An error occurred while trying to write the file-based configuration for the configuration type specified in the alarm instance. |
|
An error occurred while trying to read the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file. |
|
An error occurred while trying to activate the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file. |
|
Category: Database (Alarms raised during database communications) |
|
A persistence resource configuration referenced in rhino-config.xml has been removed at runtime. |
|
A persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated. |
|
Rhino requires a backing database for persistence of state for failure recovery purposes. A persistent instance defines a connection to a database backend. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance. |
|
Rhino requires a backing database for persistence of state for failure recovery purposes. If no connection to the database backend is available, state cannot be persisted. |
|
A persistent instance defines the connection to the database backend. If the persistent instance cannot be instantiated then JDBC connections cannot be made. |
|
Category: Event Router State (Alarms raised by event router state management) |
|
A licensing problem was detected during service activation at startup. |
|
A licensing problem was detected during resource adaptor entity activation. |
|
Category: Licensing (Alarms raised by Rhino licensing) |
|
Rate limiter throttling is active. This throttling and hence this alarm only happens in SDK versions of Rhino, not production versions. |
|
A license installed in Rhino has passed its expiry time. |
|
A license installed in Rhino is within seven days of its expiry time. |
|
The hardware addresses listed in a host-based license only partially match those on the host. |
|
The hardware addresses listed in a host-based license do not match those on the host. |
|
Rhino does not have a valid license installed. |
|
The work done by a function exceeds licensed capacity. |
|
A particular function is not licensed. |
|
Category: Limiting (Alarms raised by Rhino limiting) |
|
A rate limiter is below negative capacity. |
|
Category: Logging (Alarms raised by Rhino logging) |
|
An appender has thrown an exception when attempting to pass log messages from a logger to it. |
|
Category: M-lets Startup (Alarms raised by the M-let starter) |
|
The M-Let starter component could not register itself with the platform MBean server. This normally indicates a serious JVM misconfiguration. |
|
The M-Let starter component could not register an MBean for a configured m-let. This normally indicates an error in the m-let configuration file. |
|
Category: REM Startup (Alarms raised by embedded REM starter) |
|
This version of Rhino is supposed to contain an embedded instance of REM but it was not found, most likely due to a packaging error. |
|
There was an unexpected problem while starting the embedded REM. This could be because of a port conflict or packaging problem. |
|
Rhino Element Manager requires Java 1.8, but Rhino was started using Java 1.7 |
|
Category: Runtime Environment (Alarms related to the runtime environment) |
|
This JVM is not a Sun/Oracle JVM. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start. |
|
This Java version is not a supported major version. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start. |
|
This Java version is older than the minimum recommended update. A Rhino instance will start, but will always raise this alarm. |
|
SLEE event-routing functions failed to start after node restart |
|
Filenames with the maximum length expected by Rhino are unsupported on this filesystem. Unexpected deployment errors may occur as a result |
|
Category: SAS facility (Alarms raised by Rhino SAS Facility) |
|
Attempting to reconect to SAS server |
|
SAS message queue is full. Some events have not been reported to SAS |
|
Category: SNMP (Alarms raised by Rhino SNMP) |
|
The SNMP agent listens for requests received on all network interfaces that match the requested SNMP configuration. If no suitable interfaces can be found that match the requested configuration, then the SNMP agent cannot process any SNMP requests. |
|
The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If no ports could be bound, the SNMP agent cannot process any SNMP requests. |
|
The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If this succeeds on some (but not all) interfaces, the SNMP agent can only process requests received via the interfaces that succeeded. |
|
This is a catchall alarm for unexpected failures during agent startup. If an unexpected failure occurs, the state of the SNMP agent is unpredictable and requests may not be successfully processed. |
|
This alarm represents a failure to determine an address from the notification target configuration. This can occur if the notification hostname is not resolvable, or if the specified hostname is not parseable. |
|
Multiple parameter set type configurations for in-use parameter set types map to the same OID. All parameter set type mappings will remain inactive until the conflict is resolved. |
|
Multiple counters in the parameter set type configuration map to the same index. The parameter set type mappings will remain inactive until the conflict is resolved. |
|
Category: Scattercast Management (Alarms raised by Rhino scattercast management operations) |
|
Reboot needed to make scattercast update active. |
|
Category: Service State (Alarms raised by service state management) |
|
The service threw an exception during service activation at startup. |
|
Category: Threshold Rules (Alarms raised by the threshold alarm rule processor) |
|
A threshold rule trigger or reset rule failed. |
|
A threshold rule trigger or reset rule refers to an unknown statistics parameter set. |
|
Category: Watchdog (Alarms raised by the watchdog) |
|
The system property watchdog.no_exit is set, enabling override of default node termination behaviour on failed watchdog conditions. This can cause catastrophic results and should never be used. |
|
A forward timewarp was detected. |
|
A reverse timewarp was detected. |
|
Category: AbnormalExecution
Alarms raised as a result of an abnormal execution condition being detected
Alarm Type |
rhino.uncaught-exception |
|---|---|
Level |
WARNING |
Message |
Uncaught exception thrown by thread %s: %s |
Description |
An uncaught exception has been detected. |
Raised |
When an uncaught exception has been thrown. |
Cleared |
Never, must be cleared manually or Rhino restarted with the source of the uncaught exception corrected. |
Category: Activity Handler
Alarms raised by Rhino activity handler
Alarm Type |
rhino.ah.snapshot-age |
|---|---|
Level |
WARNING |
Message |
Oldest activity handler snapshot is older than %s, snapshot is %s (from %d), creating thread: %s |
Description |
The oldest activity handler snapshot is too old. |
Raised |
When the age of the oldest activity handler snapshot is greater than the threshold set by the rhino.ah.snapshot_age_warn system property (30s default). |
Cleared |
When the age of the oldest snapshot is less than or equal to the threshold. |
Category: Clustering
Alarms raised by Rhino cluster state changes
Alarm Type |
rhino.node-failure |
|---|---|
Level |
MAJOR |
Message |
Node %d has left the cluster |
Description |
A node left the cluster for some reason other than a management-initiated shutdown. |
Raised |
When the cluster state listener detects a node has left the cluster unexpectedly. |
Cleared |
When the failed node returns to the cluster. |
Category: Configuration Management
Alarms raised by the Rhino configuration manager
Alarm Type |
rhino.config.activation-failure |
|---|---|
Level |
MAJOR |
Message |
Error activating configuration from file %s. Configuration was replaced with defaults and old configuration file was moved to %s. |
Description |
An error occurred while trying to activate the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file. |
Raised |
When an exception occurs while activating a file-based configuration. |
Cleared |
Never, must be cleared manually. |
Alarm Type |
rhino.config.read-error |
|---|---|
Level |
MAJOR |
Message |
Error reading configuration from file %s. Configuration was replaced with defaults and old configuration file was moved to %s. |
Description |
An error occurred while trying to read the file-based configuration for the configuration type specified in the alarm instance. Rhino will use defaults from defaults.xml, move the broken configuration aside, and overwrite the config file. |
Raised |
When an exception occurs while reading a configuration file. |
Cleared |
Never, must be cleared manually. |
Alarm Type |
rhino.config.save-error |
|---|---|
Level |
MAJOR |
Message |
Error saving file based configuration: %s |
Description |
An error occurred while trying to write the file-based configuration for the configuration type specified in the alarm instance. |
Raised |
When an exception occurs while writing to a configuration file. |
Cleared |
Never, must be cleared manually. |
Category: Database
Alarms raised during database communications
Alarm Type |
rhino.database.connection-lost |
|---|---|
Level |
MAJOR |
Message |
Connection to %s database failed: %s |
Description |
Rhino requires a backing database for persistence of state for failure recovery purposes. If no connection to the database backend is available, state cannot be persisted. |
Raised |
When the connection to a database backend is lost. |
Cleared |
When the connection is restored. |
Alarm Type |
rhino.database.no-persistence-config |
|---|---|
Level |
CRITICAL |
Message |
Persistence resource config for %s has been removed |
Description |
A persistence resource configuration referenced in rhino-config.xml has been removed at runtime. |
Raised |
When an in-use persistence resource configuration is removed by a configuration update. |
Cleared |
When the persistence resource configuration is restored. |
Alarm Type |
rhino.database.no-persistence-instances |
|---|---|
Level |
CRITICAL |
Message |
Persistence resource config for %s has no active persistence instances |
Description |
A persistence resource configuration referenced in rhino-config.xml has no persistence instances configured, or no configured persistence instances could be instantiated. |
Raised |
When an in-use persistence resource configuration has no active persistence instances. |
Cleared |
When at least one active persistence instance exists for the persistence resource configuration. |
Alarm Type |
rhino.database.persistence-instance-instantiation-failure |
|---|---|
Level |
MAJOR |
Message |
Unable to instantiate persistence instance %s for database %s |
Description |
Rhino requires a backing database for persistence of state for failure recovery purposes. A persistent instance defines a connection to a database backend. If the persistent instance cannot be instantiated then that connection cannot be made and state cannot be persisted to that instance. |
Raised |
When a persistent instance configuration change occurs but instantiation of that persistent instance fails. |
Cleared |
When a correct configuration is installed. |
Alarm Type |
rhino.jdbc.persistence-instance-instantiation-failure |
|---|---|
Level |
MAJOR |
Message |
Unable to instantiate persistence instance %s for JDBC configuration with JNDI name %s |
Description |
A persistent instance defines the connection to the database backend. If the persistent instance cannot be instantiated then JDBC connections cannot be made. |
Raised |
When a persistent instance configuration change occurs but instantiation of that persistent instance fails. |
Cleared |
When a correct configuration is installed. |
Category: Event Router State
Alarms raised by event router state management
Alarm Type |
rhino.state.unlicensed-raentity |
|---|---|
Level |
MAJOR |
Message |
No valid license for resource adaptor entity "%s" found. The resource adaptor entity has not been activated. |
Description |
A licensing problem was detected during resource adaptor entity activation. |
Raised |
During Rhino startup if a resource adaptor entity is configured to be in the active state but there is no valid license for it. |
Cleared |
Never, must be cleared manually. |
Alarm Type |
rhino.state.unlicensed-service |
|---|---|
Level |
MAJOR |
Message |
No valid license for service "%s" found. The service has not been activated. |
Description |
A licensing problem was detected during service activation at startup. |
Raised |
During Rhino startup if an service is configured to be in the active state but there is no valid license for it. |
Cleared |
Never, must be cleared manually. |
Category: Licensing
Alarms raised by Rhino licensing
Alarm Type |
rhino.license.expired |
|---|---|
Level |
MAJOR |
Message |
License with serial "%s" has expired |
Description |
A license installed in Rhino has passed its expiry time. |
Raised |
When a license expires and there is no superseding license installed. |
Cleared |
When the license is removed or a superseding license is installed. |
Alarm Type |
rhino.license.over-licensed-capacity |
|---|---|
Level |
MAJOR |
Message |
Over licensed capacity for function "%s". |
Description |
The work done by a function exceeds licensed capacity. |
Raised |
When the amount of work processed by the named function exceeds the licensed capacity. |
Cleared |
When the amount of work processed by the function becomes less than or equal to the licensed capacity. |
Alarm Type |
rhino.license.over-limit |
|---|---|
Level |
MAJOR |
Message |
Rate limiter throttling active, throttled to %d events/second |
Description |
Rate limiter throttling is active. This throttling and hence this alarm only happens in SDK versions of Rhino, not production versions. |
Raised |
When there is more incoming work than allowed by the licensed limit so Rhino starts rejecting some. |
Cleared |
When the total input rate (both accepted and rejected work) drops below the licensed limit. |
Alarm Type |
rhino.license.partially-licensed-host |
|---|---|
Level |
MINOR |
Message |
Host "%s" is not fully licensed. Not all hardware addresses on this host match those licensed. Please request a new license for host "%s". |
Description |
The hardware addresses listed in a host-based license only partially match those on the host. |
Raised |
When a host-based license with invalid host addresses is installed. |
Cleared |
When the license is removed, or a superseding license is installed. |
Alarm Type |
rhino.license.pending-expiry |
|---|---|
Level |
MAJOR |
Message |
License with serial "%s" is due to expire on %s |
Description |
A license installed in Rhino is within seven days of its expiry time. |
Raised |
Seven days before a license will expire and there is no superseding license installed. |
Cleared |
When the license expires, the license is removed, or a superseding license is installed. |
Alarm Type |
rhino.license.unlicensed-function |
|---|---|
Level |
MAJOR |
Message |
There are no valid licenses installed for function "%s" and version "%s". |
Description |
A particular function is not licensed. |
Raised |
When a unit of an unlicensed function is requested. |
Cleared |
When a license is installed that licenses a particular function, and another unit is requested. |
Alarm Type |
rhino.license.unlicensed-host |
|---|---|
Level |
MINOR |
Message |
"%s" is not licensed. Hardware addresses on this host did not match those licensed, or hostname has changed. Please request a new license for host "%s". |
Description |
The hardware addresses listed in a host-based license do not match those on the host. |
Raised |
When a host-based license with invalid host addresses is installed. |
Cleared |
When the license is removed, or a superseding license is installed. |
Alarm Type |
rhino.license.unlicensed-rhino |
|---|---|
Level |
MAJOR |
Message |
Rhino platform is no longer licensed |
Description |
Rhino does not have a valid license installed. |
Raised |
When a license expires or is removed leaving Rhino in an unlicensed state. |
Cleared |
When an appropriate license is installed. |
Category: Limiting
Alarms raised by Rhino limiting
Alarm Type |
rhino.limiting.below-negative-capacity |
|---|---|
Level |
WARNING |
Message |
Token count in rate limiter "%s" capped at negative saturation point on node %d. Too much work has been forced. Alarm will clear once token count >= 0. |
Description |
A rate limiter is below negative capacity. |
Raised |
By a rate limiter when a very large number of units have been forcibly used and the internal token counter has reached the biggest possible negative number (-2,147,483,648). |
Cleared |
When the token count becomes greater than or equal to zero. |
Category: Logging
Alarms raised by Rhino logging
Alarm Type |
rhino.logging.appender-error |
|---|---|
Level |
MAJOR |
Message |
An error occurred logging to an appender: %s |
Description |
An appender has thrown an exception when attempting to pass log messages from a logger to it. |
Raised |
When an appender throws an AppenderLoggingException when a logger tries to log to it. |
Cleared |
When the problem with the given appender has been resolved and the logging configuration is updated. |
Category: M-lets Startup
Alarms raised by the M-let starter
Alarm Type |
rhino.mlet.loader-failure |
|---|---|
Level |
MAJOR |
Message |
Error registering MLetLoader MBean |
Description |
The M-Let starter component could not register itself with the platform MBean server. This normally indicates a serious JVM misconfiguration. |
Raised |
During Rhino startup if an error occurred registering the m-let loader component with the MBean server. |
Cleared |
Never, must be cleared manually or Rhino restarted. |
Alarm Type |
rhino.mlet.registration-failure |
|---|---|
Level |
MINOR |
Message |
Could not create or register MLet: %s |
Description |
The M-Let starter component could not register an MBean for a configured m-let. This normally indicates an error in the m-let configuration file. |
Raised |
During Rhino startup if an error occurred starting a m-let configured. |
Cleared |
Never, must be cleared manually or Rhino restarted with updated configuration. |
Category: REM Startup
Alarms raised by embedded REM starter
Alarm Type |
rhino.rem.insufficient-java-version |
|---|---|
Level |
MINOR |
Message |
This Java version (%s) is insufficient for starting the embedded Rhino Element Manager. REM requires Java 1.8. |
Description |
Rhino Element Manager requires Java 1.8, but Rhino was started using Java 1.7 |
Raised |
During Rhino startup if running on Java 1.7 and embedded REM is enabled. |
Cleared |
Never, must be cleared manually, Rhino restarted using Java 1.8, or embedded REM disabled. |
Alarm Type |
rhino.rem.missing |
|---|---|
Level |
MINOR |
Message |
Rhino Element Manager classes not found, embedded REM is disabled. |
Description |
This version of Rhino is supposed to contain an embedded instance of REM but it was not found, most likely due to a packaging error. |
Raised |
During Rhino startup if the classes could not be found to start the embedded REM. |
Cleared |
Never, must be cleared manually. |
Alarm Type |
rhino.rem.startup |
|---|---|
Level |
MINOR |
Message |
Could not start embedded Rhino Element Manager |
Description |
There was an unexpected problem while starting the embedded REM. This could be because of a port conflict or packaging problem. |
Raised |
During Rhino startup if an error occurred starting the embedded REM. |
Cleared |
Never, must be cleared manually or Rhino restarted with updated configuration. |
Category: Runtime Environment
Alarms related to the runtime environment
Alarm Type |
rhino.runtime.long-filenames-unsupported |
|---|---|
Level |
WARNING |
Message |
Filenames with a length of %s characters are unsupported on this filesystem. Unexpected deployment errors may occur as a result |
Description |
Filenames with the maximum length expected by Rhino are unsupported on this filesystem. Unexpected deployment errors may occur as a result |
Raised |
During Rhino startup if the long filename check fails. |
Cleared |
Never, must be cleared manually or Rhino restarted after being installed on a filesystem supporting long filenames. |
Alarm Type |
rhino.runtime.slee |
|---|---|
Level |
CRITICAL |
Message |
SLEE event-routing functions failed to start after node restart |
Description |
SLEE event-routing functions failed to start after node restart |
Raised |
During Rhino startup if SLEE event-routing functions fail to restart. |
Cleared |
Never, must be cleared manually or the node restarted. |
Alarm Type |
rhino.runtime.unsupported.javamajorversion |
|---|---|
Level |
WARNING |
Message |
This Java version (%s) is not supported for Rhino production instances. Supported versions are: %s |
Description |
This Java version is not a supported major version. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start. |
Raised |
During Rhino SDK startup if an unsupported JVM was detected. |
Cleared |
Never, must be cleared manually or Rhino restarted with a supported Java version. |
Alarm Type |
rhino.runtime.unsupported.javaupdateversion |
|---|---|
Level |
MINOR |
Message |
This Java version (%s) is older than the minimum recommended update (%s) |
Description |
This Java version is older than the minimum recommended update. A Rhino instance will start, but will always raise this alarm. |
Raised |
During Rhino startup if an old Java version was detected. |
Cleared |
Never, must be cleared manually or Rhino restarted with a supported Java version. |
Alarm Type |
rhino.runtime.unsupported.jvm |
|---|---|
Level |
WARNING |
Message |
This JVM (%s) is not supported for Rhino production instances. Supported JVMs are: %s |
Description |
This JVM is not a Sun/Oracle JVM. The Rhino SDK will raise this alarm but a Rhino Production instance will refuse to start. |
Raised |
During Rhino SDK startup if an unsupported JVM was detected. |
Cleared |
Never, must be cleared manually or Rhino restarted with a supported JVM. |
Category: SAS facility
Alarms raised by Rhino SAS Facility
Alarm Type |
rhino.sas.connection.lost |
|---|---|
Level |
MAJOR |
Message |
Connection to SAS server at %s:%d is down |
Description |
Attempting to reconect to SAS server |
Raised |
When SAS client loses connection to server |
Cleared |
On reconnect |
Alarm Type |
rhino.sas.queue.full |
|---|---|
Level |
WARNING |
Message |
SAS message queue is full |
Description |
SAS message queue is full. Some events have not been reported to SAS |
Raised |
When SAS facility outgoing message queue is full |
Cleared |
When the queue is not full for at least sas.queue_full_interval |
Category: SNMP
Alarms raised by Rhino SNMP
Alarm Type |
rhino.snmp.bind-failure |
|---|---|
Level |
MAJOR |
Message |
The SNMP agent could not be started on node %d: no addresses were successfully bound. |
Description |
The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If no ports could be bound, the SNMP agent cannot process any SNMP requests. |
Raised |
When the SNMP Agent attempts to start listening for requests, but no port in the configured range on any configured interface could be used. |
Cleared |
When the SNMP Agent is stopped. |
Alarm Type |
rhino.snmp.duplicate-counter-mapping |
|---|---|
Level |
WARNING |
Message |
Duplicate counter mappings in parameter set type %s |
Description |
Multiple counters in the parameter set type configuration map to the same index. The parameter set type mappings will remain inactive until the conflict is resolved. |
Raised |
When a in-use parameter set type has a configuration with duplicate counter mappings. |
Cleared |
When the conflict is resolved, either by changing the relevant counter mappings, or if the parameter set type is removed from use. |
Alarm Type |
rhino.snmp.duplicate-oid-mapping |
|---|---|
Level |
WARNING |
Message |
Duplicate parameter set type mapping configurations for OID %s |
Description |
Multiple parameter set type configurations for in-use parameter set types map to the same OID. All parameter set type mappings will remain inactive until the conflict is resolved. |
Raised |
When multiple in-use parameter set types have a configuration that map to the same OID. |
Cleared |
When the conflict is resolved, either by changing the OID mappings in the relevant parameter set type configurations, or if a parameter set type in conflict is removed from use. |
Alarm Type |
rhino.snmp.general-failure |
|---|---|
Level |
MINOR |
Message |
The SNMP agent encountered an error during startup: %s |
Description |
This is a catchall alarm for unexpected failures during agent startup. If an unexpected failure occurs, the state of the SNMP agent is unpredictable and requests may not be successfully processed. |
Raised |
When the SNMP Agent attempts to start listening for requests, but there is an unexpected failure not covered by other alarms. |
Cleared |
When the SNMP Agent is stopped. |
Alarm Type |
rhino.snmp.no-bind-addresses |
|---|---|
Level |
MAJOR |
Message |
The SNMP agent could not be started on node %d: no suitable bind addresses available. |
Description |
The SNMP agent listens for requests received on all network interfaces that match the requested SNMP configuration. If no suitable interfaces can be found that match the requested configuration, then the SNMP agent cannot process any SNMP requests. |
Raised |
When the SNMP Agent attempts to start listening for requests, but no suitable network interface addresses can be found to bind to. |
Cleared |
When the SNMP Agent is stopped. |
Alarm Type |
rhino.snmp.notification-address-failure |
|---|---|
Level |
MAJOR |
Message |
Failed to create notification target for address "%s". |
Description |
This alarm represents a failure to determine an address from the notification target configuration. This can occur if the notification hostname is not resolvable, or if the specified hostname is not parseable. |
Raised |
During SNMP agent start if a notification target address cannot be determined (e.g. due to a hostname resolution failing). |
Cleared |
When the SNMP Agent is stopped. |
Alarm Type |
rhino.snmp.partial-failure |
|---|---|
Level |
MINOR |
Message |
The SNMP agent failed to bind to the following addresses: %s |
Description |
The SNMP agent attempts to bind a UDP port on each configured SNMP interface to receive requests. If this succeeds on some (but not all) interfaces, the SNMP agent can only process requests received via the interfaces that succeeded. |
Raised |
When the SNMP Agent attempts to start listening for requests, and only some of the configured interfaces successfully bound a UDP port. |
Cleared |
When the SNMP Agent is stopped. |
Category: Scattercast Management
Alarms raised by Rhino scattercast management operations
Alarm Type |
rhino.scattercast.update-reboot-required |
|---|---|
Level |
CRITICAL |
Message |
Scattercast endpoints have been updated. A cluster reboot is required to apply the update. An automatic reboot has been triggered, Manual intervention required if the reboot fails. |
Description |
Reboot needed to make scattercast update active. |
Raised |
When scattercast endpoints are updated. |
Cleared |
On node reboot. |
Category: Service State
Alarms raised by service state management
Alarm Type |
rhino.state.service-activation |
|---|---|
Level |
MAJOR |
Message |
Service "%s" failed to reactivate successfully. |
Description |
The service threw an exception during service activation at startup. |
Raised |
During Rhino startup if a service is configured to be in the active state but throws an exception while handling the activation request. |
Cleared |
If the service is manually reactivated successfully, or uninstalled. |
Category: Threshold Rules
Alarms raised by the threshold alarm rule processor
Alarm Type |
rhino.threshold-rules.rule-failure |
|---|---|
Level |
WARNING |
Message |
Threshold rule %s trigger or reset condition failed to run |
Description |
A threshold rule trigger or reset rule failed. |
Raised |
When a threshold rule condition cannot be evaluated, for example it refers to a statistic that does not exist. |
Cleared |
When the threshold rule condition is corrected. |
Alarm Type |
rhino.threshold-rules.unknown-parameter-set |
|---|---|
Level |
WARNING |
Message |
Threshold rule %s refers to unknown statistics parameter set '%s' |
Description |
A threshold rule trigger or reset rule refers to an unknown statistics parameter set. |
Raised |
When a threshold rule condition cannot be evaluated because it refers to a statistics parameter set that does not exist. |
Cleared |
When the threshold rule condition is corrected. |
Category: Watchdog
Alarms raised by the watchdog
Alarm Type |
rhino.watchdog.forward-timewarp |
|---|---|
Level |
WARNING |
Message |
Forward timewarp of %sms detected at %s |
Description |
A forward timewarp was detected. |
Raised |
When the system clock is detected to have progressed by an amount exceeding the sum of the watchdog check interval and the maximum pause margin. |
Cleared |
Never, must be cleared manually. |
Alarm Type |
rhino.watchdog.no-exit |
|---|---|
Level |
CRITICAL |
Message |
System property watchdog.no_exit is set, watchdog will be terminated rather than killing the node if a failed watchdog condition occurs |
Description |
The system property watchdog.no_exit is set, enabling override of default node termination behaviour on failed watchdog conditions. This can cause catastrophic results and should never be used. |
Raised |
When the watchdog.no_exit system property is set. |
Cleared |
Never, must be cleared manually. |
Alarm Type |
rhino.watchdog.reverse-timewarp |
|---|---|
Level |
WARNING |
Message |
Reverse timewarp of %sms detected at %s |
Description |
A reverse timewarp was detected. |
Raised |
When the system clock is detected to have progressed by an amount less than the difference between the watchdog check interval and the reverse timewarp margin. |
Cleared |
Never, must be cleared manually. |
Usage
As well as an overview of usage, this section includes instructions for performing the following Rhino SLEE procedures, with explanations, examples and links to related javadocs:
| Procedure | rhino-console command | MBean → Operations |
|---|---|---|
dumpusagestats |
Usage → get<usage-parameter-name> |
|
setusagenotificationsenabled |
UsageNotificationManager → set<usage-parameter-name> NotificationsEnabled |
|
listusagenotificationsenabled |
UsageNotificationManager → get<usage-parameter-name> NotificationsEnabled |
|
createusageparameterset |
ServiceUsage → createUsageParameterSet ProfileTableUsage → createUsageParameterSet ResourceUsage → createUsageParameterSet |
|
listusageparametersets |
ServiceUsage → getUsageParameterSets ProfileTableUsage → getUsageParameterSets ResourceUsage → getUsageParameterSets |
|
removeusageparameterset |
ServiceUsage → removeUsageParameterSet ProfileTableUsage → removeUsageParameterSet ResourceUsage → removeUsageParameterSet |
About Usage
A usage parameter is a parameter that an object in the SLEE can update, to provide usage information.
There are two types:
-
Counter-type usage parameters have values that can be incremented or decremented.
-
Sample-type usage parameters accumulate sample data.
Accessing usage parameters
Administrators can access usage parameters through the SLEE’s management interface.
Management clients can access usage parameters through the usage parameters interface declared in an SBB, resource adaptor or profile specification. Usage parameters cannot be created through the management interface. Instead, a usage parameters interface must be declared in the SLEE component. For example, an SBB declares an sbb-usage-parameters-interface element in the SBB deployment descriptor (similar procedures apply for resource adaptors and profile specifications).
You can also use notifications to output usage parameters to management clients.
Creating named usage parameter sets
By default, the SLEE creates unnamed usage parameter sets for a notification source. You can also create named usage parameter sets, for example to hold multiple values of usage parameters for the same notification source.
Rhino usage extensions
To alleviate the limitations of the SLEE-defined usage mechanism, Rhino provides a usage extension mechanism that allows an SBB or resource adaptor to declare multiple usage parameters interfaces, and defines a Usage facility with which SBBs and resource adaptors can manage and access their own usage parameter sets.
Viewing Usage Parameters
To view the current value of a usage parameter, use the following rhino-console command or related MBean operation.
| |
Whereas the MBean operation below can only get individual usage parameter values, the console command outputs current values of all usage parameters for a specified notification source. |
Console command: dumpusagestats
Command |
dumpusagestats <type> <notif-source> [param-set-name] [reset]
Description
Dump the current values of the usage parameters for the specified notification
source. The usage parameter set name is optional and if not specified the
values for the unnamed (or root) parameter set are returned. If [reset] is
specified, the values of the usage parameters are reset after being obtained
|
|---|---|
Example |
$ ./rhino-console dumpusagestats sbb \
"service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]"
parameter-name counter-value sample-stats type
------------------- -------------- ------------- --------
callAttempts 0 counter
missingParameters 0 counter
offNetCalls 0 counter
onNetCalls 0 counter
unknownShortCode 0 counter
unknownSubscribers 0 counter
6 rows
|
MBean operation: get<usage-parameter-name>
MBean |
|
|---|---|
SLEE-defined |
Counter-type usage parameters
public long get<usage-parameter-name>(boolean reset)
throws ManagementException;
Sample-type usage parameters
public SampleStatistics get<usage-parameter-name>(boolean reset)
throws ManagementException;
|
Arguments |
This operation requires that you specify whether the values are to be reset after being read:
|
Return value |
Operations for counter-type usage parameters return the current value of the counter. Operations for sample-type usage parameters return a |
Usage Notifications
You can enable or disable usage notifications, and list which usage notifications are enabled:
Enabling and Disabling Usage Notifications
To enable or disable usage notifications, use the following rhino-console command or related MBean operation.
| |
The notifications-enabled flag
To enable notifications to output usage parameters to management clients, set the usage |
Console command: setusagenotificationsenabled
Command |
setusagenotificationsenabled <type> <notif-source> [upi-type] <param-name>
<flag>
Description
Set the usage notifications-enabled flag for specified usage notification
source's usage parameter. The usage parameters interface type is optional and
if not specified the root usage parameters interface type is used
|
|---|---|
Example |
$ ./rhino-console setusagenotificationsenabled sbb \
"service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]" \
callAttempts true
Usage notifications for usage parameter callAttempts for
SbbNotification[service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]]
have been enabled
|
MBean operation: set<usage-parameter-name>NotificationsEnabled
MBean |
|
|---|---|
SLEE-defined |
public void set<usage-parameter-name>NotificationsEnabled(boolean enabled)
throws ManagementException;
|
Arguments |
|
Notes |
Enabling usage notification
Usage notifications are enabled or disabled on a per-usage-parameter basis for each notification source. That means that if usage notifications are enabled for a particular usage parameter, if that usage parameter is updated in any usage parameter set belonging to the notification source, a usage notification will be generated by the SLEE. |
Viewing Usage Notification Status
To list usage parameter status, use the following rhino-console command or related MBean operation.
| |
To see which usage parameters management clients are receiving through notifications, you can list usage parameter status. |
Console command: listusagenotificationsenabled
Command |
listusagenotificationsenabled <type> <notif-source> [upi-type]
Description
List the usage notification manager flags for the specified notification source.
The usage parameters interface type is optional and if not specified the flags
for the root usage parameters interface type are returned
|
|---|---|
Example |
$ ./rhino-console listusagenotificationsenabled sbb \
"service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]"
parameter-name notifications-enabled
------------------- ----------------------
callAttempts true
missingParameters false
offNetCalls false
onNetCalls false
unknownShortCode false
unknownSubscribers false
6 rows
|
MBean operation: get<usage-parameter-name>NotificationsEnabled
MBean |
|
|---|---|
SLEE-defined |
public boolean get<usage-parameter-name>NotificationsEnabled()
throws ManagementException;
|
Arguments |
|
Named Usage Parameter Sets
By default, the SLEE creates unnamed usage parameter sets for a notification source. You can also create named usage parameter sets, for example to hold multiple values of usage parameters for the same notification source.
Rhino includes facilities for creating, listing and removing named usage parameter sets for services, resource adaptor entities and profile tables.
This section includes the following procedures:
| |
Usage parameter sets for internal subsystems (not listed using console command)
The SLEE specification also includes usage parameter sets for "internal subsystems". You can list these, but not create or remove them, since they are part of the SLEE implementation. However, Rhino uses its own statistics API to collect statistics from internal subsystems — so if you try to list usage parameter set names for an internal subsystem using |
Creating Usage Parameter Sets
To create a named usage parameter set for services, resource adaptor entities or profile tables, use the following rhino-console or related MBean operations.
Services
Console command: createusageparameterset
Command |
createusageparameterset <type> <notif-source> <param-set-name>
Description
Create a new usage parameter set with the specified name for the specified
notification source
|
|---|---|
Example |
$ ./rhino-console createusageparameterset sbb \
"service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]" \
firstLook
created usage parameter set firstLook for
SbbNotification[service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]]
|
MBean operation: createUsageParameterSet
MBean |
|
|---|---|
SLEE-defined |
public void createUsageParameterSet(SbbID id, String paramSetName)
throws NullPointerException, UnrecognizedSbbException,
InvalidArgumentException, UsageParameterSetNameAlreadyExistsException,
ManagementException;
|
Arguments |
|
Resource adaptor entities
Console command: createusageparameterset
Command |
createusageparameterset <type> <notif-source> <param-set-name>
Description
Create a new usage parameter set with the specified name for the specified
notification source
|
|---|---|
Example |
$ ./rhino-console createusageparameterset resourceadaptorentity \
"entity=cdr" \
cdr-usage
created usage parameter set cdr-usage for RAEntityNotification[entity=cdr]
|
MBean operation: createUsageParameterSet
MBean |
|
|---|---|
SLEE-defined |
public void createUsageParameterSet(String paramSetName)
throws NullPointerException, InvalidArgumentException,
UsageParameterSetNameAlreadyExistsException,
ManagementException;
|
Arguments |
|
Profile tables
Console command: createusageparameterset
Command |
createusageparameterset <type> <notif-source> <param-set-name>
Description
Create a new usage parameter set with the specified name for the specified
notification source
|
|---|---|
Example |
$ ./rhino-console createusageparameterset profiletable \
"table=PostpaidChargingPrefixTable" \
ppprefix-usage
created usage parameter set ppprefix-usage for ProfileTableNotification[table=PostpaidChargingPrefixTable]
|
MBean operation: createUsageParameterSet
MBean |
|
|---|---|
SLEE-defined |
public void createUsageParameterSet(String paramSetName)
throws NullPointerException, InvalidArgumentException,
UsageParameterSetNameAlreadyExistsException,
ManagementException;
|
Arguments |
|
Listing Usage Parameter Sets
To list named usage parameter sets for services, resource adaptor entities or profile tables, use the following rhino-console or related MBean operations.
Services
Console command: listusageparametersets
Command |
listusageparametersets <type> <notif-source>
Description
List the usage parameter sets for the specified notification source. The
unnamed (or root) parameter set is not included in this list
|
|---|---|
Example |
$ ./rhino-console listusageparametersets sbb \
"service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]"
firstLook
secondLook
|
MBean operation: getUsageParameterSets
MBean{cth} |
|
|---|---|
SLEE-defined |
public String[] getUsageParameterSets(SbbID id)
throws NullPointerException, UnrecognizedSbbException,
InvalidArgumentException, ManagementException
|
Arguments |
|
Resource adaptor entities
Console command: listusageparametersets
Command |
listusageparametersets <type> <notif-source>
Description
List the usage parameter sets for the specified notification source. The
unnamed (or root) parameter set is not included in this list
|
|---|---|
Example |
$ ./rhino-console listusageparametersets resourceadaptorentity \
"entity=cdr"
cdr-usage
|
MBean operation: getUsageParameterSets
MBean{cth} |
|
|---|---|
SLEE-defined |
public String[] getUsageParameterSets()
throws ManagementException
|
Profile tables
Console command: listusageparametersets
Command |
listusageparametersets <type> <notif-source>
Description
List the usage parameter sets for the specified notification source. The
unnamed (or root) parameter set is not included in this list
|
|---|---|
Example |
$ ./rhino-console listusageparametersets profiletable \
"table=PostpaidChargingPrefixTable"
ppprefix-usage
|
MBean operation: getUsageParameterSets
MBean{cth} |
|
|---|---|
SLEE-defined |
public String[] getUsageParameterSets()
throws ManagementException
|
Removing Usage Parameter Sets
To removed a named usage parameter set for services, resource adaptor entities or profile tables, use the following rhino-console or related MBean operations.
Services
Console command: removeusageparameterset
Command |
removeusageparameterset <type> <notif-source> <param-set-name>
Description
Remove the existing usage parameter set with the specified name from the
specified notification source
|
|---|---|
Example |
$ ./rhino-console removeusageparameterset sbb \
"service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]" \
secondLook
removed usage parameter set secondLook for
SbbNotification[service=ServiceID[name=VPN Service,vendor=OpenCloud,version=0.2],sbb=SbbID[name=VPN SBB,vendor=OpenCloud,version=0.2]]
|
MBean operation: removeUsageParameterSet
MBean |
|
|---|---|
SLEE-defined |
public void removeUsageParameterSet(SbbID id, String paramSetName)
throws NullPointerException, UnrecognizedSbbException,
InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
ManagementException;
|
Arguments |
|
Resource adaptor entities
Console command: removeusageparameterset
Command |
removeusageparameterset <type> <notif-source> <param-set-name>
Description
Remove the existing usage parameter set with the specified name from the
specified notification source
|
|---|---|
Example |
$ ./rhino-console removeusageparameterset resourceadaptorentity \
"entity=cdr" \
cdr-usage
removed usage parameter set cdr-usage for RAEntityNotification[entity=cdr]
|
MBean operation: removeUsageParameterSet
MBean |
|
|---|---|
SLEE-defined |
public void removeUsageParameterSet(String paramSetName)
throws NullPointerException,
InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
ManagementException;
|
Argument |
|
Profile tables
Console command: removeusageparameterset
Command |
removeusageparameterset <type> <notif-source> <param-set-name>
Description
Remove the existing usage parameter set with the specified name from the
specified notification source
|
|---|---|
Example |
$ ./rhino-console removeusageparameterset profiletable \
"table=PostpaidChargingPrefixTable" \
ppprefix-usage
removed usage parameter set ppprefix-usage for ProfileTableNotification[table=PostpaidChargingPrefixTable]
|
MBean operation: removeUsageParameterSet
MBean |
|
|---|---|
SLEE-defined |
public void removeUsageParameterSet(String paramSetName)
throws NullPointerException,
InvalidArgumentException, UnrecognizedUsageParameterSetNameException,
ManagementException;
|
Argument |
|
User Transactions
As well as an overview of user transactions, this section includes instructions for performing the following Rhino SLEE procedures with explanations, examples and links to related javadocs:
| Procedure | rhino-console command(s) | MBean(s) → Operation |
|---|---|---|
|
User Transaction Management →
|
|
|
User Transaction Management →
|
|
|
User Transaction Management →
|
About User Transactions
Using the User Transaction Management MBean, a client can demarcate transaction boundaries for a subset of profile-management operations, by:
-
starting a user transaction
-
performing some profile-management operations, across a number of different profiles (in the context of that transaction)
-
then committing the transaction — resulting in an atomic update of profile state.
Binding user transactions with authenticated subjects
The SLEE binds user transactions to the java.security.auth.Subject associated with the invoking thread. For all user-transaction management, the thread invoking the management operation must therefore be associated with an authenticated subject. The command console interface handles this task as part of the client-login process. (Other user-provided m-lets installed in the Rhino SLEE will need to take care of this requirement in their own way.)
Executing Profile Provisioning operations in a user transaction
The following operations on the Profile Provisioning MBean support execution in a user transaction: createProfile, createProfiles, removeProfile, getDefaultProfile, getProfile, and importProfiles
Furthermore, accessing a Profile MBean while a user transaction is active:
-
enlists that MBean into that user transaction
-
changes that MBean to the read/write state
-
puts any changes to the profile in context of the user transaction.
| |
Committing or rolling back profiles enlisted in user transactions
You cannot invoke the |
Starting User Transactions
To start a user transaction, use the following rhino-console command or related MBean operation.
Console command: startusertransaction
Command |
startusertransaction
Description
Start a client-demarcated transaction. Note that only a limited set of Rhino
management operations support user transactions
|
|---|---|
Example |
$ ./rhino-console startusertransaction |
MBean operation: startUserTransaction
MBean |
|
|---|---|
Rhino extension |
void startUserTransaction()
throws com.opencloud.rhino.management.usertx.NoAuthenticatedSubjectException,
NotSupportedException, ManagementException;
|
Committing User Transactions
To commit a user transaction, use the following rhino-console command or related MBean operation.
Console command: commitusertransaction
Command |
commitusertransaction
Description
Commit a client-demarcated transaction
|
|---|---|
Example |
$ ./rhino-console commitusertransaction |
MBean operation: commitUserTransaction
MBean |
|
|---|---|
Rhino extension |
void commitUserTransaction()
throws com.opencloud.rhino.management.usertx.NoAuthenticatedSubjectException,
InvalidStateException, ProfileVerificationException,
HeuristicMixedException, HeuristicRollbackException,
RollbackException, ManagementException;
|
Rolling Back User Transactions
To rollback a user transaction, use the following rhino-console command or related MBean operation.
Console command: rollbackusertransaction
Command |
rollbackusertransaction
Description
Roll back a client-demarcated transaction
|
|---|---|
Example |
$ ./rhino-console rollbackusertransaction |
MBean operation: rollbackUserTransaction
MBean |
|
|---|---|
Rhino extension |
void rollbackUserTransaction()
throws com.opencloud.rhino.management.usertx.NoAuthenticatedSubjectException,
InvalidStateException, ManagementException;
|
Auditing Management Operations
Rhino logs all management operations to two log files in the working directory of each Rhino node (work/logs by default):
-
management.csv, a plain text CSV file -
encrypted.management.csv, a second, encrypted copy of the logs.
| |
You can use the encrypted version to detect tampering with the plain text copy — decode with the decrypt-management-log script, in the client/bin directory. |
| |
The management audit logs roll over once they reach 100MB, with an unlimited number of backup files. This logging configuration is currently hard-coded. |
| |
The format of management audit log can be chosen via system property rhino.audit.log_format. See more detail in system property. |
What’s in the log file?
Rhino management operations logs include the following fields:
| Field | Description |
|---|---|
date |
A timestamp in the form |
uniqueID |
An identifier used to correlate a set of log lines for a single management operation. All of the log lines from the same operation will have the same |
opcode |
Uniquely identifies the type of operation. |
user |
The name of the user invoking the management operation, or |
roles |
Any roles associated with the user. |
access |
Identifies whether the operation results in a state change of some sort. May be |
client address |
The IP address of the client invoking the management operation. |
namespace |
The namespace where the management operation invoked. Empty if it is the default namespace. |
MBean name |
|
operation type |
The general type of operation. |
operation name |
The name of the invoked method or |
arguments |
The contents of all arguments passed to the management operation. Byte array arguments display converted to a length and a hash. |
duration |
How long (in milliseconds) the operation took. |
result |
|
failure reason |
A text string indicating why an operation failed. (Only present for failed results.) 2 |
| |
All management operations except for AUTHENTICATION type operations come in pairs with the first entry indicating the start of an operation, and the second entry indicating success or failure, as well as how long the operation took. Only the result lines make use of the duration, result, and failure reason fields. |
| |
For a list of all operations currently recognised by the auditing subsystem, run the getopcodexml command from the command-line console. It will return the complete XML representation of all known management operations. |
Operation types
The operation type field may contain one of the following values:
| Type | Result type | Description |
|---|---|---|
AUTHENTICATION |
n/a |
A successful or failed authentication attempt. |
INVOKE |
INVOKE (RESULT) |
An MBean invoke operation. |
GET |
GET (RESULT) |
An MBean attribute get operation. |
SET |
SET (RESULT) |
An MBean attribute set operation. |
GET-ATTRIBUTES |
GET-ATTRIBUTES (RESULT) |
An MBean bulk-attributes |
SET-ATTRIBUTES |
SET-ATTRIBUTES (RESULT) |
An MBean bulk-attributes |
Managing the audit level
The auditing subsystem provides two console commands to manage what gets logged to the management audit log:
getmanagementauditlevel
Description
Returns the current level of management operation auditing.
setmanagementauditlevel <none \| writes \| all>
Description
Sets the current level of management operation auditing.
| |
Writes is useful, for example, to avoid receiving excessive messages from an automated management client that continually polls Rhino state using JMX. |
| |
Rhino always logs changes to the audit level (irrespective of the current level). |
Example 1: Resource adaptor deployment and activation
The following example shows management logs from deploying a resource adaptor, creating a resource adaptor entity for it, and activating that resource adaptor entity.
| |
The log shows the resource adaptor activated twice in a row, the second operation failing (because the RA was already activated) — see the result and failure fields. |
| date | uniqueID | opcode | user | roles | access | client address | MBean name | operation type | operation name | arguments | duration | result | failure reason |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2010-06-08 14:22:06.850 |
101:176452077447:22 |
|
admin |
|
|
192.168.0.7 |
|
AUTHENTICATION |
|
|
|
ok |
|
2010-06-08 14:22:35.622 |
101:176452077447:29 |
19000 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=Deployment |
INVOKE |
install |
[file:/home/alex/simple/simple-ra-ha.jar, [byte array, length=65164, md5sum=96322071e6128333bdee3364a224b48c] |
|
|
|
2010-06-08 14:22:38.961 |
101:176452077447:29 |
19000 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=Deployment |
INVOKE (RESULT) |
install |
[file:/home/alex/simple/simple-ra-ha.jar, [byte array, length=65164, md5sum=96322071e6128333bdee3364a224b48c] ] |
3339ms |
ok |
|
2010-06-08 14:22:53.356 |
101:176452077447:36 |
22014 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE |
getConfigurationProperties |
[ResourceAdaptorID [name=Simple,vendor=OpenCloud,version=1.0] ] |
|
|
|
2010-06-08 14:22:53.359 |
101:176452077447:36 |
22014 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE (RESULT) |
getConfigurationProperties |
[ResourceAdaptorID [name=Simple,vendor=OpenCloud,version=1.0] ] |
3ms |
ok |
|
2010-06-08 14:22:53.369 |
101:176452077447:39 |
22016 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE |
createResourceAdaptorEntity |
[ResourceAdaptorID
[name=Simple,vendor=OpenCloud,version=1.0],
simplera,
[(Host:java.lang.String=localhost),
(Port:java.lang.Integer=14477),
(slee-vendor:
com.opencloud.rhino_replicate_activities:
java.lang.String=none)
]
]
|
|
|
|
2010-06-08 14:22:53.536 |
101:176452077447:39 |
22016 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE (RESULT) |
createResourceAdaptorEntity |
[ResourceAdaptorID
[name=Simple,vendor=OpenCloud,version=1.0],
simplera,
[(Host:java.lang.String=localhost),
(Port:java.lang.Integer=14477),
(slee-vendor:
com.opencloud.rhino_replicate_activities:
java.lang.String=none)
]
]
|
167ms |
ok |
|
2010-06-08 14:23:11.987 |
101:176452077447:47 |
22004 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE |
activateResourceAdaptorEntity |
[simplera,[101]] |
|
|
|
2010-06-08 14:23:12.029 |
101:176452077447:47 |
22004 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE (RESULT) |
activateResourceAdaptorEntity |
[simplera,[101]] |
42ms |
ok |
|
2010-06-08 14:23:30.802 |
101:176452077447:52 |
22004 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE |
activateResourceAdaptorEntity |
[simplera,[101]] |
|
|
|
2010-06-08 14:23:30.820 |
101:176452077447:52 |
22004 |
admin |
admin |
write |
192.168.0.7 |
javax.slee.management: name=ResourceManagement |
INVOKE (RESULT) |
activateResourceAdaptorEntity |
[simplera,[101]] |
18ms |
failed |
simplera not in INACTIVE state on node(s)[101] |
Example 2: Bulk GET operation on Licensing MBean
The example below shows a GET-ATTRIBUTES operation called on the Licensing MBean. It includes queries on four separate attributes: LicenseSummary, LicensedFunctions, LicensedVersions, and Licenses. The result of the bulk-attribute query operation are in the last line.
| |
Note that the uniqueID field is the same for all lines representing the GET-ATTRIBUTES operation. |
| date | uniqueID | opcode | user | roles | access | client address | MBean name | operation type | operation name | arguments | duration | result | failure reason |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2010-05-28 14:07:11.223 |
101:175500674962:292 |
|
admin |
admin |
|
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET-ATTRIBUTES |
|
|
|
|
|
2010-05-28 14:07:11.223 |
101:175500674962:292 |
2008 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET |
LicenseSummary |
|
|
|
|
2010-05-28 14:07:11.223 |
101:175500674962:292 |
2005 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET |
LicensedFunctions |
|
|
|
|
2010-05-28 14:07:11.223 |
101:175500674962:292 |
2006 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET |
LicensedVersions |
|
|
|
|
2010-05-28 14:07:11.223 |
101:175500674962:292 |
2004 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET |
Licenses |
|
|
|
|
2010-05-28 14:07:11.226 |
101:175500674962:292 |
2008 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET (RESULT) |
LicenseSummary |
|
3ms |
ok |
|
2010-05-28 14:07:11.226 |
101:175500674962:292 |
2005 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET (RESULT) |
LicensedFunctions |
|
3ms |
ok |
|
2010-05-28 14:07:11.226 |
101:175500674962:292 |
2006 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET (RESULT) |
LicensedVersions |
|
3ms |
ok |
|
2010-05-28 14:07:11.226 |
101:175500674962:292 |
2004 |
admin |
admin |
read |
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
GET (RESULT) |
Licenses |
|
3ms |
ok |
|
2010-05-28 14:07:11.226 |
101:175500674962:292 |
|
admin |
admin |
|
192.168.0.7 |
com.opencloud.rhino: type=Licensing |
|
|
3ms |
ok |
|
| |
The durations listed for the individual GET (RESULT) lines correspond to the duration of the entire GET-ATTRIBUTES operation and not the individual GET components. In the example above, the entire GET-ATTRIBUTES operation took 3ms. |
Linked and Shadowed Components
There can be times when creating component dependencies in a deployable unit where a specific dependency target may not be known. For example, the particular version of a dependent library may be variable. At other times, some already installed component may need to be replaced with another, possibly a new version with a bug fix, and reinstalling all dependent components with updated deployment descriptors is undesirable.
Bindings can help with this problem, to some degree, however bindings can introduce other issues. Bindings always operate on virtual copies of the original components, and keeping track of copied components can be difficult if many binding operations are made.
Rhino provides a solution to these problems with support for linked and shadowed components.
Linked components
A linked component is a virtual component that provides an alias for some other component. Incoming references to the linked component are redirected to the link target. A linked component’s component type, for example SBB, profile specification, library, and so on, is the same as the component that it is linked to; and, like all other components, has a unique identity represented by the (name, vendor, version) tuple.
A linked component identifier can be used anywhere where a regular component identifier is required.
Shadowed components
A shadowed component is an existing component that has been "shadowed" or replaced by a link to another component of the same type. Incoming references to the shadowed component are redirected to the link target rather than using the original component.
Conceptually, linked and shadowed component perform the same function: to redirect an incoming reference to another component. The difference is that a linked component is a new virtual component with a unique identity, whereas a shadow replaces a component that is already installed in the SLEE.
| |
Components supporting links and shadows
The following types of components currently support links and shadows:
|
Managing linked components
Below are overviews of the procedures to create, remove, and view the metadata for linked components.
Creating a linked component
You create linked components using the createLinkedComponent management operation. For example, using rhino-console:
[Rhino@localhost:2199 (#0)] createlinkedcomponent sbb name=MySBB,vendor=OpenCloud,version=1.0 MySBBLink OpenCloud 1.0 Component SbbID[name=MySBBLink,vendor=OpenCloud,version=1.0] linked to SbbID[name=MySBB,vendor=OpenCloud,version=1.0]
The first two arguments identify the component type and identifier of the link target. The target component must already exist in the SLEE. The last three arguments define the name, vendor, and version strings for the new linked component identifier.
Removing a linked component
You remove a linked component using the removeLinkedComponent management operation. For example, using rhino-console:
[Rhino@localhost:2199 (#0)] removelinkedcomponent sbb name=MySBBLink,vendor=OpenCloud,version=1.0 Linked component SbbID[name=MySBBLink,vendor=OpenCloud,version=1.0] removed
A linked component cannot be removed if:
-
another component with an install level of
VERIFIEDorDEPLOYEDreferences it; -
another linked component specifies this linked component as its target; or
-
another component is shadowed by this linked component.
Viewing linked component metadata
The getDescriptor management operation returns a SLEE ComponentDescriptor object for any component that exists in the SLEE. A ComponentDescriptor object for a linked component has the following properties:
-
its deployable unit is the same as the deployable unit of the link target
-
its source component jar is the same as the source component jar of the link target
-
it contains a vendor-specific data object of type
LinkedComponentDescriptorExtensions.
Linked component descriptor extensions
The LinkedComponentDescriptorExtensions class defines Rhino-specific component metadata extensions for linked components. Here’s what it looks like:
package com.opencloud.rhino.management.deployment;
import java.io.Serializable;
import java.util.Date;
import javax.slee.ComponentID;
public class LinkedComponentDescriptorExtensions implements Serializable {
public LinkedComponentDescriptorExtensions(...) { ... }
public ComponentID getLinkTarget() { ... }
public Date getLinkDate() { ... }
public InstallLevel getInstallLevel() { ... }
public ComponentID[] getIncomingLinks() { ... }
public ComponentID[] getShadowing() { ... }
...
}-
The
getLinkTargetmethod returns the component identifier of the link target. -
The
getLinkDatemethod returns aDateobject that specifies the date and time the linked component was created. -
The
getInstallLevelmethod returns the current install level of the linked component. The install level of a linked component is immaterial, and changing it has no effect on the linked component itself; however, since an install level is a property of all components installed in Rhino, a linked component must have one by definition. -
The
getIncomingLinksmethod returns the component identifiers of any other linked components that have this linked component as a target. -
The
getShadowingmethod returns the component identifiers of any other component that has been shadowed by this linked component.
Managing component shadows
Shadowing or unshadowing a component effectively changes the definition of the component; therefore a component can only undergo these transitions if it has an install level of INSTALLED. This ensures that any components that depend on the affected component also have an install level of INSTALLED, and thus will need (re)verifying against the updated component before further use. Rhino will allow a component with an install level of VERIFIED to be shadowed or unshadowed, but will automatically transition the component (and any upstream dependencies) to the INSTALLED install level first. A component with an install level of DEPLOYED must be manually undeployed before a shadow can be created or removed.
Below are overviews of the procedures to shadow, unshadow, and view the shadow metadata for a component.
Shadowing a component
You shadow one component with another using the shadowComponent management operation. For example, using rhino-console:
[Rhino@localhost:2199 (#0)] shadowcomponent sbb name=MySBB,vendor=OpenCloud,version=1.0 name=MySBB,vendor=OpenCloud,version=1.0.2 Component SbbID[name=MySBB,vendor=OpenCloud,version=1.0] shadowed by SbbID[name=MySBB,vendor=OpenCloud,version=1.0.2]
The first two arguments identify the component type and identifier of the component to be shadowed. The last argument identifies the component that this component will be shadowed by. Both the shadowed and shadowing components must already exist in the SLEE.
| |
Link cycles won’t work
Using shadows, you might try to create a link cycle. For example, if component |
Unshadowing a component
You unshadow a component using the unshadowComponent management operation. For example, using rhino-console:
[Rhino@localhost:2199 (#0)] unshadow sbb name=MySBB,vendor=OpenCloud,version=1.0 Shadow removed from component SbbID[name=MySBB,vendor=OpenCloud,version=1.0]
Viewing shadowed component metadata
The getDescriptor management operation returns a SLEE ComponentDescriptor object for any component that exists in the SLEE. The component descriptor for a shadowed component continues to describe the original unshadowed component, but contains a vendor-specific data object of type com.opencloud.rhino.management.deployment.ComponentDescriptorExtensions that includes the following information relevant to shadowing:
-
The
getShadowedBymethod returns the component identifier of the component that shadows this component. This target component will be used in place of the described component. -
The
getShadowDatemethod returns aDateobject that specifies the date and time the shadow was established. -
The
getShadowingmethod returns the component identifiers of any other component that has in turn been shadowed by this shadowed component.
Linked and shadowed component resolution
In most cases where a component identifier is specified, Rhino will follow a chain of links and shadows to resolve the component identifier to a concrete target component. Typical cases where this occurs are as follows:
-
wherever a component references another component in its deployment descriptor or in a binding descriptor
-
if a service component is activated or deactivated
-
when a profile table is created from a profile specification
(though Rhino will report that the profile table was created from the specified component rather than the resolved target) -
when a resource adaptor entity is created from a resource adaptor
(though again Rhino will report that the resource adaptor entity was created from the specified component rather than the resolved target) -
when interrogating or updating a component’s security policy.
Specific cases where a management operation applies directly to a linked or shadowed component rather than its resolved target are as follows:
-
when requesting a component’s metadata descriptor
-
when copying a shadowed component
(The shadowed component itself is copied, rather than the shadowing component. Linked components are still resolved though when determining the actual component to copy; so an attempt to copy a linked component will result in a copy of the resolved target component being copied.)
Additional notes
-
Creating a link to a service component automatically adds a clone of the resolved target service’s statistics with the linked component identifier to the stats manager. For example, if service component
Ais linked to service componentB, then the stats forBcan be accessed from the stats manager using either component identifierAorB. The same result will be obtained in each case. Listing the available stats parameter sets will include bothAandB. -
The activation state reported for a linked or shadowed service component is the state of the service component that the link or shadow resolves to. Activating or deactivating the linked or shadowed component has the same effect as activating or deactivating the resolved component.
-
If a resource adaptor entity generates events that may be consumed by a given service component, and a link to that service component is created, then the resource adaptor entity will also be notified about a change to the lifecycle state for the linked component when the state of the target service component changes.
-
A resource adaptor entity may fire an event targeted at a linked service component, and Rhino will deliver the event to the resolved target service component. If an SBB in the service invokes a resource adaptor interface API method while handling that event, then the value returned by the
ResourceAdaptorContext.getInvokingService()method will equal the target service component identifier specified by the resource adaptor entity when the event was fired; that is, it will be the linked component identifier. However if an SBB in the service invokes a resource adaptor interface API method while handling an event that had no specific service target, then the value returned by the samegetInvokingService()method will be the service component identifier of the resolved service that is actually processing the event.
Component Activation Priorities
Rhino versions 2.4 and above allow configuration of the activation order of SLEE components. This ordering is controlled separately for activating and deactivating components.
Introduction to priorities
In Rhino 2.3.1 and older, RAs and services started in effectively random order. The startup order was based on the indexing hash order in the system.
The priority system added in Rhino 2.4 allows operator control of this order.
Priorities are values between -128 and 127. If a component (service or resource adaptor entity), X, has a numerically higher priority value than another component, Y, then X will be started before Y. Components with the same priority may be started in an arbitrary order, or may be started concurrently. The same rule applies for component stopping priorities; i.e., highest priority stops first.
If you have assigned startup priorities to; RAs A=100, B=20, C=10; and service S=15, they will start up in the following order:
-
activate RA entity A
-
activate RA entity B
-
activate service S
-
activate RA entity C
Note that a service can still potentially receive an event from an RA before it receives a ServiceStartedEvent on the ServiceActivity. That’s a completely different problem to activation ordering, and given the asynchronous nature of event delivery not something we can readily do anything about. A service that depends on the ServiceStartedEvent may be able to use the service activation callbacks in Rhino 2.4 instead. You may notice that services of the same priority level as RA entities start before the RA entities and stop after them. This ordering is not part of the priority system definition. It is possible that they will be started concurrently in the future, so always use different priorities if you need a specific order.
Managing priorities
Below are overviews of the procedures to manage service priorities, manage RA entity priorities, and list priorities.
Managing service priorities
You get priorities for services using the getStartingPriority and getStoppingPriority management operations.
You set priorities for services using the setStartingPriority and setStoppingPriority management operations.
For example, using rhino-console:
[Rhino@localhost:2199 (#0)] setservicestartingpriority name=MyService,vendor=OpenCloud,version=1.0 10 Service ServiceID[name=MyService,vendor=OpenCloud,version=1.0] activation priority set to 10
Managing RA entity priorities
You get priorities for RA entities using the getStartingPriority and getStoppingPriority management operations.
You set priorities for RA entities using the setStartingPriority and setStoppingPriority management operations.
For example, using rhino-console:
[Rhino@localhost:2199 (#0)] setraentitystartingpriority sipra 80 Resource adaptor entity sipra activation priority set to 80
Listing priorities
You list priorities for services using the getStartingPriorities and getStoppingPriorities management operations.
You list priorities for RA entities using the getStartingPriorities and getStoppingPriorities management operations.
You get a full combined listing using the liststartingpriorities and liststoppingpriorities commands in rhino-console.
For example:
[Rhino@localhost:2199 (#0)] liststartingpriorities
Starting priorities of installed services and resource adaptor entities:
80 : resource adaptor entity sipra
20 : ServiceID[name=SIP Presence Service,vendor=OpenCloud,version=1.1]
10 : ServiceID[name=SIP Proxy Service,vendor=OpenCloud,version=1.8]
0 : ServiceID[name=SIP Notification Service,vendor=OpenCloud,version=1.1]
ServiceID[name=SIP Profile Location Service,vendor=OpenCloud,version=1.0]
ServiceID[name=SIP Publish Service,vendor=OpenCloud,version=1.0]
-5 : ServiceID[name=SIP Registrar Service,vendor=OpenCloud,version=1.8]
Note: Components with the same priority may be started in any order
Rhino Configuration
This section covers procedures for configuring Rhino upon installation, and as needed (for example to tune performance).
This includes configuring:
| |
See also Management Tools. |
Logging
Rhino supports logging to multiple different locations and offers granular configuration of loggers and output. The most common configuration used is of log levels and output appenders. Log appenders are used to direct logging output for display and storage, typically to files or the console terminal. Rhino provides management interfaces and commands for configuring the logging framework. It also provides access to the logging framework for deployed components as extensions to the SLEE specification.
This section includes the following topics:
| |
JMX clients can access logging management operations via the Logging Management MBean. |
About Logging
The Rhino SLEE uses the Apache Log4j 2 logging framework to provide logging facilities for SLEE components and deployed services.
| |
The Logging Management MBean
Rhino SLEE allows changes to logging configuration at runtime. This is useful for capturing log information to diagnose a problem, without having to restart the SLEE. You configure logging using the |
Asynchronous Logging
The Log4j 2 logging architecture provides a new approach to asynchronous logging. It uses asynchronous loggers, which submit log events to a work queue for later handling by the appropriate appenders.
More details can be found in the Log4j 2 async loggers documentation
Rhino offers support for mixed synchronous and asynchronous logging through logger configuration commands. Correctly configuring asynchronous logging has some complexity, discussed in how to Configure a Logger.
Mapped Diagnostic Context
Rhino 2.6 introduces access to the Mapped Diagnostic Context (MDC) as a tool to tag and correlate log messages throughout an activity’s life cycle. This tagging can be combined with the new filters to allow very fine grained control of logging and tracing.
A simple SIP example of useful context would be including the P-charging-vector header. As this uniquely identifies a single call, it becomes trivial to identify all log messages related to handling an individual call. Identification (or filtering) remains simple even under load, with multiple calls handled in parallel.
The Logging Context Facility discusses MDC in greater detail.
Logger names
Subsystems within the Rhino SLEE send log messages to specific loggers. For example, the rhino.facility.alarm logger periodically receives messages about which alarms are currently active within the Rhino SLEE.
Examples of logger names include:
-
root— the root logger, from which all loggers are derived (can be used to change the log level for all loggers at once) -
rhino— main Rhino logger -
rhino.management— for log messages related to Rhino management systems -
trace.<namespace>.<deployable_type>.<notification_source>.<tracer name>— loggers used by deployed SLEE components that use tracers. By default these keys appear abbreviated in console and file logs. Details of tracer abbreviation can be found at Tracer pattern converter.
Log levels
Log levels can be assigned to individual loggers to filter how much information the SLEE produces:
| Log level | Information sent |
|---|---|
OFF |
No messages sent to logs (not recommended). |
FATAL |
Error messages for unrecoverable errors only (not recommended). |
ERROR |
Error messages (not recommended). |
WARN |
Warning messages. |
INFO |
Informational messages (especially during node startup or deployment of new resource adaptors or services). The default. |
DEBUG |
Detailed log messages. Used for debugging by OpenCloud Rhino SLEE developers. |
TRACE |
Finest level. Not currently used. |
ALL |
All of the above. |
Each log level will log all messages for that log level and above. For example, if a logger is set to the INFO level (the default), all of the log messages logged at the INFO, WARN, ERROR, and FATAL levels will be logged as well.
If a logger is not assigned a log level, it inherits its parent’s. For example, if the rhino.management logger has not been assigned a log level, it will have the same effective log level as the rhino logger.
The root logger is a special logger which is considered the parent of all other loggers. By default, the root logger is configured with the INFO log level. In this way, all other logger will output log messages at the INFO log level or above unless explicitly configured otherwise.
| |
Use INFO
A lot of useful or crucial information is output at the INFO log level. Because of this, setting log levels to WARN, ERROR or FATAL is not recommended. |
Log appenders
System administrators can use the console to create some simple log appenders. Full appender creation is available through the Rhino Element Manager (REM). These append log messages to destinations such as the console, a log file, socket, or Unix syslog daemon. At runtime, when Rhino logs a message (as permitted by the log level of the associated logger), Rhino sends the message to the log appender for writing. Types of log appenders include:
-
file appenders — which append messages to files (and may be rolling file appenders)
-
console appenders — which send messages to the Rhino console
-
socket appenders — Append to a network socket. Either raw, or syslog formatted.
-
custom appenders — which can do a wide variety of things. Common "custom" apenders are used to append to various kinds of database.
Rolling file appenders
Typically, to manage disk usage, administrators are interested in sending log messages to a set of rolling files. They do this by setting up rolling file appenders which:
-
create new log files if the current one gets too large
-
rename old log files as numbered backups
-
delete old logs when a certain number of them have been archived.
Log files roll over when they exceed the configured size i.e. size is checked after logging each message, if the log file is larger than the maximum the next message will be written to a new file. Since Rhino 2.6.0 only the SDK rolls over log files on node restart. Production nodes use a size-based policy only.
You can configure the size and number of rolled-over log files and the rollover behaviour. Options include size-based, time-based and on node-restart. All configurations described for Log4j 2 are valid: https://logging.apache.org/log4j/2.x/manual/appenders.html#RollingFileAppender
An example logging config containing a complex rollover strategy that increments file numbers, retaining up to 4 historical files younger than 30 days:
<appender name="RhinoLog" plugin-name="RollingFile">
<layout name="RhinoLogLayout" plugin-name="PatternLayout">
<property name="pattern" value="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%logger] <%threadName> %mdc : %msg%n%throwable"/>
<property name="header" value="${rhinoVersionHeader}"/>
</layout>
<property name="filePattern" value="${logDir}/rhino.log.%i"/>
<property name="fileName" value="${logDir}/rhino.log"/>
<component name="RhinoLogPolicy" plugin-name="SizeBasedTriggeringPolicy">
<property name="size" value="100MB"/>
</component>
<component name="RhinoLogStrategy" plugin-name="NotifyingRolloverStrategy">
<property name="min" value="1"/>
<property name="max" value="2147483647"/>
<component name="deleteAction" plugin-name="Delete">
<property name="basePath" value="${logDir}"/>
<property name="maxDepth" value="1"/>
<component name="fileName" plugin-name="IfFileName">
<property name="glob" value="rhino.log.*"/>
</component>
<component name="any" plugin-name="IfAny">
<component name="lastmodified" plugin-name="IfLastModified">
<property name="age" value="30d"/>
</component>
<component name="fileCount" plugin-name="IfAccumulatedFileCount">
<property name="exceeds" value="4"/>
</component>
</component>
</component>
</component>
</appender>
Default appenders
By default, the Rhino SLEE comes configured with the following appenders active:
| Appender | Where it sends messages | Logger name | Type of appender |
|---|---|---|---|
RhinoLog |
the Rhino logs directory (work/log/rhino.log) |
root |
a rolling file appender |
STDERR |
the Rhino console where a node is running (in a standard error stream) |
root |
a console appender |
ConfigLog |
work/log/config.log |
rhino.config |
a rolling file appender |
| |
New appenders won’t receive messages until associated with at least one logger
By default, a newly created log appender is not associated with any loggers, so will not receive any log messages. |
Appender additivity
If a logger has its additivity flag set to true, all of the output of its log statements goes to all of its appenders and ancestors. If a specific ancestor has its additivity flag set to false, then the output goes to all appenders and ancestors up to and including that specific ancestor — but not to appenders in any of that ancestor’s ancestors. (By default, logger additivity flags are set to true.}
| |
See Apache’s Log4j 2 Architecture page for details on additivity. |
Filters
Filters can be applied to both loggers and appenders to restrict the set of log messages that are reported by a logger or through an appender. They provide a more flexible limiting approach than log level alone. Configuring filters can be performed using the Rhino Element Manager or by modifying an export of the logging configuration. A list of the filters available by default and their configuration properties can be found in the Log4j 2 filter documentation
An example filter configuration setting for limiting log levels to Warning in namespace volte and Info in all other namespaces is shown below:
<component plugin-name="DynamicThresholdFilter">
<property name="defaultThreshold" value="Finer"/>
<property name="key" value="namespace"/>
<component plugin-name="KeyValuePair">
<property name="key" value="volte"/>
<property name="value" value="Warning"/>
</component>
</component>
If three trace messages are emitted by the service
tracer.warning("TransparentDataCache(MMTEL-Services) (RepositoryDataAccessKey{REPOSITORY_DATA, userId=tel:+34600000002, userIdType=IMPU, serviceIndication=MMTEL-Services}): [DoUDR] failed to send request")
tracer.finer("Cache gave immediate response. Latency: 1 ms")
tracer.finest("Removing service indication: MMTEL-Services from the session state list.Initial items: [MMTEL-Services]")
With the service deployed in namespace volte only the Warning will be logged:
2017-11-14 13:35:38.123+1300 Warning [trace.sh_cache_ra.sh-cache-ra] <jr-4> {ns=volte, txID=101:210487189646097} TransparentDataCache(MMTEL-Services) (RepositoryDataAccessKey{REPOSITORY_DATA, userId=tel:+34600000002, userIdType=IMPU, serviceIndication=MMTEL-Services}): [DoUDR] failed to send request
otherwise both the Finer and Warning messages will be logged:
2017-11-14 13:35:38.123+1300 Warning [trace.sh_cache_ra.sh-cache-ra] <jr-4> {ns=mmtel, txID=101:210487189646097} TransparentDataCache(MMTEL-Services) (RepositoryDataAccessKey{REPOSITORY_DATA, userId=tel:+34600000002, userIdType=IMPU, serviceIndication=MMTEL-Services}): [DoUDR] failed to send request
2017-11-14 13:35:38.137+1300 Finer [trace.volte_sentinel_sip.2_7_0_copy_1.volte_sentinel_sip.sentinel.sbb] <jr-4> {ns=mmtel, txID=101:210487189646097} Cache gave immediate response. Latency: 1 ms
The default threshold of Finer will cause the Finest message to never be logged.
Logging plugins
Rhino contains several logging plugins to extend the functionality of Log4j 2 to aid SLEE management and provide additional context to logs.
-
NotifyingRolloverStrategy -
NotifyingDirectWriteRolloverStrategy -
LogNotificationAppender -
PolledMemoryAppender
NotifyingRolloverStrategy
An extended variant of the DefaultRolloverStrategy providing an API for components to receive notification of log file rollover. RolloverNotificationListener`s can be registered to receive a callback whenever a log file is rolled over. This strategy should be used instead of the Log4j 2 `DefaultRolloverStrategy so Rhino can send notifications to monitoring systems.
NotifyingDirectWriteRolloverStrategy
An extended variant of the DirectWriteRolloverStrategy providing an API for components to receive notification of log file rollover. RolloverNotificationListener`s can be registered to receive a callback whenever a log file is rolled over. This strategy should be used instead of the Log4j 2 `DirectWriteRolloverStrategy so Rhino can send notifications to monitoring systems.
LogNotificationAppender
A log appender for delivering log messages to a listener inside the application. This is used to send log messages to JMX monitoring clients and as SNMP notifications. It is only necessary to use the LogNotificationAppender if using SNMP to receive log messages.
TraceNotificationAppender
A log appender for delivering log messages to a listener inside the application that extracts tracer messages to send as `TraceNotification`s. This is used to send tracer messages to JMX monitoring clients such as REM. It is necessary to use the TraceNotificationAppender if using JMX to receive tracer messages. Without an instance of this appender in the log configuration REM instances connecting to this Rhino instance will not be able to receive or display tracer messages.
PolledMemoryAppender
A log appender that stores messages in an internal buffer that the REM can poll for live log watching. This implementation is only of use when log output is infrequent enough for human monitoring and has a minor performance cost. It will be removed in a future release of Rhino. We recommend that log files or an external log server be used as the primary log output.
| |
See Logging plugins for instructions on enabling additional appender types. |
Other plugins
The Log4j 2 project (https://logging.apache.org/log4j/2.x) provides a number of plugins for extending the functionality of Log4j 2. These plugins provide appenders for sending logs to a number of log servers, files and databases, layouts for configuring the format of log messages, and filters to restrict the logging of messages. System integrators or operators can create plugins to add further functionality or support for other log handling systems.
Rhino log configuration properties
Rhino log configuration variables include a rhino namespace containing options useful for providing additional context in log files. These are:
-
${rhino:node-id}: The node ID of the Rhino node that wrote the log message parameterised with this variable -
${rhino:version}: The version of Rhino running at the time the log message parameterised with this variable was written
Tracer objects
SLEE 1.1 provides tracer objects for logging messages from deployed components.
Rhino logs all messages sent to a Tracer under the trace.<notification source>.<tracer name> logger.
In an extension of the SLEE specification Rhino allows configuration of tracer levels at coarser grain than the component tracer. This extended functionality is accessed through the Rhino logging configuration. For example setloglevel trace Finest will set the default tracer level to Finest. All tracers not explicitly set will log at levels from Finest up. To support this SLEE extension root tracers for individual notification sources inherit their levels from the trace logger. It is also permitted to unset the root tracer level for a given notification source using setTracerLevel. Unsetting the root tracer level reverts to using the inherited level.
A further extension of the SLEE specification allows for full use of logging management commands against Tracers. A SLEE 1.1 Tracer may have appenders and filters added to further customise tracing output, both to JMX notifications, and logging destinations. Any supported appender may be used, so logging destinations are not restricted to file only.
Tracer log levels
Log levels for trace messages are logged at the level they are emitted.
| |
See also About SLEE 1.1 Tracers. |
| |
SLEE 1.0-based application components can still use the trace facility (defined in the JAIN SLEE 1.0 specification) for logging, however the trace facility has been deprecated for JAIN SLEE 1.1. |
About SLEE 1.1 Tracers
Tracer Interface
In SLEE 1.1, there are more components that may need tracing support. In addition to SBBs, trace messages may also be generated by profile abstract classes and resource adaptors, and potentially any other SLEE subsystem.
All of these components may use the SLEE 1.1 javax.slee.facilities.Tracer interface. The Tracer interface will be familiar to users of other logging APIs. It provides methods for generating traces at different trace levels. Details of the tracing methods available are in the javax.slee.facilities.Tracer javadoc.
Obtaining a Tracer
Components obtain Tracers by calling the getTracer() method on the particular component’s context object. Rhino 2.6 provides 'com.opencloud.rhino.facilities.ExtendedTracer' instances when acquiring a Tracer, If only Rhino 2.6 support is required, the Tracer aquired from a context may be safely cast to ExtendedTracer
Older Rhino versions provide a com.opencloud.rhino.facilities.Tracer. The older Rhino implementation does not offer the extended logging API that the ExtendedTracer does.
For backwards compatibility Rhino 2.6 API library contains a com.opencloud.rhino.facilities.trace.TracerAccessor which handles safely acquiring a Rhino 2.6 ExtendedTracer.
| Component | Tracer access method |
|---|---|
SBB |
ExtendedTracer trace = (ExtendedTracer)SbbContext.getTracer(String) |
Profiles |
ProfileContext.getTracer(String) |
Resource Adaptors |
ResourceAdaptorContext.getTracer(String) or TracerAccessor.getExtendedTracer(ResourceAdaptorContext, String) |
The string parameter in the above methods is the tracer name. This is a hierarchical name, following Java naming conventions, where the different levels in the hierarchy are delimited by a dot. For example, a tracer named "com.foo" is the parent of "com.foo.bar". Components may create any number of tracers, with different names, for different purposes. Tracers inherit the trace level of their parent in the hierarchy. The tracer named "" (empty string) is the top-level or root tracer. The hierarchical naming is a convention used in most logging APIs, and allows an administrator to easily enable or disable tracing for an entire hierarchy of tracers.
import javax.slee.Sbb;
import javax.slee.SbbContext;
import javax.slee.facilities.Tracer;
public abstract class MySbb implements Sbb {
private Tracer rootTracer;
private ExtendedTracer fooTracer;
private SbbContext context;
public void setSbbContext(SbbContext context) {
this.context = context;
this.rootTracer = context.getTracer("");
this.fooTracer = (ExtendedTracer)context.getTracer("foo");
}
...
// Generate an INFO trace on the root tracer
rootTracer.info("An event has occurred");
...
// Generate a WARNING trace on the fooTracer
fooTracer.warning("Could not combobulate {}", "discombobulator");Notification Sources
SLEE 1.1 introduces the javax.slee.management.NotificationSource interface, which the SLEE automatically adds to notifications generated by SLEE tracers. As this is automatically asssociated with the Tracer object, there is no need to manually specify source as in SLEE 1.0. This solves the problem of identifying which SBB in which service generated a trace message. The NotificationSource explicity identifies the component that generated the trace, so a management client can easily see which service and SBB the trace came from, allowing filtering by service or SBB.
Tracer Extensions
To alleviate some limitations of the SLEE 1.1 Tracer system, Rhino offers an extended Tracer API. This extended API offers a larger set of tracing methods, to support tracing without string concatenation to build trace messages. Tracer extensions contains details of the Tracer API extensions, and com.opencloud.rhino.facilities.ExtendedTracer javadoc is available.
Rhino 2.6 Tracer Extensions
In Rhino 2.6, the Tracer subsystem has been substantially reworked. As a result, Tracers are now first class loggers. This means that a Tracer may be manipulated by logging management commands as if it were a logger, with the exception that it will only accept Tracer levels.
Tracers now have very long logger names, as they must be unique to support making Tracers first class loggers. In log files these very long names are inconvenient, as they will frequently cause log entries to run over multiple lines on screen. In order to alleviate this issue, we have included a default tracer name abbreviation system.
Tracer pattern converter
The Tracer abbreviator used by default is based heavily on the logger pattern converter supplied with Log4j 2. See Log4j 2 Pattern Layout for documentation.
The tracer pattern converter shipped with Rhino allows for optionally completely removing a logger/tracer name component. In contrast, the logger pattern converter will always leave a . literal to show where elements have been abbreviated. The tracer pattern converter also does not implement Log4j 2 integer precision abbreviation, only pattern abbreviation.
| Tracer name | Pattern | Output |
|---|---|---|
trace.default.resourceadaptorentity.simplera.example |
%logger{*.0.0.*}
|
trace…simplera.example |
trace.default.resourceadaptorentity.simplera.example |
%tracer{*.0.0.*}
|
trace.simplera.example |
Tracer abbreviation behaviour can be managed through REM or by editing an exported logging.xml.
The default tracer pattern converter shipped with Rhino is shown below
<component plugin-name="MarkerPatternSelector" >
<property name="defaultPattern" value="%d{yyyy-MM-dd HH:mm:ss.SSSZ} %-7level [%logger] <%threadName> %mdc %msg{nolookups}%n%throwable"/>
<component plugin-name="PatternMatch">
<property name="key" value="Trace"/>
<property name="pattern" value="%d{yyyy-MM-dd HH:mm:ss.SSSZ} ${plainLevel} [%tracer{*.0.0.*}] <%threadName> %mdc %msg{nolookups}%n%throwable"/>
</component>
<component plugin-name="PatternMatch">
<property name="key" value="SbbTrace"/>
<property name="pattern" value="%d{yyyy-MM-dd HH:mm:ss.SSSZ} ${plainLevel} [%tracer{*.0.0.*.0.*.*.0.0.*}] <%threadName> %mdc %msg{nolookups}%n%throwable"/>
</component>
</component>Note that there are three patterns in use here.
| Marker | Pattern | Usecase |
|---|---|---|
None (defaultPattern) |
%logger |
Used for non-tracer log messages |
SbbTrace |
%tracer{*.0.0.*.0.*.*.0.0.*}
|
Used for Tracer messages logged from an SBB. |
Trace |
%tracer{*.0.0.*}
|
Used for Tracer messages logged from anything other than an SBB |
Different patterns are required for SBB and non-SBB Tracers, due to the more complex notification source identity of SBB notification sources. An SBB notification source includes both SBB id and Service ID. All other notification sources have no equivalent of Service ID.
Creating a File Appender
To create a file appender, use the following rhino-console command or related MBean operation. Since Rhino 2.6 there are many varieties of file appenders supported.
There are two major classes of file appenders discussed below. Non rolling file appenders do not rollover logfiles ever. Rolling file appenders are able to roll over logfiles, and must be configured with automatic rollover rules.
| |
FileName arguments are paths to files, not just filenames. To create a logfile in the configured logging directory (Default is ${NODE_HOME}/work/log) one can use the property ${logDir} as the leading element of the filename |
Non rolling file appenders
These appenders cannot be rolled over with the rolloverlogfiles console command.
Console command: createfileappender
Command |
createfileappender <appenderName> <fileName> [-append <true|false>] [-bufferedIO
<true|false>] [-bufferSize size] [-createOnDemand <true|false>] [-immediateFlush
<true|false>] [-locking <true|false>] [-ignoreExceptions <true|false>] [-pattern
<pattern>]
Description
The FileAppender is an appender that writes to the File named in the <fileName>
parameter.
Required Arguments
appenderName The name of the Appender.
fileName The name of the file to write to. If the file, or any of its parent
directories, do not exist, they will be created.
Options
-append When true, records will be appended to the end of the file. When set to
false, the file will be cleared before new records are written. The default is
true.
-bufferedIO When true, records will be written to a buffer and the data will be
written to disk when the buffer is full or, if immediateFlush is set, when the
record is written. File locking cannot be used with bufferedIO. The default is
true.
-bufferSize The buffer size. The default is 8192 bytes.
-createOnDemand When true, the appender creates the file on-demand. The default
is false.
-immediateFlush When true, each write will be followed by a flush. This will
guarantee the data is written to disk but could impact performance. The default
is true.
-locking When true, I/O operations will occur only while the file lock is held.
The default is false.
-ignoreExceptions When true, exceptions encountered while appending events will
be internally logged and then ignored. The default is true.
-pattern The pattern to use for logging output.
|
|---|---|
Example |
To create a logfile in the configured logging directory
$ ./rhino-console createfileappender myappender "${logDir}/myappender.log"
Done.
To create a logfile in an absolute path
$ ./rhino-console createfileappender myappender /var/logs/rhino/myappender.log Done. |
Console command: createrandomaccessfileappender
Command |
createrandomaccessfileappender <appenderName> <fileName> [-append <true|false>]
[-immediateFlush <true|false>] [-bufferSize size] [-ignoreExceptions
<true|false>] [-pattern <pattern>]
Description
The RandomAccessFileAppender is an appender that writes to the File named in the
<fileName> parameter. It is similar to the standard FileAppender except it is
always buffered.
Required Arguments
appenderName The name of the Appender.
fileName The name of the file to write to. If the file, or any of its parent
directories, do not exist, they will be created.
Options
-append When true, records will be appended to the end of the file. When set to
false, the file will be cleared before new records are written. The default is
true.
-immediateFlush When true, each write will be followed by a flush. This will
guarantee the data is written to disk but could impact performance. The default
is true.
-bufferSize The buffer size. The default is 8192 bytes.
-ignoreExceptions When true, exceptions encountered while appending events will
be internally logged and then ignored. The default is true.
-pattern The pattern to use for logging output.
|
|---|---|
Example |
$ ./rhino-console createrandomaccessfileappender myappender "${logDir}/myappender.log"
Done.
|
Console command: creatememorymappedfileappender
Command |
creatememorymappedfileappender <appenderName> <fileName> [-append <true|false>]
[-immediateFlush <true|false>] [-regionLength length] [-ignoreExceptions
<true|false>] [-pattern <pattern>]
Description
The MemoryMappedFileAppender maps a part of the specified file into memory and
writes log events to this memory, relying on the operating system's virtual
memory manager to synchronize the changes to the storage device
Required Arguments
appenderName The name of the Appender.
fileName The name of the file to write to. If the file, or any of its parent
directories, do not exist, they will be created.
Options
-append When true, records will be appended to the end of the file. When set to
false, the file will be cleared before new records are written. The default is
true.
-immediateFlush When true, each write will be followed by a flush. This will
guarantee the data is written to disk but could impact performance. The default
is true.
-regionLength The length of the mapped region, defaults to 32 MB.
-ignoreExceptions When true, exceptions encountered while appending events will
be internally logged and then ignored. The default is true.
-pattern The pattern to use for logging output.
|
|---|---|
Example |
$ ./rhino-console creatememorymappedfileappender myappender "${logDir}/myappender.log"
Done.
|