Webservice debugger

Blueriq offers the capability of debugging what happens during a webservice invocation, both for SOAP and REST services. This functionality is only available when the development tools are active (i.e. the Spring profile development-tools has to be active) and a custom header is included in the webservice request to represent logpoints, referring to parts of the model. During execution of the model, a profile dump in XML is written to a special debug log file whenever a logpoint is hit.

A basic example is as follows:

GET http://example.com/server/rest/studio-calculatorbaars-mycalculatorbaars/0.0-Trunk/BAARS?X=123&Y=2&Operator=plus
Accept: application/json
Blueriq-Debugger-Logpoints: flow:MyStartFlow/service-call:Example

The presence of the Blueriq-Debugger-Logpoints  header activates a logpoint  that triggers whenever the service call named "Example" within flow "MyStartFlow" executes. Multiple logpoints can be activated by comma-separating them, as well as including the header multiple times:

GET http://example.com/server/rest/studio-calculatorbaars-mycalculatorbaars/0.0-Trunk/BAARS?X=123&Y=2&Operator=plus
Accept: application/json
Blueriq-Debugger-Logpoints: flow:MyStartFlow/service-call:Example, flow:MySubflow/subflow:AnothterSubflow
Blueriq-Debugger-Logpoints: flow:AnothterSubflow/service-call:Example

The above example activates three logpoints.

The profile XML is written to a dedicated debugger log file, separate from the regular log file. It is stored in the same location as the regular log, but suffixed with .debugger.log. Please note that the debugger file is only active when a log file has been configured using the logging.file.name  property. The development dashboard allows you to open the debugger log from the left sidebar (which is typically collapsed) using the "View debugger log" button.

Debugger ids

The debugger id is an identifier that corresponds with a part of the model. Debugger ids are case-insensitive. The runtime supports the following list of debugger ids:

Flow nodes

Each node in the flow is considered as a potential logpoint, according to the following naming convention:

A logpoint for a flow node is triggered before the flow node is evaluated. Setting a logpoint at the start of a flow can be accomplished by using the debugger id of the node that is linked from the start node, as the start node itself does not have a logpoint. Multiple occurrences of a service-call/function-call/subflow within the same flow cannot be distinguished, as the debugger id is only determined based on the referenced name.

Data mapping

Each direction of a data mapping have their own ids, with the possibility to log the source profile before the mapping executes and the target profile before and/or after the mapping has executed.

Domain schema & schema sets

Reading XML and JSON data into the profile is done through either a domain schema or a schema set. The following ids can be used to log the profile after the profile has been populated from the data:

Logging configuration

The runtime includes default logging configuration such that debugger logging is redirected to a separate debugger log, according to the following Logback configuration snippet:

<configuration>
	<!-- ... -->

	<!-- Debugger logger -->
	<springProfile name="development-tools">
		<if condition="isDefined("logFile")">
			<then>
				<logger additivity="false" level="INFO" name="com.blueriq.debugger">
					<appender-ref ref="DEBUGGER"/>
				</logger>
				<appender class="ch.qos.logback.core.rolling.RollingFileAppender" name="DEBUGGER">
					<encoder>
						<pattern>
							<![CDATA[%d{yyyy-MM-dd HH:mm:ss.SSS} userId="%X{userId}" project="%X{projectName}:%X{projectVersion}" [trace=%X{traceId:-},span=%X{spanId:-}] - %msg%n%n]]>
						</pattern>
					</encoder>
					<file>${logFile}.debugger.log</file>
					<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
						<!-- rollover daily -->
						<fileNamePattern>${logFile}-%d.debugger.log</fileNamePattern>
						<!-- retain at most 7 days of debug logging -->
						<maxHistory>7</maxHistory>
					</rollingPolicy>
				</appender>
			</then>
		</if>
	</springProfile>
</configuration>

In a custom runtime, it may be necessary to realize a similar configuration to redirect log entries from the com.blueriq.debugger logger to a dedicated file.