Administrator toolkit
The administrator toolkit consists of a set of MBeans (managed beans), scripts, and other tools that help you administer Decision Server Insights solutions and servers.
Insight Server has a range of operational metrics. The most important metrics are related to heap usage, garbage collection, inbound queue depth (which indicates whether a cluster is keeping up with the volume of incoming events), outbound queue depth, and how long each agent is taking to process different types of events. These basic metrics give you good visibility into the health of your servers and can help you to detect and react to issues before they become critical.
Decision Server Insights provides scripts to automate deployment and administrative tasks over JMX and REST. The following files are modified when you manage solutions and administer your servers:
- <InstallDir>runtime/wlp/usr/servers/server_name/server.xml
The server configuration file is updated by running scripts and other management tools.
- <InstallDir>runtime/wlp/usr/servers/server_name/bootstrap.properties
and jvm.options
These files are used for various server properties.
- <InstallDir>runtime/wlp/usr/servers/server_name/grids/objectgrid.xml
and objectGridDeployment.xml
These files are used to configure WebSphere® eXtreme Scale.
The <InstallDir>/runtime/ia/etc directory contains property files that are used by the scripts in ia/bin. If you need different connection properties, do not edit the <InstallDir>/runtime/ia/etc/connection.properties file. Create a properties file that includes your connection properties and use the --propertiesFile command-line argument to reference it. The <InstallDir>/runtime/ia/etc directory is replaced when you run an update of Insight Server.
- Do's and don'ts
- MBean APIs for general administration
- TestDriver API for server and solution problem determination
- REST APIs for entity and global aggregate administration
- Scripts for general administration
- SmartCloud Analytics for monitoring and analyzing solutions
- Insight Monitor
- Log and trace files for checking server status
Do's and don'ts
Goal |
The do's | The don'ts |
---|---|---|
Modify solution and system behavior |
Use the solutionManager and propertyManager scripts to adjust default values and add new properties. For more information, see Properties. You set a system property on a single server of a server topology; system property updates are pushed to all servers. |
|
Manage system memory |
Monitor key metrics to ensure that your runtime servers and solutions are working well. Monitor the Java™ virtual machine (JVM) heap usage remotely by using the MBeans supplied by the JVM. You can also use JConsole to get information on performance and resource consumption both on a local or remote computer. Connect to a JVM and then browse the JMX MBeans to see the wide variety of metrics available. If the heap usage exceeds some percentage of available heap, alarms can be generated. |
Expect the system to automatically page entities in/out of memory. |
Update entities |
When you use the REST API to update an entity, agents are not notified that the entity is updated. If this lack of notification is an issue in your solution, submit an event to update your entities rather than using the REST API. If the events are submitted by the gateway API, the events are routed to the correct partition and processed immediately. If the events are submitted through HTTP or JMS, the processing passes through the solution connectivity, which can be scaled independently of agent processing. |
|
Protect access to entities |
Configure grid security in a production server that is running in an unprotected network. |
Do not keep test users and authorization roles in the configuration of your production server; at a minimum encode or encrypt the passwords. |
Deploy solutions |
In production, use the solutionManager script to deploy a solution. In a production topology, use bash scripts over Secure Shell (SSH) to clean up the servers, start/stop the servers, deploy, and retrieve logs. Pass a script and have it run ephemerally. For example:
Or:
|
In production, do not deploy a solution from Insight Designer. |
Monitor your operations |
Aggregate your logs from all your servers. In a development environment, use Insight Monitor, SmartCloud Analytics, or install IBM® Log Analytics Server. Create operational alerts and build dashboards to improve operational efficiency. Some metrics are best viewed on a dashboard. IBM Log Analysis Server has a built-in index, search, and dashboard capability. IBM Tivoli® Monitoring can also be used to set up alert conditions and alarms. |
MBean APIs for general administration
You can manage Insight Server, deployed solutions, and outbound endpoints by using JMX MBean (managed bean) APIs. The Liberty profile provides a list of MBeans and corresponding management interfaces that help you manipulate and monitor the server.
The management interface is a Java interface that you use to construct a proxy object for the MXBean, as described in the Liberty documentation. Documentation of the management interface for each MBean API is provided in the Java API reference.
MBean | When to use | Supported tasks |
---|---|---|
AgentStatsMXBean |
Use AgentStatsMXBean to obtain statistics about Java agents. For more information, see AgentStatsMXBean and Monitoring agent activity. |
|
DataLoadManagerMXBean |
Use DataLoadManagerMXBean to recover and restore configuration information and data that is persisted to a backup database. For more information, see DataLoadManagerMXBean |
|
GlobalPropertiesMXBean |
Use GlobalPropertiesMXBean to manage global properties. For more information, see GlobalPropertiesMXBean. |
|
InboundEndpointMonitorMXBean |
Use InboundEndpointMonitorMXBean to retrieve information about solution connectivity that can help you assess the performance of your inbound endpoints. For more information, see InboundEndpointMonitorMXBeanr |
|
JobManagerMXBean |
Use JobManagerMXBean to manage jobs. For more information, see JobManagerMXBean and Managing global aggregates. |
|
OutboundBufferManagerMXBean |
Use OutboundBufferManagerMXBean to manage outbound connectivity (outbound endpoints), and outbound events that are pending delivery, for a solution. For more information, see OutboundBufferManagerMXBean and Managing outbound endpoints with the MBean API. |
|
ServerAdminMXBean |
Use ServerAdminMXBean to manage the servers in your topology. For more information, see ServerAdminMXBean. |
|
SolutionsMXBean |
Use SolutionsMXBean to manage solutions and solution properties. For more information, see SolutionsMXBean and Managing deployed solutions by using MBean APIs. |
|
TestDriver API for server and solution problem determination
API | When to use | Supported tasks |
---|---|---|
Test driver |
Use test driver to set up and automate complex solution testing, and to detect server problems. For more information, see TestDriver and Receiving and storing debug events and Loading entities and submitting events by using TestDriver. |
|
REST APIs for entity and global aggregate administration
API | When to use | Supported tasks |
---|---|---|
Entity resources | ||
DELETE |
Use DELETE to remove a business entity from a solution on an Insight Server. For more information, see Deleting entities. |
|
DELETE state |
Use the DELETE state REST
method to reset the state of a solution in a production environment. For more information, see the REST API. |
Reset the solution state, including the rule agent history, cached engines, time triggers, pending events and global aggregates. |
GET |
Use GET to retrieve information about business entities in a solution. For more information, see Listing entities. |
|
POST |
Use POST to update business entities in a solution. For example, use a POST request to change a flight number or customer account number. For more information, see Creating entities. |
|
PUT |
Use PUT to deliver business entities to a deployed solution, at the location indicated by the URI. You use the PUT request for delivering new business entities, and for delivering business entities that are updated with new fields or deleted fields. For more information, see Updating entity data. |
|
Global aggregate resources | ||
GET |
Use GET to retrieve information about global aggregates in a solution. For more information, see the REST API. |
|
Shared aggregate resources | ||
GET |
Use GET to retrieve information about shared aggregates in a solution. For more information, see the REST requests. |
|
Scripts for general administration
Script | When to use | Supported tasks |
---|---|---|
connectivityManager |
Use connectivityManager to manage the connectivity assets in a solution. For more information, see Managing solution connectivity by running connectivityManager. |
|
dataLoadManager |
Use dataLoadManager to recover and restore configuration information and data that is persisted to a backup database. For more information, see Restoring data after a system shutdown by running dataLoadManager. |
|
dataMigrationManager |
You must migrate the data in your persistence database before it can be used in V8.8.0. |
|
jobManager |
Use jobManager to manage and obtain information about analytics jobs. For more information, see Managing global aggregates. |
|
outboundBufferManager |
Use outboundBufferManager to manage the outbound connectivity (outbound endpoints), and the outbound events that are pending delivery, for a solution. For more information, see Managing outbound endpoints by running outboundBufferManager. |
|
pmiManager |
Use pmiManager to generate statistics about a running server. For more information, see ../../com.ibm.odm.itoa.ref/topics/ref_itoa_pmimanager_script.html |
Generate statistics that include the number of times an agent or event type is invoked, average time an agent or event time is active, and the number of times an agent or event type is invoked per second. |
propertyManager |
Use propertyManager to manage server properties. For more information, see Modifying server behavior by setting properties. |
|
serverManager |
Use serverManager to pause and shutdown server processes. For more information, see Creating, starting, and stopping servers. |
|
solutionManager |
Use solutionManager to manage deployed solutions. For more information, see Managing deployed solutions by running solutionManager. |
|
SmartCloud Analytics for monitoring and analyzing solutions
Console | When to use | Supported tasks |
---|---|---|
SmartCloud Analytics Console |
Use IBM SmartCloud® Analytics console to search Insight Server for logged events, to generate analytics reports, and to monitor and analyze your solutions. For more information, see SmartCloud Analytics. |
|
Insight Monitor
Console | When to use | Supported tasks |
---|---|---|
adminCenter-1.0 on a catalog server |
Use Insight Monitor to view event rates and available memory for all of the runtime servers. |
Display metrics on each runtime server:
|
Log and trace files for checking server status
File | When to use | Supported tasks |
---|---|---|
console.log |
Use console.log to view standard process output and error messages from the runtime environment, for run and debug actions. Messages are redirected to the server_name/logs/console.log file when you start the server. For more information, see |
View a confirmation message that a solution
is deployed and ready to use, for example:
View other standard process output and error messages. |
messages.log |
Use messsages.log to view operational messages and information that is generated by the system. For more information, see |
|
trace.log |
Use trace.log to gather and view debug information. For more information, see |
Gather and view debug information that is obtained by basic, enhanced, or advanced tracing. |