9 minute readApplies to: v4

How to use the Logs tile

The Logs tile allows you to query Log Analytics data from Azure Monitor (both stand-alone and in the context of resources within Azure) and display that information in your SquaredUp dashboard.

Overview

SquaredUp executes the requests in the context of the logged in user viewing the dashboard. The Logs tile queries Log Analytics using the new query language (KQL).

The ability to render information as a graph is a feature of the Azure portal rather than the Log Analytics Query language itself. Graphs will only be shown if you have selected a suitable graph tile such as the Logs Line Graph or Logs Donut.

Logs Line Graph 2

Logs tile types

The Logs tile button indicates that there are more tiles available from this one button:

Logs Tile button

After selecting the Logs tile you will get the choice of tiles.

Logs (Scalar)

This will show a single value:

Logs Scalar button

Logs (Grid)

This will show a grid or table of data:

Logs Grid button

Logs Grid button

Logs (Line Graph)

Logs Line Graph button

Logs Line Graph

Logs Line Graph 2

Logs (Donut)

Logs Donut button

Logs Donut graph

Logs tile options

Scope

The scope is optional, and allows you to select Azure resources to inject into the query.

For more information see How to scope tiles

Timeframe

If your query doesn't specify a timeframe then you can set it using the tile timeframe.

Take care when extending the timeframe beyond 7 days, as this may pull many thousands of entries and significantly impact browser performance.

If you are planning on changing the page timeframe beyond 7 days then it may be worth switching to the specific timeframe option within the tile configuration instead.

It is also possible to specify a timeframe in the query (e.g. where timestamp >= ago(2h)), however events must satisfy both the timeframe specified in the tile and in the where clause.

You may like to consider using the page timeframe, and adding a "clamping" timeframe in the query (such as where timestamp >= ago(7d)). When the page timeframe is less than 7 days it will be used, but once the page timeframe exceeds 7 days the query will enforce the max time.

For more information see How to use Timeframe option.

Workspace

This is your Log Analytics workspace. For more information see Create a Log Analytics workspace in the Azure portal.

It is not possible to query multiple workspaces on a single tile, because the Azure API in use does not support cross-resource queries.

Query

The Logs tile uses the Log Analytics query language KQL (Kusto), which is very rich and offers features such as sorting, projection and calculated values, which you can use to control the display of data in your dashboard.

Next to the query box is the view in portal button, which opens the Azure portal in a new tab, in the specified workspace.

View In Portal

From here you can test any query to be sure it returns the results expected, and then copy the query ready to paste into the Logs tile query box. There are also many sample queries in this area of the portal for you to work with or copy back into the Logs tile.

For more information see Microsoft Azure Monitor log queries article, as this provides links to other resources for learning how to write queries.

Queries in SquaredUp can also include Mustache syntax to create a dynamic query that will change depending on the object being viewed. After typing {{ the mustache helper will appear, see below. This is particularly useful on perspectives where you can insert the resource name or resource group members as a variable using mustache syntax.

The mustache helper

When specifying a mustache clicking the {{}} button or typing {{ brings up a helpful picker which shows the name of the targeted resource, and a suggested mustache for creating a dynamic list of names which is useful if the tile is scoped to more than one object (such as a list, resource group, subscription or specific resource type).

Once the mustache helper is displayed, the list of properties will automatically filter based on what you type, allowing you to quickly find a property using a partial name or likely term. Clicking an item in the list will automatically insert that property into your query and complete the mustache.

For example, on a Perspective you can insert the computer name from the scope:

Perf
| where Computer startswith "{{scope[0].name}}"
| where CounterName == @"% Processor Time"
| summarize avg(CounterValue) by Computer, bin(TimeGenerated, 5m)

Property names are case-sensitive and should be written as they appear in the mustache helper (e.g. {{resourceGroup}} not {{ResourceGroup}}).

The Azure API in use does not support cross-resource queries.

Column overrides

For the donut and line graph tiles there is a column overrides option following the query box. This important option allows you to choose how the data returned is grouped and displayed.

For example, if your results have more than one numeric column, SquaredUp won't know which one to use as the line graph Y axis, so you select the one you want here.

ColumnOverrides

Data range

The Data Range option allows you to choose the range of the y-axis for the line graph. The min and max will be set, depending on the option selected.

percentage shows 0 to 100

fit to data shows the data minimum to data maximum

fit to data (from zero) shows from 0 to the data maximum

custom allows you to specify the min and max

custom fit - allows you to specify the min and max, however if data falls within the specified ranges the y axis range will fit to data.

Display

For the line graph a height slider allows you stretch or shrink the graph height.

For the donut the size mode allows you to change from the default to a fill mode where the donut will fit the space available.

show legend allows you to display a key to the colours on the donut, and the legend size slider will change the size of the legend text.

color palette gives you a choice of several colour selections suited towards different data sets such as priorities and health.

Label

For the line graph the show legend option will display a key to the coloured graph lines, and allow you to change from the automatic label to specify your own custom label format.

Custom labelling

Using the custom option you can create your own advanced label to specify exactly how you want the results to be displayed (using both static text and dynamic properties) to ensure that the results always make sense.

See How to use Custom labelling

Scalar

You can change the font size of the figure shown, and add text to show the unit after the figure, for example GB or virtual machines.

Grid columns

As a best practise, once you know which columns you want to display, modify the Log Analytics query to only return those columns (via project or project away), as it will improve performance when loading and displaying the tile. You can also hide individual columns by clicking the hide link next to the column name.

You can also customise the appearance of columns by clicking the edit link next to it's name in the grid columns panel and then specifying a custom template. One of the most used customisation is to set the TimeGenerated column template to {{timeago(value)}} to show a friendly time in the form Last x minutes rather than the specific time. For more information see How to use the Grid designer when configuring tiles.

Grid options

The grid options section allows you to create hyperlinks from rows of data when using the grid tile. You can also create dynamic URLs using the data returned. For example, you could paste in your Azure portal URL and append {{ResourceId}} to create a dynamic URL: https://portal.azure.com/#@squaredup.net/resource/{{ResourceId}}

Walkthrough: Configuring a Logs tile to query data

It's useful to use the Azure portal to prepare and test your queries first, see the links at the bottom of this article for further information. For this walkthrough, you are going to query Software Update status summary information.

The provided sample below assumes you have the Update Management solution enabled for your workspace.

  1. In SquaredUp browse to the dashboard you wish to add the Logs tile to.
  2. Click on the orange + button to add a new tile, then click on Logs > Logs (Grid)

    Logs Tile button

    Logs Grid button

  3. The scope is optional, and allows you to select Azure resources to inject into the query. For this walkthrough you can leave the scope empty.

    For more information see How to scope tiles

  4. Leave the timeframe as use page timeframe.
  5. In the workspace section select a Log Analytics workspace from the drop down list.
  6. On the Query panel, enter the following Log Analytics Query:

    UpdateSummary
    | summarize max(TimeGenerated) by Computer
    | project Computer, TimeGenerated = max_TimeGenerated
    | join (
    	UpdateSummary
    	| where TotalUpdatesMissing > 0 or RestartPending == true
    )
    on Computer, TimeGenerated
    | project-away Computer1, TimeGenerated1
    | order by TimeGenerated desc
  7. The grid columns section allows you to hide and edit columns. For this walkthrough hide some columns you don't need to see by clicking the hide link next to them.
  8. You can now customise the TimeGenerated column by clicking the edit link next to it's name in the grid columns panel. In the custom template box paste in {{timeago(value)}} to show a friendly time in the form Last x minutes. For more information see How to use the Grid designer when configuring tiles.
  9. Leave the grid options section as it is for this walkthrough.
  10. Click done.

Troubleshooting

"The API returned a 400 response" with message "Failed to resolve entity 'xxxxx'

Typically this indicates that a solution is missing from the queried workspace, resulting in it not containing the requested table (such as Update or UpdateSummary missing from workspaces without the Software Management solution enabled).

Azure Log Analytics Query Language

Getting started with queries

How to use the Grid designer when configuring tiles

How to use Custom labelling

Squared Up Ltd. (c) 2020Report an issue with this article