Debug Reports

This topic introduces developers to debugging techniques for use with Logi Studio. It provides you with information about the tools and techniques available in Studio to help you understand what's happening within your application, especially if things don't work as expected.

Previewing and Browsing

A Logi application may have one or more report definition files and, while actually browsing a report shows you the big picture, doing so can be cumbersome if you have multiple definitions. Studio's Preview tab provides the developer with a fast way to view the report definition currently being edited in the Workspace Panel, without changing the Default Report attribute in the _Settings definition.
 

To preview a Report definition:

  1. In the Application Panel, select and open the report definition to preview.
  2. Click the Preview button at the bottom of the Workspace Panel, as shown above.
  3. Browse and interact with the report definition using the toolbar at the top of the Preview panel.

Logi Info developers can also test their Process and Data definitions in a similar way:

  1. In the Application Panel, select and open the process definition to test.
  2. In the Test Parameters Panel, set values for any parameters the process task requires.
  3. At the bottom of the Workspace Panel, select the individual process task to test in the task list.
  4. Click the Run button at the bottom of the Workspace Panel, as shown above.


When using Preview, any JavaScript errors thrown will cause a count of the errors to appear next to the preview URL:
 

Click the number, as shown above, to display a dialog box containing the JavaScript error message. In earlier versions of Studio, the dialog box will simply be displayed automatically, interrupting execution.

 

Using Live Preview

The Live Preview feature allows you preview your work in a separate, "live" desktop window.

 

The Main Menu's Live Preview item is shown above. The live preview will be displayed in a separate window and any changes made to the definition will immediately be reflected in that window. You can resize and relocate the new preview window as desired; you can even drag it onto a separate display, if you have one.

You can also switch to Live Preview from regular Preview mode:
 


     

To start Live Preview, first preview the report definition, using the Preview tab, and then click the Live Preview icon, circled above.

The preview will be displayed in a separate window, and Studio will switch back to its Definition tab. You can resize and relocate the new preview window as desired; you can even drag it onto a separate display, if you have one.

Any subsequent changes you make to the definition code will immediately be reflected in the Live Preview window.
 

If you don't want definition changes to be updated immediately in the Live Preview window, you can pause and restart them, using the Pause and Play icons in the Live Preview window, circled above.

To exit Live Preview, just click the Live Preview window's Close (X) icon.
 

Browsing the Default Report Definition

In a Logi application, one of the report definitions is designated (in the _Setting definition) as the "default" report - the page that will be shown if no definition is specified in the URL. If you don't change it, this is usually the Default report definition.

 

     

You can browse the default report by clicking the Run Application menu item, shown above, in Studio's Main Menu, or by pressing the F5 key. Your computer's default browser (the one associated with .htm/.html file extensions) will be used for this.

You can change the "default" report designation using two methods:
 

As shown above, left, in the Application panel, select the desired report definition, right-click it, and select Set As Default from its context menu. This sets the Application element's Default Report attribute, shown above, right, in the _Settings definition. You can also manually edit this attribute value directly in the _Settings definition.

Using the Run Application menu item will save all open, unsaved definitions before displaying the report.

Back to top

Using Comments, Remarks, and Application Notes

As an application grows in size and complexity, it's often helpful for developers to leave in-line comments and descriptive notes within the definitions. The Note element holds these comments and can be placed anywhere in a report definition; it's ignored when the report is executed.
 

In the above example, Note elements have been placed in the _Settings definition to provide instructions for other developers. Placing the Notes in different levels of the element tree establishes context for the reader, as shown by the final Note element above. Blue is the default note text color, but you can change this using Studio's Tools Options menu

To add a comment:

  1. Add the Note element to the definition, like any other, wherever it makes sense to you.
  2. Select the newly added Note element to define its attributes.
  3. Double-click the Note attribute to open the Zoom window, type your comment, and click OK.
  4. To prevent Notes from appearing in the generated HTML page, remark them (see below).

Remarking Elements

During development, it may be helpful to temporarily "comment out" certain elements. The developer can remark a single element or an entire hierarchy of sub-elements in order to temporarily hide them from execution. This can be an important debugging tool as it allows you to selectively prevent execution of parts of the application.

A common troubleshooting technique is to remark a definition repeatedly, successively reducing it down to fewer and fewer basic parts, in order to isolate the source of a difficult-to-find error.
 


In the example above, the first Divisions in the element tree is active. The second Division element has been remarked and appears in a green font; it is therefore inactive and will not be rendered in the final HTML output. Green is the default color but you can change this using Studio's Tools Options menu.

Remarked elements do not affect the appearance or functionality of the application but remain present in the definition file. At runtime, the Logi Server Engine ignores remarked elements and they are not rendered into the HTML page output.

To remark an element:

  1. Select the element to remark from the definition file.
  2. Right-click it and choose Remark from the pop-up menu.

Because elements are structured in a hierarchical tree, if a parent element is remarked, all of its child elements in the tree are also remarked.

 

Writing Application Notes

It's often useful to write detailed notes about topics that affect the entire application, such as database modifications or session variable names, and the Note element isn't useful for this purpose. Instead there's an Application Notepad for each Logi Studio application. To access it, select to the Application tab in the Workspace panel.
 

To write Application Notes:

  1. Click Edit Notes to begin writing the application notes.
  2. Type the notes in the provided textbox.
  3. Click Save Notes to commit the changes.
     

The following formatting options are available when writing application notes:

  • Bold
  • Italic
  • Underline
  • Bulleted List
  • Numbered List
  • Decrease Indent
  • Increase Indent
  • Insert Link

The Application Notes are stored in a separate .xml data file in the _Definitions folder under your application folder.

Back to top

 

Using the Test Parameters Panel

One of Studio's least well-known panels is the Test Parameters panel. Studio makes this panel visible when the current definition expects to receive and use parameters. It provides a way for developers to supply request variable values for their definitions when previewing them in Studio, and it makes experimenting with different values very easy.

The example above shows this panel in use. Studio will automatically populate the left column with the tokens for any request variables expected by the currently selected definition in the Workspace. You can enter values for those tokens, and they'll be fed to the definition when you Preview it in the Workspace panel, or right-click it in the Application panel and select "Run in Browser".

 The token values in Test Parameters are not fed to the application when you click the Run Application menu item or press the F5 key.

Back to top

Using the Debugging Features

Logi Studio provides debugging features for an application, but they have to be enabled to work. They are not enabled by default.
 

You can turn on debugging for all your report pages by clicking the Debug menu item, shown above, in Studio's main menu in the Home tab and selecting Debugger Link from the options.


Selecting a debugger option in the toolbar sets an attribute value in the General element, in the _Settings definition, as shown above. This value can also be set manually.

 

Now, when run, each report page will include a debugger icon that "floats" in the lower right-hand corner of the browser window, as shown above. Click this link to display the Debugger Trace Report (discussed below). Any charts on the page will have their own separate debugger links. You can right-click the icon to open the debug page, open it in a new tab (if displayed in a browser), or in a new window, etc.

Each chart will have its own debug icon or link, as well, and a separate debug trace page.

The other debugging modes include:

  • Debugger Link No Data - Produces the same report as Debugger Link, but does not include links to, nor cache, the XML data retrieved. For more discussion of this option, see below.
  • Error Details - Appends detailed error at the bottom of a page only when an error occurs.
  • No Details - Prevents any debugger information from appearing when there's an error, so the user cannot see sensitive system security information. Use this option for system deployment.
  • Redirect - Redirects the browser when an error occurs to a custom error page, at the URL you must specify in the Redirect Error URL attribute.

The default value is No Details.

For information about logging the debugger outpout, see the Logging Errors section.
 

Using Debugger Link No Data

Why is Debugger Link No Data useful? When you debug using the standard Debugger Link setting, debug data files are generated for all of the datalayer elements inside your report. Creating these files requires a significant amount of processing overhead and your reports will run slower. How much slower depends on how much data there is, but expect ~2x slower for each datalayer element.

However, if you wish to debug for performance reasons and want to inspect the timings of different events, you can use the Debugger Link No Data setting, which creates no debug data files and incurs no processing overhead, to produce a more accurate execution time profile.
 

Turning on Debugging with Session Variables

You can also turn on debugging for all users by setting Session variables. To do this, use the Set Session Variables element, and set these two variables:

rdDebugSession="True"
rdDebuggerStyle="DebuggerLinks" (can be any of the debugging modes listed earlier)

Debugging will be turned on for the duration of a user's session. Because the Set Session Variables element has a Condition attribute, you can make debugging dynamic, for example, by adding a parameter and value to the query string used to call a report, then evaluating its @Request token in the Condition attribute:
 

Enabling Debugging with Security Rights

You may wish to enable debugging just for specific users, without enabling it for all users. To do this:

  1. Logi Security must be enabled, and users must have security rights assigned to them.
  2. In the _Settings definition's General element, specify the appropriate security rights as a comma-separated list in the Debugger Security Right ID attribute value.
  3. Set the General element's Debugger Style to No Details or leave it blank to ensure debugging is not enabled for all users.
  4. Run the application, and pass rdDebugSession=True to the page in the query string.

Debugging will remain enabled for users with the specified security rights for the duration of their session.
 

<Label Caption="Enable Debugging" SecurityRightID="Admin">
   <Action Type="Report">
      <Target Type="Report" />
      <LinkParams rdDebugSession="True" />
   </Action>
</Label>

The example code shown above will create a link that will be visible only to users with the "Admin" security right ID and, when clicked, will enable debugging for them (assuming Debugger Security Right ID has also been configured with that security right ID).  

The Debugger Trace Report

When the Debugger Style has been set to Debugger Link or Debugger Link No Data, the Debugger Trace Report can be accessed in two ways: using the Debug icon or link discussed earlier, or from a link that appears on a runtime error page. The trace report appears either in the Preview panel or in your browser, depending on which method you were using to view your report.
 

As shown above, the Debugger Trace Report, includes step-by-step events, values, and time stamps for the report run. Tracing application execution is very useful for troubleshooting, especially for data retrieval issues. Here are some of the items you'll find in the trace report:

  1. Valuable information about Logi Info, the system environment, and the requesting browser.
     
  2. The Request Tokens for query string variables being passed to the report, which can be helpful in determining what is being passed from other reports, including from user input.
     
  3. Local Data datalayer activity, such as a SQL query issued to a database, is shown. This is especially useful if a query includes tokens being resolved at runtime. SQL queries shown here can be copied and pasted into Studio's Query Builder or other tools in order to run and test them independently. Data retrieval and manipulation is optimized under one or more "data operation plans" to reduce data cache reads and writes. Plan information appears in this section of the debug report.
     
  4. Other datalayer activity, including complex SQL queries with resolved tokens, can be also be viewed.
     
  5. If the Debugging Style selected was Debugger Link, then after retrieval and subsequent processing with condition filters, joins, calculated columns, grouping, etc., the data in the datalayer can be viewed, either as a neatly-formatted table or as the stored raw XML.
     
  6. The Time column, with its integrated chart, provides valuable performance information for each step. This allows you to pinpoint which operations are taking the most time.
     
  7. This link at the bottom of the page will package and compress the debug report into a single .zip file, should you need to provide it to Logi Tech Support for diagnosis.

     

  8.  

  9. If you're working with a Logi Java application, the Trace Report will also include a special section near the top that presents information about your Java configuration.

The debug report also contains more than the information highlighted here, so examine it carefully.

 

In addition, if an error has occurred, a Detailed Error Report, shown above, including the stack trace will also appear, often with a more detailed error message to aid in debugging.
 

Debugging Scripts

You can also cause debugging to extend to scripts:
 

To enable this, configure the General element's Script Source Debugger Style attribute. Its None value is the default, or you can set it to OnError, in which case the View Script File link shown above appears in the Debugger Trace Report when an error occurs. This link displays the script as generated when the report was run. If the script is a simple, single line of script, the actual error may appear here instead of a link. A third value option, Always, causes the link to appear in the trace report at all times. The routine use of "Always" is discouraged as it will incur a significant performance hit.
 

Debugging Subreports

If you're working with subreports and a subreport encounters an error, the error message and debug link may appear in a very small iFrame on the parent report page, like this:
 

It's nearly impossible to view and navigate around the debugger trace report after clicking the link. What to do?

The simplest solution is to temporarily change the SubReport element's SubReport Mode attribute value to Embedded. The error message and debug trace page will then expand to the full width of the parent report. Change it back to its original value when you're done debugging.

If, for some reason, you can't change the SubReport Mode, then you need to open the error message or the debug trace page at full-size in a new browser tab or window. Unfortunately, different browsers have different requirements for this, as follows:

Firefox: Right-click the error message and select the "This Frame" and then "Open Frame in a New Tab" or "Open Frame in a New Window" option.

Chrome: Chrome removed its "Open Frame in a New Tab" option some years ago, but you can re-enable it with the free Open Frame extension from the Chrome Store. Once it's installed, right-click the error message and select the "Open frame" and then "Open frame in new tab" or "Open frame in new window" option. If you don't want to install the extension, follow the instructions below for IE11.

Microsoft IE11: Right-click the "Click here for more detailed information" link and select "Inspect element". The Developer Tools panel will open with the error message source code in it. Scroll up in it to the tag that begins with <body rddbugurl= and double-click the long value that starts with rdDownload/ to select it. Right-click the selected value and click "Copy". Manually open a new browser tab and type in the URL for your Logi application, stopping just before rdPage.aspx. Paste the copied long value in after the slash and press Enter.

Microsoft Edge: Use the same instructions as above for IE11. When you right-click the "Click here for more..." link, you will see options to open a new tab or window but they won't do anything, so carry on with the "Inspect element" option and other instructions above.
 

Back to top

Using the Element Seeker

Logi Studio includes a feature, the Element Seeker, that lets you quickly locate an element in a definition file by selecting it in your preview or browser window. To use it, you must be working in Logi Studio v12.2 SP5+ and the Logi Server Engine version of your Logi application also has to be v12.2 SP5+. In addition, if you're using the Internet Explorer browser, you must be using IE 9 or later. Here's how it works:
 

Enable the Element Seeker in Studio's Debug menu, as shown above. When you preview or browse a report page, you'll see the Seeker icon in the lower right-hand corner.
 

When you click the Seeker icon, it will turn green and enter selection mode. As you move your mouse cursor around the page, different regions will be framed in green, as shown above. Click a framed region...
 

... and Logi Studio will open the correct report definition and select the element responsible for the chosen region, as shown above.

To turn off the Seeker's selection mode, you'll need to refresh your preview or browser page.

Back to top

Logging Errors

If errors are intermittent or difficult to reproduce, then logging the errors may be a good strategy for observing them.
 

Error logging with full details is enabled in the application's _Settings definition, as shown above, by setting the General element's debugging and logging attributes. Note the forward- and backward-slashes that differentiate a file path and a URL.

If the Error Log Location attribute value is left blank, the Debugger Trace Report will be written to the <application folder>\rdErrorLog folder, which will be created automatically.

If you only wish to log limited information, you can set the Debugger Style attribute to ErrorDetail or NoDetail. The log pages will then only include the level of detail provided by the corresponding error messages.

You can also redirect the error logging to a folder of your choice by providing an Error Log Location attribute value. This must be a fully-qualified folder path and you need to manually create the named folder if it does not already exist. Tokens can be used here as part of the path, such as:

    @Function.AppPhysicalPath~\yourErrorLogFolder

Keep in mind that the account, which may be an application pool, used to run web applications requires full File Access rights to the target folder. If the folder does not exist, then the application folder must have these rights so that the target folder, when created, inherits them.

To use a custom location in a web farm environment, specify a network folder and change the application's identity to a network account.

Back to top

 

Debugging Discovery v3.0

The services that support Discovery v3.0, Logi Application Service and Logi Data Service, have their own logs which can be useful for debugging. Assuming a default installation location, the logs are located in:

    C:\LogiAnalytics\Discovery\platform\logs

There are a variety of log files but focus on the two for the services: logiApplicationService.yyyymmdd.log and logiDataService.log. The files are created using log4j and can be easily viewed with Notepad++ or many other free log viewers.

Debugging can be turned on and off in this settings file:

    C:\LogiAnalytics\Discovery\platform\settings\logiApplicationService.json

By default, all information, warning, and error messages are logged:

{
  "disableSchemaValidation": false,
  "logiApplicationService": {
    "description": "Platform logiApplicationService Configuration",
    "logLevel": "debug",
    "corsOriginWhiteList": "*",
    "accessTokenGracePeriod": 120,
    "system": {
      "pollingIntervalSeconds": 15,
      "pollingTimeoutMinutes": -1
    },

In the file, change the "logLevel" value from "error" to "debug", as shown above, to enable debug logging. You'll need to stop and restart the two services after editing the settings file.
 

Status 201 [DEBUG] - 2018-01-11T08:07:05-0500 - Response Received (521bbef0-f6d0-11e7-86ba-97facc95ecaa)

An example log debug entry is shown above.