The Management API is a REST-based API that allows you to access MarkLogic Server instrumentation with no provisioning or set-up. The API provides the ability to easily capture detailed information on MarkLogic Server objects and processes, such as hosts, databases, forests, App Servers, groups, transactions, and requests from a wide variety of tools. The Monitoring Dashboard and Nagios plugin described in this guide are implemented on top 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.
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 Administrator's Guide.
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.
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.
|Type of Resource Address||Returns|
|List||A list of resources. For example, as list of the forests in the cluster:|
|Item||A specific resource. For example, a specific forest in the cluster:|
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
format parameters, as shown below.
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:
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:
The application that issues a request to the Management API specifies the format for the returned view. For example, most Web browsers specify the default return format as HTML. If no return format is specified by the application, the view is formatted as XML. You can explicitly specify the view format by means of the
format parameter at the end of the resource address:
<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>
property parameter filters the monitor content returned by the resource address. The results returned from the above resource address include the forest id and name, along with the metadata,
forest-counts : id : 4514318629528848231 name : Documents meta : uri : /manage/LATEST/forests/Documents?view=counts&property=stands-counts current-time : 2011-06-29T13:24:08.469-07:00 elapsed-time : 0.007 count-properties : stands-counts : stand-counts : stand-id : 8558661396116142072 path:C:\Program Files\MarkLogic\Data\Forests\Documents\00000008 active-fragment-count : 86 nascent-fragment-count : 0 deleted-fragment-count : 0 related-views : related-view : default
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.
|Type of Resource Address||Element||Description|
|Item and Item View||The item id number.|
|Item and Item View||The item name (not available for requests and transactions).|
|Server Item||The type of App Server (http, WebDAV, or XDBC)|
|Item, Item List, and View||Metadata that describes:|
|View||The properties of the item or item list view.|
|Item and Item List||The items that are related to this item or item list.|
|Item List||The items in this item list|
|Item, Item List, and View||The views related to this item or item list. If an item, the item list view is also included.|