Monitoring MarkLogic Guide — Chapter 5

Terms used in this Chapter

• An Object is a component of interest in MarkLogic Server, such as a cluster, host, App Server, or database.
• A Process is a request or transaction in MarkLogic Server.
• Monitor Content is the XML, HTML, or JSON structure that represents the data returned by the Management API.
• A Monitor Application can be any application that requests and makes use of monitoring data, such as a Web browser, a plugin for an existing monitoring tool, or the Monitoring Dashboard described in Using the MarkLogic Server Monitoring Dashboard.
• The Monitor Host is the host in the MarkLogic Server cluster that exposes the Management API to respond to requests for monitoring content from a monitor application.
• The Manage App Server is the App Server on the Monitor Host that is configured to handle monitor requests. The Manage App Server is bound to port 8002 and is the App Server used by the Monitoring Dashboard.
• REST stands for Representational State Transfer, which is an architectural style that, in the context of monitoring MarkLogic Server, describes the use of HTTP to make calls between a monitoring application and monitor host.
• A Resource is an abstraction of a MarkLogic Server object, as represented by the REST architecture.
• A Resource Address is a URL that identifies a MarkLogic Server resource. The resource addresses are described in Resource Addresses.
• A View is the returned monitoring information about a resource. You can have different views of the same resource. A view can be for a single resource (known as an item view) or a number of resources (known as a list view).
• A Representation is a view of a resource in a particular format, such as XML, HTML, or JSON.
• A Parameter is an addition to the end of a resource address to filter and/or format the view returned from MarkLogic Server. Parameters are expressed as query strings in the URL and are described in Specifying Parameters in a Resource Address.
• An Endpoint is an XQuery module on MarkLogic Server that is invoked by and responds to an HTTP request for monitoring information.
• A Plugin is an XQuery module that provides extension capabilities using the Plugin framework described in the System Plugin Framework chapter in the Application Developer's Guide.

Overview of the Management API

The Management API is implemented on top of the REST Library described in Creating an Interpretive XQuery Rewriter to Support REST Web Services in the Application Developer's Guide. Requests to monitor an object in MarkLogic Server are made by means of a resource address that returns a view containing the monitor data for the object. The view can be returned in various formats, such as XML, HTML, or JSON.

Every resource address in the Management API invokes a monitoring endpoint, which is an XQuery module on the target MarkLogic Server host. The monitoring endpoints are invoked by a resource address in an application, such as a browser. The Management API uses the REST library to validate the request, authorize the user, and rewrite the resource address to one understood by the monitoring framework before invoking the endpoint module. The endpoint module returns the monitoring data for the resource to the application.

Security

As described in Monitoring Tools and Security, client access to a Management API and endpoints requires that they authenticate as a user with the manage-user role. If custom Plugin code requires additional privileges, you can create and assign a custom role to users of the Management API to enable that functionality.

If you have enabled SSL on the Manage App Server, your resource address must start with HTTPS, rather than HTTP, and you must have a MarkLogic certificate authority on your browser, as described in Accessing an SSL-Enabled Server from a Browser or WebDAV Client in the Security Guide.

Management API Requires Writing to the App-Services Database

The Management API sometimes writes documents to the App-Services database for internal purposes, and it therefore assumes that the App-Services database is writable. On each cluster in which the Management API runs (which might include a replica cluster), it requires a writable view of the App-Services database. The App-Services database is used to store data used by various MarkLogic applications, such as Query Console. For these reasons, MarkLogic recommends that you do not replicate the App-Services database using database replication. If the App-Services database is not available, it falls back to the schemas-database configured for the schemas-database of the App Server under which the Management API is running.

Resource Addresses

This section provides an overview of the structure and capabilities of the resource addresses provided by the Management API. For details on each resource address, see the MarkLogic REST API Reference.

Resource addresses fall into the categories listed in the table below. The output from each type of resource address is described in Interpreting the Output.

http://localhost:8002/manage/LATEST/forests

http://localhost:8002/manage/LATEST/forests/Documents

A resource address takes the form of a URL that includes a host name and a port number. The most basic resource address returns summary information for the entire cluster:

http://host:port/manage/LATEST/

The Management API version, LATEST in this release, is specified in every resource address to maintain compatibility with future revisions of the Management API.

You can optionally include the name of a resource and parameters in a resource address as follows:

http://host:port/manage/version/resource?param=value&param=value

Obtaining the Options Node for a Resource Address

As described in Creating an Interpretive XQuery Rewriter to Support REST Web Services in the Application Developer's Guide, the REST Library uses an options node to map incoming requests to endpoints. The options node contains information about the communication options available on the request/response chain for the resource address, such as which parameters can be specified with the resource address.

You can use the xdmp:http-options function to output the options node for any resource address. For example, you can enter the following query in Query Console to display the options node for the /manage/LATEST/transactions resource address:

xdmp:http-options(
  "http://localhost:8002/manage/LATEST/transactions",
  <options xmlns="xdmp:http">
    <authentication method="digest">
      <username>admin</username>
      <password>admin</password>
    </authentication>
  </options>)

The output will include a request element that defines the options associated with the GET and HEAD methods for the resource address. From this, you can determine the supported parameters and values. For example, the above resource address supports the view, seconds-min, host-id, fullrefs, and format parameters, as shown below.

<rest:http method="GET">
  <rest:param name="view" values="default" default="default"/>
  <rest:param name="seconds-min" as="string"/>
  <rest:param name="host-id" as="string"/>
  <rest:param name="fullrefs" as="boolean" required="false"/>
  <rest:param name="format" as="string" values="xml|json|html"/>
  <rest:or>
    <rest:accept>application/xml</rest:accept>
    <rest:accept>application/json</rest:accept>
    <rest:accept>text/html</rest:accept>
    <rest:accept>application/x-javascript</rest:accept>
  </rest:or>
</rest:http>

Specifying the Management API Version

To guarantee stable behavior of the Management API as new versions are released, each resource address in the Management API includes a version number. The examples in this chapter show the version as LATEST, which means to use the latest version of the API. However, you can also specify the version number to use a specific version of the API, using the format:

v#

Where # is the version number. For example, in the initial version of the API:

http://localhost:8002/manage/LATEST/databases

is the same as:

http://localhost:8002/manage/v2/databases

If you want to update your clients when you choose, use the explicit version number. If you want to update your clients to the most recent version of the Management API, use LATEST.

The version number is only updated when resource addresses and/or parameters have changed. It is not updated when resource addresses and/or parameters are added or removed.

Specifying Parameters in a Resource Address

Resource addresses can take parameters to do the following:

• Specify the format of the returned view
• Return a filtered view

To specify multiple parameters, use the '?' sign before the first parameter and the '&' sign before any additional parameters:

http://host:port/manage/LATEST/resource?param1=value&param2=value....

Some resource addresses support optional parameters that are specific to that resource address. For example, to return monitoring information on the forests used by the Documents database, you can use the database-id parameter with the /forests resource as follows:

http://monitor_host:8002/manage/LATEST/forests?database-id=Documents

The remainder of this section describes the format parameter in more detail.

format=value

http://monitor_host:8002/manage/LATEST?format=xml 

<cluster-default xsi:schemaLocation=
  "http://marklogic.com/manage/clusters manage-clusters.xsd">
  <meta>
    <uri>/manage/LATEST</uri>
    <current-time>2011-06-30T16:00:06.81-07:00</current-time>
    <elapsed-time units="sec">0.012</elapsed-time>
  </meta>
  <relations>
    <relation-group array="true">
      <uriref>/manage/LATEST/databases</uriref>
      <typeref>databases</typeref>
      <relation-count>13</relation-count>
    </relation-group>
    <relation-group array="true">
      <uriref>/manage/LATEST/forests</uriref>
      <typeref>forests</typeref>
      <relation-count>13</relation-count>
    </relation-group>
    <relation-group array="true">
      <uriref>/manage/LATEST/groups</uriref>
      <typeref>groups</typeref>
      <relation-count>1</relation-count>
    </relation-group>
    <relation-group array="true">
      <uriref>/manage/LATEST/hosts</uriref>
      <typeref>hosts</typeref>
      <relation-count>1</relation-count>
    </relation-group>
    <relation-group array="true">
      <uriref>/manage/LATEST/requests</uriref>
      <typeref>requests</typeref>
      <relation-count>1</relation-count>
    </relation-group>
    <relation-group array="true">
      <uriref>/manage/LATEST/servers</uriref>
      <typeref>servers</typeref>
      <relation-count>8</relation-count>
    </relation-group>
    <relation-group array="true">
      <uriref>/manage/LATEST/transactions</uriref>
      <typeref>transactions</typeref>
    </relation-group>
  </relations>
  <related-views>
    <related-view array="true">
      <view-type>item</view-type>
      <view-name>query</view-name>
      <view-uri>/manage/LATEST/query</view-uri>
    </related-view>
    <related-view array="true">
      <view-type>item</view-type>
      <view-name>status</view-name>
      <view-uri>/manage/LATEST?view=status</view-uri>
    </related-view>
  </related-views>
</cluster-default>

Interpreting the Output

The reference documentation for the Management API in the MarkLogic REST API Reference describes each element in the XML output for each Management API resource address.

The main elements in the output from each resource address for an item or item list are shown in the table below.

id

name

server-kind

meta

view-properties

relations

list-items

related-views