How to use Custom Labels

Some of the most commonly used tiles in dashboards and perspectives display information from SCOM objects. These tiles work extremely well most of the time, but in some cases you need to customize the labels before you can understand which SCOM object you are looking at.

If you're just looking for some quick samples, jump straight to them: Sample custom labels

For example, below is a Status tile configured to show all disks on a group of servers:

Without drilling down it's difficult to know which disk belongs to which server.

Custom labeling allows us to specify exactly how we want objects to be displayed (using both static text and dynamic properties from the object) to ensure that the tile always makes sense.

You may also like to take a look at the Dashboard Server webinar 'Custom Labeling':

Supported tiles

Tiles that support custom labels come preconfigured with some useful labels and, in the case of Performance tiles, will even attempt to automatically select the most useful label based on the selected object and metric. You can however choose the custom option which will allow you to precisely control the label.

The following tiles support changing the labels of SCOM objects:

• Status
• Performance (Bar, Line graph, Sparklines)
• Matrix
• Image
• SLA
• SQL (Grid)
• Data On-Demand Task (Grid)
• Web API (Grid)
• Azure Log Analytics(Grid)
• App Insights (Grid)

You can configure a custom label by configuring the label panel when creating or editing a supported tile.

Mustache Parameters

Custom labels can use Mustache parameters (mustache syntax) to insert properties. If you're familiar with mustache, you can specify advanced labels that can transform properties prior to displaying them (such as showing only a portion of text, converting a number or reformatting a date).

What is a mustache parameter?

A mustache parameter is a dynamic value, the actual value will be inserted from the properties of the object(s) in scope.

This data stream supplies scoped objects individually for mustache parameters. When there are multiple objects in scope this plugin will send the query multiple times, once for each object. The results are then displayed together, for example in a single table.

You can use properties of objects and write them in between curly braces e.g {{name}} to use them as mustache parameters. Whenever you use mustache parameters, you need to use a scope of objects that contain the property you're referencing.

For example, if objects of type "host" have a property called name, you can use {{name}}. This will resolve {{name}} to the value of the name property of the different "host" objects used in the scope.

Check out our GitHub Samples repository for samples around using mustache. You'll find snippets for custom labels, conversions, manipulating strings, using HTML, and many more use cases.

For example you can use the javascript split method to separate properties into substrings to make the result more readable.

Below are some examples of using both a predefined and custom label.

Display logical disks using a predefined format

One way to quickly fix the issue we saw at the start of this article is to use a predefined label that uses a name (path) format.

1. Create a Status tile.
2. On the scope panel select advanced and enter Logical Disk (Server) as the class.
3. Click next until you are on the label panel.
4. Click on name (path).
5. Click on done.

We can now see exactly which server each disk is associated with.

Display logical disks with a custom label

In some layouts you may wish to simplify the labeling further, by removing the FQDN for example, and this is where using a custom label can be useful.

Using the custom option we can create our own advanced label that only uses the hostname. Custom labels use Mustache syntax to insert values from the SCOM object.

If you're familiar with mustache, you can specify advanced labels that can transform properties prior to displaying them (such as showing only a portion of text, converting a number or reformatting a date).

The mustache helper

When specifying a mustache for a custom label, clicking the {{}} button or typing {{ brings up a helpful picker which shows all the properties of your selected resources, along with sample values.

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 label and complete the mustache.

Property names are case-sensitive and should be written as they appear in the mustache helper (e.g. displayName not DisplayName).

Note about using properties with hyphens from external APIs (for Web API, Elasticsearch, and Splunk tile)

Property names that contain hyphens (for example properties.name-with-hyphens) can't be processed due to a JavaScript limitation. If you want to use a property that contains a hyphen, you have two options:

1. If you have access to the data source and can change the name of the property, change the name of the property to a name without hyphens.

   For example, if your Elasticsearch query uses a property (an aggregation, a grouping or any other property you want to use) with a name that contains a hyphen, you can either access your Elasticsearch instance and change the name there or you can overwrite the name in the query dsl field.

2. If you can't change the name of the property, you need to enter the property name in the following format:

   Original property name:
   {{properties.name-with-hyphens.value}}

   New format:
   {{properties['name-with-hyphens'].value}}

Procedure

1. Create a Status tile.
2. On the scope panel select advanced and enter Logical Disk (Server) as the class.
3. Open the label panel.
4. Click on custom.
5. Enter {{displayName}} ({{ path.split('.')[0] }}) for the label template.
6. Click on done.

The mustache here uses the javascript split method to separate the FQDN into substrings at each ., and then accesses the first result (the hostname) using [0]

Display CPU usage for servers with a custom label

Performance tiles expose slightly different values for use in custom labels, as they access performance metrics rather than SCOM objects. This can be helpful if you want to include the timestamp or most recent value in the label.

In order to display just the hostname for a windows server metric, we'll need to use either key.managedEntityPath or key.managedEntityName depending on whether the metric is available directly on the server or is hosted on a child class (such as Operating System).

Procedure

1. Create a Performance (Sparklines) tile.
2. On the scope panel select group and specify All Windows Computers. Click next.
3. On the metric panel type Processor and select Processor Information - % Processor Time.
4. Open the label panel.

5. Click custom and enter {{ key.managedEntityPath.toUpperCase().split('.')[0] }} for the label template.
   

6. Click done.

This will now display all servers as hostnames only, with all servers consistently showing as upper case.

Sample custom labels

Below are some sample mustaches you can use in custom labels. The table may wrap longer examples, but all mustaches below are a single line.

Status, Image, and SLA tiles

Display an object's health state, last change, and health state summary

{{healthState}} for {{timeago(stateLastModified, null, false, true)}}
{{model.alerts.0.name}}

Display a logical disk as "Drive Letter (Host Server)"

{{displayName}} ({{path.split('.')[0]}})

Display a SQL database as "Instance Name \ Database Name"

{{properties.instanceName}}\\{{displayName}}

Display an IIS application pool as "Pool Name (Pool Identity)"

{{displayName}} (running as {{properties.applicationPoolIdentity}})

Display a Windows computer's "[Location] Host Name" using a Regular Expression on its IP address

{{#if /10\.0\.(\d{1,3}.?){2}/.test(properties.ipAddress) }} [Azure] {{else}} [Marlow] {{/if}} {{properties.netbiosComputerName}}

Display a Windows computer's last state change using the timeago function (jump to Using Timeago to convert Unix timestamps).

{{timeago(stateLastModified, true)}}

Performance tiles

Display a network adapter by its instance name i.e. "Realtek PCIe GBE"

{{key.instance}}

Display a server name in upper case

{{key.managedEntityPath.toUpperCase().split('.')[0]}}

Using Timeago to convert Unix timestamps

You can use timeago to convert Unix timestamps from milliseconds to show a readable date and time. You can either display an absolute time (for example, August 20th 2021) or a relative time (for example, 20 hours ago).

There are four parameters you can use for converting the time, written in the following format: 
timeago(Value you want to convert, Show Absolute, Show Time, Without Suffix, With Prefix).

The parameters for the value you want to convert can either be true or false:

Tip: The default setting for all parameters is false. If you only want to change the first parameters, you can just use timeago(value, true, true) and it will be interpreted as timeago(value, true, true, false, false).

Examples:

To display the relative time (how long ago something occurred):

{{timeago(value)}}

To display the absolute time as the date without the time:

{{timeago(value, true)}}

To display the absolute time as the date with the time:

{{timeago(value, true, true)}}

To display the time with the prefix "for" for relative time and "since" for absolute time (for example, "the status has been unhealthy for 10 hours")

Option A) Use the fourth parameter and set it to true. This will insert the appropriate prefix for the absolute or relative time:

timeago(value, false, false, true, true)

Option B) You can leave out the fourth parameter that controls if the prefix "for" or "since" is inserted automatically. Since you left it out, it defaults to false, causing no prefix to be shown. Instead you insert the word "for" or "since" manually before the timeago function.

for timeago(value, false, false, true)

To convert a time value from seconds to milliseconds:

Some APIs, like Pingdom for example, return the value in seconds. Since Timeago uses the time value in milliseconds, you need to multiply by 1000 in that case:

{{timeago(value*1000)}}

Example with a Pingdom property:

{{timeago(properties.lasttesttime*1000)}}