Debug API

Overview

As Relativity is shipped as a pre-built server, debugging it might pose a concern. The good thing is that in most cases there is no need to debug Relativity at all. Any errors occurred during accessing or updating the database, be it caused by a Domain misconfiguration or database issues, are wrapped into an exception and are sent back to the caller. So it is usually enough just to evaluate the exception message and fix the error.

However in some advanced cases it might be necessary to take a look at the internal Relativity processes. For such cases Relativity exposes an advanced Debug API. It might look overcomplicated, but this API has been not designed for everyday use. This is a very advanced tool that should be used as a last resort in pinpointing an issue.

In the future releases of Relativity some additional methods might be introduced into the Debug API to simplify it.

Workflow

There are two possible workflows in using the Debug API:

1. Simple one:

   1.1. Create a simple application where the Relativity server data access issue can be reproduced.

   1.2. Enable the request trace feature using the SetTraceRequestMode method (see below). This method should be called before the failing data access operation.

   1.3. Run the data access operation that fails.

   1.4. Disable the request trace feature using the SetTraceRequestMode method.

   1.5. Retrieve the gathered trace info using the GetRequestInfo method (see below).

2. A more complex workflow that might be required if it is not possible to create a simple testcase application and revert to the 1st workflow:

   2.1. Modify the failing application so it will log the Session ID assigned to the user using that application. This value can be accessed via the ClientID property of the Message instance used to communicate with the Relativity server.

   2.2. Create a separate application. In this application instead of logging into a Relativity server instance just assign a Session Id value logged on the step 2.1. to the Message.ClientID property. This will allow to perform following operations in the context of the user of the main application.

   2.3. Enable the request trace feature using the SetTraceRequestMode method (see below). This method should be called before the failing data access operation.

   2.4. Perform actions in the main application that result in the issue that has to be investigated.

   2.5. Run the data access operation that fails.

   2.6. Disable the request trace feature using the SetTraceRequestMode method.

   2.7. Retrieve the gathered trace info using the GetRequestInfo method (see below).

So the 'simple' workflow is quite straightforward. It can be described as 'Enable tracing -> Execute failing operation -> Gather the info'.

The 'complex' workflow requires more actions, but it allows to take a closer look at the actions performed by a real application. In this workflow the second tracing application just attaches itself to an existing user's session and gathers information from it.

API description

Methods

Debug API is based on 2 additional methods present in the Relativity DataService. These methods can only be called by a user with Developer role assigned.

Method	Description
SetTraceRequestMode	Enables or disables request trace depending on the enableTrace parameter value
GetRequestInfo	Returns an RequestInfo instance containing the gathered trace info. Please be aware that this operation also resets the server-side trace info buffer

Data Types

RequestInfo

Gathered trace info, including unhandled exceptions occurred during the data access operations.

Property	Type	Description
ReadRequests	array of ReadTableRequestInfo	Incoming data read requests
UpdateRequests	array of DeltaInfo	Incoming Delta containing data update requests
ScriptMessages	array of EventInfo	Messages emitted by the Business Rules scripts
SqlStatements	array of EventInfo	SQL statements executed by the Relativity server, including parameter names and values
Exceptions	array of EventInfo	Unhandled exceptions occurred during the data access operations

ReadTableRequestInfo

Description of a data read request

Property	Type	Description
Date	Date	UTC date and time of the data read request
Version	Integer	Version of the request object. Value of this property will be 6 for DA SQL requests
TableName	String	Name of the requested Schema table. Not applicable for DA SQL requests
IncludeSchema	Boolean	Flag indicating whether the response stream should also include the Schema meta-info
MaxRecords	Integer	Max amount of data rows to be returned
DynamicSelectFields	array of String	List of fields requested via the Dynamic Select feature. Not applicable for DA SQL requests
ParameterNames	array of String	List of request parameter names
ParameterValues	array of Variant	List of request parameter values
DynamicWhereXml	Xml (where supported), otherwise String	XML representation of the Dynamic Where filter applied to the request
DynamicWhereSql	String	SQL-like string representation of the DynamicWhereXml value
Sql	String	DA SQL request string. Applicable only to DA SQL requests

DeltaInfo

Description of a Delta package applied to the underlying database

Property	Type	Description
Date	Date	UTC date and time of the data update request
TableName	String	Name of the updated Schema table
IsReduced	Boolean	Flag indicating whether the Delta was sent in the Reduced Delta mode
DeltaChanges	array of DeltaChangeInfo	List of detailed descriptions of every data row change

DeltaChangeInfo

Property	Type	Description
FieldNames	array of String	List of table fields present in the field values lists
OldValues	array of Valriant	List of field values before the data change. In most cases this list contains only Primary Key values
NewValues	array of Valriant	List of field values after the data change

EventInfo

Generic event information

Property	Type	Description
Date	Date	UTC date and time of the event
Category	Event category, f.e. "SQL Statement" or "Script Message"
Message	Event message, f.e. a full dump of the SQL statement being executed
Source	Event source, including Domain and Domain Schema name