MarkLogic 8 Http Server Rewriter and Debugging Tips
27 October 2015 08:40 PM


A powerful new feature was added to MarkLogic 8 - the ability to build applications around a declarative HTTP rewriter. You can read more about MarkLogic Server's HTTP rewriter and some of the new features it provides in our documentation.

This article will cover some basic tips for debugging applications that make use of this feature.

Validating your rewriter rules (Using XML Schema)

The rewriter adheres to an XML Schema. At runtime the rewriter is not validated against this schema; this is by design so that potentially minor errors don't risk taking your application offline. As a best practice, we recommend validating your rewriters manually every time you make a change. In order to do this, you can use MarkLogic Server or any other tool that supports XML validation (the schema is standard XSD 1.0).  If you want to view the schema, it's copied to Config/rewriter.xsd when you install the product.

In order to validate from within MarkLogic using XQuery you can simply execute:

validate { fn:doc("/path/to/your/rewriter.xml") }

The above will validate the XML if your rewriter rules are stored in a database. If you're using the filesystem, you can use xdmp:document-get instead.

Alternatively, you can copy / paste the XML body into Query Console and wrap it with a call to validate as below:

validate { * Paste your rewriter rules here * }

The above approach should work without any issue as long as there is no content in your rewriter XML that contains any XQuery reserved syntax.

General rewritter debugging and tracing

For a simple "print" style debugging you can manually add trace statements at any point an eval rule is allowed. Like this:

<trace event="customevent">data</trace>

Then enable diagnostics (in your group settings) and add "customevent"; your custom trace will now show up in ErrorLog.txt whenever that endpoint is accessed. To read more on the use of trace events in your applications, refer to this Knowledgebase article

There is error code handling:

<error code="MYAPP-EXCEPTION" data1="value1" data2="... 

You can also add ids - these will be traced out - which may aid debugging

<match id="match-id-for-myregex" regex=".* ...

Useful diagnostic trace events

Note that additional trace events can generate a lot of data and may slow your application down, so make sure these do not get left on in a production-critical environment

Below are some trace events you can use and a brief description of what each trace event does:

Rewriter Parser Details of the parsing of the rewriter XML file
Rewriter Evaluator Execution traces of rules as evaluated
Rewriter Evaluator Verbose Additional (more verbose) tracing
Declarative Rewriter Entry points into and out of the rewriter from the app server request handler
Rewriter Print Rules After parsing and validation of the rewriter – a full dump of the internal data structures that resulted.

Additional points to note

Use of the "Evaluator" traces will write to the ErrorLog.txt on every request.

The "Parser" trace event will only occur once or upon updating your rewriter.

(0 vote(s))
Not helpful

Comments (0)