Last September, I wrote about accessing Sitecore Logs from Azure PaaS instances using the (now deprecated) AzureAILogs.html file provided by Sitecore. The knowledgebase article was updated in mid-January , 2019 – and the AzureAILogs.html file had been replaced with a new /sitecore/admin page dubbed AzureTools.aspx.
This updated admin page contains all the same functionality found in the AzureAILogs.html, with the addition of being able to pull log traces and requests from Application Insights.
Installation is easy: download the AzureTools.zip files, drop in the /sitecore/admin/AzureAILogs.aspx into the you’re your site’s root.
Admittedly, this admin page is great - but I could also see several aspects SPE being particularly useful (like the OOB SPE ListView - which would easily allow us to filter/sort/search through a series of log entries). An additional option to see raw color-coded logs would also be cool. 😊
Using the existing AzureTools.aspx as a general guide, we can re-create the GUI with general ease.
We’ll need:
1) Option to get Requests or Logs
2) Option to selected a Role (values pulled from API)
3) Option to control recency.
4) Option to control the severity.
The end result will consume the Application Insights REST API endpoints and allow a user to pull logs from Application Insights inside the CMS.
To start, we'll need to make sure we can work with the API by obtaining an Application Insights App ID and a corresponding App Insights API key Sitecore's documentation already lists the.
Sitecore's documentation covers this but it's as simple as logging into Azure Portal and navigating to your Application Insights service.
Under Configure, select 'API Access':
The Application Insights App ID will be displayed the following screen:
Copy this value and store it temporarily.
Click the 'Create API Key' button.
Give it a name and check the 'Read telemetry' checkbox.
After clicking 'Generate key', you'll have one opportunity to copy the 'App Insights API key'. Copy and store this value temporarily.
Before building our UI in SPE, we'll need to confirm API communication by obtaining the server roles from Application Insights. We can set a variable to call a function that will grab an ArrayList of roles:
Our function will build the URL, include the property URL authorization header containing the API key, and return an array list.
The dialog should contain a series of radio buttons and checkbox lists, all of which will be used to provide options to build out another API call to obtain the traces or requests from AppInsights.
The output displays as follows:
Notice line 51 in the above snippet calls a Get-LogsOrRequests function which accepts a series of parameters from the dialog options upon selecting the OK button.
This function builds out the proper API URL and query parameters based on the passed the selected values passed in. Invoke-WebRequest is used to make the call to the API, which will return a JSON object of log entries from AppInsights based on those parameters.
Line 119 contains a final call to a function called 'Set-PostDialog' which provides options for displaying the results.
The output here is a ModalDialog with three buttons:
Selecting 'Script View' will display the results of the API in a color-coded Show-Result window:
Selecting 'List View' will process the results to an acceptable format for a standard SPE ListView result window (filtering, exporting, etc is obviously all included here):
Finally, selecting the 'Download' button will download a .txt file of the contents retrieved from the API.
The script will be available to run from the PowerShell Toolbox in the Start Menu.
This updated admin page contains all the same functionality found in the AzureAILogs.html, with the addition of being able to pull log traces and requests from Application Insights.
Installation is easy: download the AzureTools.zip files, drop in the /sitecore/admin/AzureAILogs.aspx into the you’re your site’s root.
Admittedly, this admin page is great - but I could also see several aspects SPE being particularly useful (like the OOB SPE ListView - which would easily allow us to filter/sort/search through a series of log entries). An additional option to see raw color-coded logs would also be cool. 😊
Using the existing AzureTools.aspx as a general guide, we can re-create the GUI with general ease.
We’ll need:
1) Option to get Requests or Logs
2) Option to selected a Role (values pulled from API)
3) Option to control recency.
4) Option to control the severity.
The end result will consume the Application Insights REST API endpoints and allow a user to pull logs from Application Insights inside the CMS.
API Access
Sitecore's documentation covers this but it's as simple as logging into Azure Portal and navigating to your Application Insights service.
Under Configure, select 'API Access':
The Application Insights App ID will be displayed the following screen:
Copy this value and store it temporarily.
Click the 'Create API Key' button.
Give it a name and check the 'Read telemetry' checkbox.
After clicking 'Generate key', you'll have one opportunity to copy the 'App Insights API key'. Copy and store this value temporarily.
Initial Communication with the API
Our script will utilize the two values to interact with the API.Before building our UI in SPE, we'll need to confirm API communication by obtaining the server roles from Application Insights. We can set a variable to call a function that will grab an ArrayList of roles:
Our function will build the URL, include the property URL authorization header containing the API key, and return an array list.
User Interface
Now that we have confirmed communication to the API and obtained our list of roles, we can pass the variable into a new function that will be responsible for building and displaying the UI:The dialog should contain a series of radio buttons and checkbox lists, all of which will be used to provide options to build out another API call to obtain the traces or requests from AppInsights.
The output displays as follows:
Notice line 51 in the above snippet calls a Get-LogsOrRequests function which accepts a series of parameters from the dialog options upon selecting the OK button.
This function builds out the proper API URL and query parameters based on the passed the selected values passed in. Invoke-WebRequest is used to make the call to the API, which will return a JSON object of log entries from AppInsights based on those parameters.
Line 119 contains a final call to a function called 'Set-PostDialog' which provides options for displaying the results.
The output here is a ModalDialog with three buttons:
Selecting 'Script View' will display the results of the API in a color-coded Show-Result window:
Selecting 'List View' will process the results to an acceptable format for a standard SPE ListView result window (filtering, exporting, etc is obviously all included here):
Finally, selecting the 'Download' button will download a .txt file of the contents retrieved from the API.
Final Script
Installation
Manual
- Create a new Sitecore item based on the SPE PowerShell Script template and copy the final script above into the Script Body field.
- Replace the default "XXXXXXXXXXXXXXXXXXXXXXXXX" placeholder values in the $aiAppID and $apiKey variables with your own.
Sitecore Package
- Download the Sitecore package and install from GitHub.
- Navigate to the PowerShell script located here:
/sitecore/system/Modules/PowerShell/Script Library/Azure Application Insights Logs/Toolbox/Azure Application Insights Logs - Replace the default "XXXXXXXXXXXXXXXXXXXXXXXXX" placeholder values in the $aiAppID and $apiKey variables with your own.
Source Code
The full script can also be found on GitHub.
Feel free to grab a copy and modify it how you see fit.
Feel free to grab a copy and modify it how you see fit.
