Profiler in MarkLogic Server

Profiling is a very important aspect when developing and supporting almost any application. This also applies to databases. Especially with large amounts of information, the performance of queries to the data warehouse is very critical. As for the performance of queries in MarkLogic Server and their profiling, we can say that these questions are among the most important since the XQuery used in MarkLogic Server allows you to write not only very complex queries to the DB itself but also quite complex applications.

In MarkLogic Server there is a fairly good profiling functionality presented in ten built-in functions. All of them are located in the “http://marklogic.com/xdmp/profile“ namespace and are available with the prefix “ prof: ”

prof:eval( $xquery as xs:string, [$vars as item()*], [$options as node()?] ) as item()* 

')
This function is passed XQuery as a text string whose performance is worth testing.

 prof:eval( "1 + 1" ) 

The return value for prof: eval is a sequence (<XML with report>, <execution result of XQuery>). The report contains quite detailed information about the execution of XQuery.

Example

 <prof:metadata> <prof:overall-elapsed>PT0S</prof:overall-elapsed> <prof:created>2013-09-13T00:00:00.000+04:00</prof:created> <prof:server-version>6.0-3</prof:server-version> </prof:metadata> <prof:histogram> <prof:expression> <prof:expr-id>13367197075475374717</prof:expr-id> <prof:expr-source>1 + 1</prof:expr-source> <prof:uri/> <prof:line>1</prof:line> <prof:column>33</prof:column> <prof:count>1</prof:count> <prof:shallow-time>PT0S</prof:shallow-time> <prof:deep-time>PT0S</prof:deep-time> </prof:expression> </prof:histogram> </prof:report>, 2 

It is worth noting that the XQuery thus transmitted is in no way connected with the context in which prof: eval is executed. In order to pass parameters to the debugged XQuery, you can use the $ vars parameter, which is a sequence of variables in the form (QName, <value>). Example

 prof:eval( "declare variable $a external; $a + 1", (fn:QName("", "a"), 1) ) 

or so

 prof:eval( "declare variable $a external; declare variable $b external; $a + $b", (fn:QName("", "a"), 1, fn:QName("", "b"), 1) ) 

If an error occurs while executing XQuery, then prof: eval throws a PROF-PROFILEALLOW exception .

About the following function, it can be said that it is similar to prof: eval, with the only exception that it accepts not XQuery as a text string, but the path to the XQuery module.

 prof:invoke( $path as xs:string, [$vars as item()*], [$options as node()?] ) as item()* 

An XQuery module does not have to be a library; it must be a “main” executable module. The path to the module is resolved relative to the application server root. And the rest of prof: invoke is completely analogous to prof: eval .

MarkLogic Server allows you to create profiles not only for the XQuery passed in the prof: eval and prof: invoke functions, but also for instructions that are directly in the program module. Moreover, profiling is not tied to a specific program code, but to a request processed by the server. This allows you to debug not only the code in the current request, but also to analyze any request by knowing its ID and not interfering with the application code, which can be very useful in case of analyzing an application in the production environment.

To start collecting performance information, call the function

 prof:enable( $request-id as xs:unsignedLong ) as empty-sequence() 

Where $ request-id is the request ID for which to start profiling.
You can get the ID of the current request using the xdmp function : request () .
In order to stop the collection of information you need to use the function

 prof:disable( $request-id as xs:unsignedLong ) as empty-sequence() 

As it follows from the above, you can profile any code processed between calls of the prof: enable and prof: disable functions if profiling is performed for the current request, or between times to which these functions were called if the current request is not analyzed.

When trying to use a profiler, it checks for the following user rights.
“Http://marklogic.com/xdmp/privileges/profile-my-requests” - for profiling your requests
“Http://marklogic.com/xdmp/privileges/profile-any-requests” - for profiling any requests
Of course, there is a small exception - for profiling the current request (the request for which the profiling functions are located) no special ghosts are required, and “profile-my-requests” entitles you to profiling all (excluding the current) requests of the current user.
To check whether profiling is available for a particular query, you can use the function

 prof:allowed( $request-id as xs:unsignedLong ) as xs:boolean 

In order to obtain the collected information on the execution of the request, use the function

 prof:report( $request-id as xs:unsignedLong ) as element(prof:report)? 

Unlike prof: eval , which returns a report and the result of XQuery execution, the prof: report function returns only a report.

Prof: report usage example

 let $e as empty-sequence() := prof:enable( xdmp:request() ) let $r as xs:string := fn:string( 1 + 2 ) return prof:report( xdmp:request() ) 

Sometimes there is a need to remove the accumulated information and start maintaining a report again, for this is used the function

 prof:reset( $request-id as xs:unsignedLong ) as empty-sequence() 

The following function is similar to the prof: eval function, but unlike it, prof: value inherits the context when the specified XQuery is executed

 prof:value( $expr as xs:string ) as item()* 

Context inheritance by the prof: value function allows you to write such code

 let $a := 1 let $b := 2 return prof:value('$a + $b') 

There are two more interesting features.

 prof:xslt-eval( $stylesheet as element(), $input as node()?, [$params as map:map?], [$options as node()?] ) as item()* 

 prof:xslt-invoke( $path as xs:string, $input as node()?, [$params as map:map?], [$options as node()?] ) as item()* 

Where $ input is an XML document that is processed in an XSLT processor.
From the name of these functions it is clear that they are similar to the functions prof: eval and prof: invoke , but are used for profiling XSLT, the processor of which the developers of MarkLogic Server so carefully integrated into their product.

MarkLogi Server provides powerful tools for performance analysis. With this mechanism you can create complex profilers for various tasks. At the same time, MarkLogi Server has a graphical profiler in the built-in console, which makes the analysis process easier and more convenient for small tasks and in the development process.