prof:allowed

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

Summary

Returns the value of the Profile Allow setting for the App Server or Task Server upon which the target request is running. This function is useful to determine if subsequent calls to profiling functions will be effective.

For details on profiling requests and interpreting the output of a profile request, see Profiling Requests to Evaluate Performance in the Query Performance and Tuning Guide.

Required Privileges

Either http://marklogic.com/xdmp/privileges/profile-my-requests or http://marklogic.com/xdmp/privileges/profile-any-requests is required for profiling requests other than the current request, with the profile-my-requests privilege allowing profiling of requests issued by the same user ID, and the profile-any-requests privilege allowing profiling of requests issued by any user ID. No privilege is required to profile the currently running request (that is, self-profiling is always allowed).

Usage Notes

Use this function to determine if profiling is allowed on the App Server that owns the target request. This will indicate whether the other profiling functions will be effective.

If the Profile Allow setting is off on the App Server, then calls to profiling functions do nothing and return the empty sequence. You can use prof:allow to test if profiling is allowed on the App Server, and if it is then use the other profiling APIs to profile other requests or to call prof:eval or prof:invoke; if it is not allowed, then your code does not call them. This type of logic allows you to keep profiling code in your XQuery code and it will only be executed if profiling is allowed in the context in which the code is run, thus allowing you to globally (at the App Server level) switch off profiling without breaking any code.

Appropriate privileges are required to call this function, as with the other profiling functions. The return value is the state of the App Server Profile Allow setting. This function does not verify that the target request is stopped for debugging, which is required for one request to profile another.

Example

  prof:allowed(xdmp:request())
  => true
  

Example

let $profallowed := prof:allowed(xdmp:request())
return
(
  if ( $profallowed )
  then ( prof:eval('fn:current-dateTime()') )
  else ( ),
  "your code here"
)
 
  => The profile report (only if profiling is enabled
     on the App Server) followed by the output of your code.