View Source

{toc}

h1. Managing OWLIM through the JMX interface

OWLIM offers a number of management and control functions using [Java Management Extensions (JMX)|http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html]. OWLIM uses this interface to provide information about its internal state and behaviour, including trend information, as well as operations for intervening in certain database activities.

After initialisation, OWLIM will register a number of JMX MBeans for each repository each providing a different set of information and functions for specific features. The JMX endpoint is configured using special system properties when starting the Java virtual machine (JVM) in which OWLIM is running. For example, the following command line parameters will set the JMX server endpoint to listen on port 8089, not require authentication and will not use a secure socket layer:

{noformat}
-Dcom.sun.management.jmxremote.port=8089
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
{noformat}

If using OWLIM with Tomcat, then these parameters must be passed to Tomcat's JVM by setting either the {{JAVA_OPTS}} or {{CATALINA_OPTS}} environment variable, e.g.

{noformat}
set JAVA_OPTS="-Dcom.sun.management.jmxremote.port=8089
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false"
{noformat}

For some Linux distributions, you can also edit the file {{/etc/default/tomcat6}} and set {{JAVA_OPTS}} there.

Once OWLIM is loaded, use any compliant JMX client, e.g. {{jconsole}} that is part of the Java development kit, to access the JMX interface on the configured port.

h1. Cache/index statistics

Statistics are kept for the main index data structures and includes information such as: cache hits/misses, file reads/writes, etc. This information can be used to fine tune OWLIM-SE's memory configuration and can be useful for 'debugging' certain situations, such as understanding why load performance changes over time or with particular data sets.

For each index, there will be a CollectionStatistics MBean published that shows the cache and file I/O values updated in real-time:

|| Package | com.ontotext |
|| MBean name | CollectionStatistics |

The following information is displayed for each MBean/index:

|| Attribute || Description ||
| CacheHits | The number of operations that completed without accessing the storage system. |
| CacheMisses | The number of operations that completed that needed to access the storage system. |
| PageDiscards | The number of times a non-dirty page's memory was reused to read in another page. |
| PageSwaps | The number of times a page was written do disk, so its memory could be used to load another page. |
| Reads | The total number of times an index was searched for a statement or range of statements |
| Writes | The total number of times a statement was added to a collection |

The following operations are available:

|| Operation || Description ||
| resetCounters | Simply resets all the counters for this index |

Ideally, the system should be configured to keep the number of cache misses to a minimum. If the ratio of hits to misses is low then consider increasing the memory available to the index (if other factors permit this).

Page swaps will tend to occur much more often during large scale data loading. Page discards will occur more frequently during query evaluation.


h1. Query monitoring and termination

Information is also available that provides details about executing queries (or more accurately query result iterators). These statistics are provided through a SailIterationMonitor MBean, with one for each repository instance. Each bean instance is named using the storage directory of the repository it relates to.

|| Package | com.ontotext |
|| MBean name | SailIterationMonitor |

The SailIterationMonitor Mbean has a single attribute {{TrackRecords}} that is an array of objects with the following attributes:

|| Attribute || Description ||
| isRequestedToStop | indicates if the query has been requested to terminate early (see below) ||
| msLifeTime | lifetime of the iterator (in ms) between being created and reaching the CLOSED state ||
| msSinceCreated | time (in ms) since the iterator was created ||
| nNext | total number of invocations of next() for this iterator ||
| nsAverageForOneNext | average time spent for one (has)Next calculation (in nanoseconds), i.e. nsTotalSpentInNext / nNext ||
| nsTotalSpentInNext | cumulative time spent in (has)Next calculations (in nanoseconds) ||
| state | current state of the iterator, values are: ACTIVE, IN_NEXT, IN_HAS_NEXT, IN_REMOVE, IN_CLOSE, CLOSED ||
| trackId | a unique id for this iterator - if debug.level is used to increase the detail of OWLIM output, then this value is used to identify queries when logging query execution plan and optimisation information ||


The collection of these objects grows for each executing/executed query, however older objects in the CLOSED state expire and are removed from the collection as the query result iterators are garbage collected.

There is a single operation available with this MBean:

|| Operation || Description ||
| requestStop | Request that a query terminates early \\ parameter: trackId of the query to stop |

This operation allows an administrator to request that a query terminates early. The operation is called {{requestStop}} and requires the trackId of the query that is to be stopped. If this operation is invoked on a running query, the {{isRequestedToStop}} flag is set to {{true}} and the next call to {{hasNext()}} will return false.


h1. Terminating a transaction

It is possible to contrive situations where committing an update transaction can take an excessive amount of time, e.g. if committing a 'chain' of many thousands of statements using some transitive property - the inferencer will attempt to materialise all possible combinations leading to hundreds of millions of inferred statements. In such a situation, it is possible to force a commit operation to abort and rollback to the state the database had before the commit was attempted.

The following MBean is used:

|| Package | com.ontotext |
|| MBean name | OwlimRepositoryManager |

This MBean has no attributes and only a single operation:

|| Operation || Description ||
| abortTransactionCommit | Request that the currently executing (lengthy) commit operation be terminated and rolled back |