Query Performance and Tuning Guide — Chapter 7

Monitoring MarkLogic Server Performance

This chapter provides an overview to various ways to monitor the status in MarkLogic Server, both through the Admin Interface and through Server Monitoring APIs designed to report status of various parts of the system. This chapter includes the following sections:

Ways to Monitor Performance and Activity
Server Monitoring APIs

Ways to Monitor Performance and Activity

This section describes the following ways to monitor various activity on MarkLogic Server:

Monitoring History Dashboard
Server Logs
Status Screens in the Admin Interface
Create Your Own Server Reports

Monitoring History Dashboard

The Monitoring History dashboard is used to capture and make use of historical performance data for a MarkLogic cluster. Once the performance data has been collected, you can view the data in the Monitoring History page. The top-level Monitoring History page provides an overview of the performance metrics for all of the key resources in your cluster. For each resource, you can drill down for more detail. You can also adjust the time span of the viewed data and apply filters to view the data for select resources to compare and spot exceptions.

For details on the Monitoring History dashboard, see the MarkLogic Server Monitoring History chapter in the Monitoring MarkLogic Guide.

Server Logs

The logs for MarkLogic Server are an important source of information about activity on the server, particularly information about error conditions. The logs are all stored in the Logs directory under the MarkLogic Server data directory (typically c:\Program Files\MarkLogic\Data\Logs in windows, /var/opt/MarkLogic/Logs under UNIX-based systems). There are two types of logs:

ErrorLog.txt, which logs MarkLogic Server exceptions, startup activity, and so on.
port_no_AccessLog.txt, which logs access requests (for example, HTTP requests) for the App Server running at the specified port.

You can configure how long to keep a log before starting a new one, at which level to log activity, and how many old log files to keep before deleting (they have a number appended to their name, for example, ErrorLog_5.txt indicates 5 new log files have been created since this one was used). For more details on configuring the log files, see the Administrator's Guide.

Another option you can configure, at the App Server level, is for any uncaught application exceptions to be written to the ErrorLog.txt file. This way, if your application throws an exception (for example, if it has a syntax error), the error message is logged in addition to being sent to the client. This is useful in debugging, especially if queries are being generated via user activity on a browser or through a WebDAV client.

You can also code your own log messages into an application using xdmp:log. You can use xdmp:log to log any message at any level, and that message is written to the ErrorLog.txt file when it is called. Log messages are useful in debugging during development, and are also useful in logging certain activities in production.

For operational purposes, some developers write scripts or programs to monitor the logs for specific messages. Then, if the specific message is logged, the script or program can send some sort of alert out (for example, page someone or send a message to someone).

The logs contain important information that can be used in monitoring MarkLogic Server. The logs can be a powerful tool in an overall monitoring policy. How you use that information depends on your requirements.

There must be sufficient disk space on the filesystem in which the log files reside. If there is no space left on the log file device, MarkLogic Server will abort. Additionally, if there is no disk space available for the log files, MarkLogic Server will fail to start.

Status Screens in the Admin Interface

The Admin Interface includes many pages that list current activity and status for various parts of MarkLogic Server. To access the status pages, click the status tab in the part of the Admin Interface to which you want to find current system information.

The following table lists the status pages available in the Admin Interface, along with the location path to the status tab in the Admin Interface and a description of each page.

Name	Location	Description
System Status	Configure > Status	Provides a summary of all information throughout the entire MarkLogic Server cluster, including host, App Server, database, and forest information. Also includes buttons to restart or shutdown all of the hosts in the cluster.
Group Status	Groups > group_name > Status	Provides a summary of all information throughout the MarkLogic Server group, including host, App Server, database, and forest information. Also includes buttons to restart or shutdown all of the hosts in the group.
Host Status	Hosts > host_name > Status	Provides a summary of the current conditions on the host, including information about App Servers, forests, and active queries. Also includes buttons to enter a new license key, restart, or shutdown the host.
App Server Status	Groups > group_name > App Servers > app_server_name > Status	Shows information about activity on the App Server, including queries active on each host and the ability to cancel the queries.
Task Server Status	Groups > group_name > Task Server > Status	Shows information about activity on the task servers for the group, including the number of requests being processed and the number of tasks queued on the task server.
Database Status	Databases > db_name > Status	Shows activity on the specified database. Shows if any merges are in progress and if reindexing is in progress, and gives estimates about how long they will take. Shows information about the database, including the number of documents, number of fragments, and its size. Optionally shows forest status information.
Forest Status	Forests > forest_name > Status	Shows information and activity about the specified forest, including merge activity, number of stands, size, space available, and so on. Also includes a button to restart the forest, which forces the forest to go offline. Once it is offline, it will automatically attempts to rejoin the host, resulting in a restart of the forest. If failover is enabled, a restarted forest will first attempt to join the primary host.

Create Your Own Server Reports

The status pages in the Admin Interface provide a lot of detail about many parts of the system. If you want information about MarkLogic Server status in a different form, however, or if you want to combine it with some other application-specific information, you can build your own server reports using the Server Monitoring APIs. For more details, see the next section.

Server Monitoring APIs

The Server Monitoring APIs are XQuery functions that return XML representations of current activity of various parts of MarkLogic Server. Because they are XQuery functions, you can build any application you deem necessary with them. For example, perhaps you want a summary page that shows some different information then the system status page in the Admin Interface, or perhaps you want to combine some of that information with some content from your application. Perhaps you want to integrate it with a site-wide monitoring system. Whatever your requirements, because the APIs return XML, it is easy to write an application to display the information in whatever way fits your needs.

The following are the monitoring functions available:

The xdmp:forest-counts function can take some time to compute on large systems, as it must query the forest to determine some of the counts. You can limit the work it performs with the optional second argument. For more details about syntax and usage of these functions, see the Server Monitoring functions in the MarkLogic XQuery and XSLT Function Reference.