I wanted to take the time to introduce some general troubleshooting techniques that I often find myself using when debugging PI Web API code.
Developer Tools in Browsers
Whether in Chrome, Edge, Firefox, or Internet Explorer most modern browsers have a developer tools pane to allow you as a programmer to take a closer look at the requests and response being sent over the network. If you find your web application is not getting the expected data or a request is failing it can be beneficial to open developer tools (by pressing F12 on your keyboard) navigating to the network tab and locating your request.
In some cases, as with Cross-Site Forgery Request and Cross-Origin Requests that fail, there will be errors in the console that can assist in leading you to the underlying issue.
Frequently I find isolating out a single request and using an HTTP Client like Fiddler or Postman one of the best ways to determine the root cause of an issue. Whether that be the data being returned in a different format than expected, the data failing to return at all, or a malformed request.
I highly recommend isolating issues down to single requests whenever possible.
These tools are also very useful when building out Batch requests as you can incrementally build up the POST body and reference sample previous responses when attempting to make parent-child requests.
DebugMode Configuration Attribute
In order to reduce surface vectors for attackers, the PI Web API implemented a configuration parameter to obfuscate error messages. From time to time you may see “An exception has occurred. Please contact your PI Web API administrator for help in enabling debug mode.” when making requests.
In order to see the error message behind the request you must set the “DebugMode” AF Attribute in the configuration database to a Boolean value of “True.” After doing so and allowing the PI Web API’s configuration to refresh, performing the same request will now show the underlying error message in the HTTP response body.
PI Web API Windows Event Viewer Debug Logs
The PI Web API is capable of logging all requests and responses in the Windows Event Viewer Log. In order to view this log, you’ll need to open Windows event Viewer on the machine running the PI Web API. Expand “Applications and Services Logs” and then expand “PI Web API.” If you don’t see the debug log as in the screenshot below:
You will need to explicitly request the Windows Event Viewer show you the log. This can be done by opening up “View” in the upper left, then selecting “Show Analytic and Debug Logs”
Once you’ve done this you should now see the Debug Log for the PI Web API available in the Event Viewer
In order to start logging, the log needs to be enabled. To do this right-click “Debug” and “Enable Log”
All requests and Responses are logged in the debug log. You can identify which Request and Response are associated with one another by matching the GUID provided in each message. For example the two messages below a request-response pair, and we know this because of the matching GUIDs.
By Default, the PI Web API Debug log will not overwrite old messages, so once it is full it will no longer continue logging. In order to clear the PI Web API Debug log and start fresh, you’ll need to right-click the Debug log and select “Disable Log”
The right-click Debug and “Enable Log”
This will cause all the events in the Debug log to be erased and you’ll likely see the following prompt to confirm you want to clear the log.
If you need to save the logs for longer term use, there is an option to save the Log file on the right-hand side of the Event Viewer.
If you need to increase the amount of time the Debug log is going to log, you can right-click debug and select properties.
From this new window, you have the option to increase the log size so that you can capture more events.