Building on the previous installments of this custom agent series, Quest Principal Solutions Architect Brian Wheeldon steps through the process of adding multiple aspects of a metric to a WCF table and defining a multi-line header, pointing out best practices along the way.
Requirements
After defining a custom metric and configuring a chart to display the metric, we'd like add this metric to the custom table we defined in episode two. We'd like to be able to visualize several aspects of this metric, including the current value, period average and trend. The table should present these distinct metric as a logical group. These columns should be sortable so that the highest network latencies appear at the top of the table.
Table Metric Design
We defined a WCF table to display the host, port and message returned by our custom agent in episode two of this series.
Now that we have a metric to measure the network latency between the source and the target port, we'd like to display that metric in the table.
We'd like to expose several aspects of this table so that it's easy to determine at a glance which connections are consistently slow or intermittently slow. To do this, we'll display three different aspects of this metric: the trend, current value, and period average. We'll also like to be able to see the worst case network latency for this metric, but this aspect should be hidden by default to avoid cluttering the display.
For a briefing about these different aspects of a metric, see Understanding Foglight Metrics.
We'll define column groupings so that these metric values appear in a logical group.
Configure a metric in a WCF Table
Although these steps directly build on our custom agent example, the same principle can be applied to adding any metric to any WCF table.
As a user with the "Dashboard Designer" role, open the Configuration group under Dashboards and select Definitions.
Select the working module in the top left window. In this tutorial, we'll build on the custom port monitor agent dashboards in the "TCPcheck" module.
Select the target table: "TCP Check Table" in the bottom left pane so that the summary of this table appears in the main working area. Click Edit.
Select the Configuration tab.
Add a "Trend" (sparkline) column
In this section, we'll configure a column to visualize the trend of the metric using a sparkline. A sparkline is a "data-intense, design-simple, word-sized graphic" invented by data visualization pioneer Edward Tufte.
We'll also define the separate metric aspect that will be used when this column is sorted.his column.
Open Columns
Click the "+" button at the bottom of the Column list
Click the edit button in the Value row. Select Context.
Click the drop down beside Input Key. Select the item representing the object for this row: currentRow (tcp_check_Agent_Table_TCP_CHECK)
The aspect we want is the average value of the metric over the selected time range shown in the current page.
Click in the drop down beside Path. Open the target metric: responseTime. Open Period. Select Average - Double
The Path field will populate with "responseTime/period/average". Click Set.
The table will use this aspect of the metric to sort the table.
Next configure a sparkline visualization to represent the trend of this metric.
Click the edit button in the Render Value row. Select Context.
Click the drop down beside Input Key. Select the item representing the object for this row: currentRow (tcp_check_Agent_Table_TCP_CHECK)
Click in the drop down beside Path. Select the target metric: responseTime - Metric
Click the edit button beside Renderer.
In the Select a Renderer dialog, Open Management Server. Open System. Select "Time Plot Renderer". Click Save.
Click Set.
Next, we will identify this column:
Click the edit button beside ID. Enter something like "responseTimeTrend". Click Set.
Label this column:
Click the edit button beside Header. Select Set To Binding>Localized String.
In the Edit - Header dialog, enter "Trend" in the Localized String field. Click Set.
Right-align the column:
Open Cell Alignment. Click the edit button beside Horizontal. Select Right.
Best Practice: Right align numeric columns. Left align text columns. Center align icons.
Specify the default sort direction for this column:
Click the edit button beside Current Sort Order. Select Descending.
Best Practice: Set the Default sort direction of text columns to Ascending. The Default sort direction for most metric columns and all alarm value columns should be Descending. The default sort direction of a a column should move the most interesting (largest) values to the top of the table.
All the other column values can be left to their default values. The table column you just configured should look something like:
Click the Save button at the top of the page to save "TCP Check Table".
Test the table by using the the Test button at the top of the page, or by opening a new browser window/tab from the right Action Table "New window" option, and navigating to the TCPcheck/TCP Check Table dashboard. Verify the "Trend" column.
Add a "Current" value column
Return to the Definition editor and edit the table once again. Select the Configuration tab.
Click the gray "-" button to the left of the last column group to hide (not delete!) the column you just created.
Click the "+" button at the bottom of the Column list to add a new column.
Click the edit button in the Value row. Select Context.
Click the drop down beside Input Key. Select the item representing the object for this row: currentRow (tcp_check_Agent_Table_TCP_CHECK)
The aspect we want is the current value of the metric for the selected time range.
Click in the drop down beside Path. Open the target metric: responseTime. Open Current. Select Average - Double
The Path field will populate with "responseTime/current/average".
Click the edit button beside Renderer. Open Management Server. Open System. Scroll down to select "Number: 2 Decimals". Click Save.
As you can see, there are a lot of predefined options for displaying metrics.
Click Set.
This time we don't need to specify a separate Render Value. The value we just defined is suitable for both display and sorting.
Identify this column:
Click the edit button beside ID. Enter something like "responseTimeCurrent". Click Set.
Label this column:
Click ther edit button beside Header. Select Set To Binding>Localized String.
In the Edit - Header dialog, enter "Current" in the Localized String field. Click Set.
Right-align the column
Open Cell Alignment. Click the edit button beside Horizontal. Select Right.
Specify the default sort direction for this column:
Click the edit button beside Current Sort Order. Select Descending.
Add a "Period Average" value column
Click the "+" button at the bottom of the Column list to add a new column.
Click the edit button in the Value row. Select Context.
Click the drop down beside Input Key. Select the item representing the object for this row: currentRow (tcp_check_Agent_Table_TCP_CHECK)
The aspect we want is the current value of the metric for the selected time range.
Click in the drop down beside Path. Open the target metric: responseTime. Open Period. Select Average - Double
The Path field will populate with "responseTime/period/average".
Click the edit button beside Renderer. Open Management Server. Open System. Scroll down to select "Number: 2 Decimals". Click Save.
Click Set.
Identify this column:
Click the edit button beside ID. Enter something like "responseTimePeriodAverage". Click Set.
Label this column:
Click the edit button beside Header. Select Set To Binding>Localized String.
In the Edit - Header dialog, enter "Average" in the Localized String field. Click Set.
Add a tooltip to this column:
Click the edit button beside Header Tooltip. Select Set To Binding>Localized String.
In the Edit - Header dialog, enter "Period Average" in the Localized String field. Click Set
Best Practice: Keep column headings brief, but define more descriptive column header tooltips so users can learn more by resting their mouse on the column header.
Right-align the column
Open Cell Alignment. Click the edit button beside Horizontal. Select Right.
Specify the default sort direction for this column:
Click the edit button beside Current Sort Order. Select Descending.
It's time to validate your configuration again. Test your configuration using the Test button or a separate browser tab/window.
Define nested column headings
Next we want to tune the table by adding a logical grouping for these metric aspects.
Edit the TCP Check Table once again and select the Configuration tab.
Click the "-" button to the left of Columns to hide all the columns you just defined.
Open Groups. Click the "+" below Groups to add a group.
Label the group:
Click the edit button in the Header row. Select Set to Binding>Localized String.
In the Edit - Header dialog, enter "Response Time" in the Localized String field. Click Set.
Define the column IDs that belong in this group:
Open "Column/Group Order". Click "+" to add a column to this group.
Click the edit button for the first column. Enter the first column ID: "responseTimeTrend". Click Set.
Click "+" to add another column to this group.
Click the edit button for the second column. Enter the second column ID: "responseTimeCurrent". Click Set.
Click "+" to add another column to this group.
Click the edit button for the third column. Enter the third column ID: "responseTimePeriodAverage". Click Set.
Click the edit button beside ID. Enter something like "responseTimeGroup". Click Set.
Now there is a two level header for the Response Time metric columns.
Define the Column/Group Order
We'll be using the ID values configured previously for each column and group to order them.
Open "Column/Group Order".
Click "+" to specify the first column or group to display in this table.
Click the edit button for the first column. Enter the first column ID: "health". Click Set.
Click "+" to add the next column to this group.
Click the edit button for the second column. Enter the second column ID: "hostname". Click Set.
Click "+" to add the next column to this group.
Click the edit button for the third column. Enter the third column ID: "port". Click Set.
Click "+" to add the next group to this group.
Click the edit button for the forth group. Enter the group column ID: "responseTimeGroup". Click Set.
Click "+" to add the next column to this group.
Click the edit button for the fifth column. Enter the third column ID: "message". Click Set.
Best Practice: If you want the columns to appear in a different order than they are specified in the Columns group, configure the "Column/Group Order".
Save and Test the table.
Define a custom Renderer
That looks pretty good, but let's refine the way that the trend line looks.
We'll make a copy of the System renderer and customize it.
Best Practice: There are plenty of pre-defined views and renderers that you can use in your dashboard directly, but don't be afraid to make a copy of one that's close but not exactly right, then tune the copy it to make it your own. Never modify a pre-defined System view or renderer. Instead copy it to your working module and modify the copied version.
Return to the WCF Definition Editor.
With the current module "TCPcheck" selected, change the "Views" dropdown to "Renderers"
Click the "+" button beside "Renderers" to add a renderer.
Select the "Copy an Existing Renderer" tab.
Open Management Server/System. Scroll down and select "Time Plot Renderer".
The copied renderer now appears in the edit window.
Change the Name to "Sparkline".
Uncheck "Public".
Best Practice: Only views that are marked as "Public" can be used in other modules. Public views cannot be deleted, only replaced. In your custom dashboard modules, avoid setting the "Public" property unless you actually plan to use this view in other modules.
Select the Configuration tab.
Change the Height from 20 to 13.
Change Mark Current Point to true.
Open "Sparkline" at the bottom.
Change Line Thickness to "Automatic (Default)"
Save this Sparkline renderer.
Now modify the table to use the Sparkline you just defined.
Edit TCP Check Table and open the Configuration tab.
In the Columns group, open the responseTimeTrend column
Edit the Render Value field.
In the Edit - Render Value editor, click the edit button in the Renderer field.
Replace the System Renderer with the tuned Sparkline Renderer you just configured:
Open TCPcheck. Select "Sparkline". Click Save.
Click Set.
Save TCP Check Table.
Test the table. Does the trend line look better?
Exercise: Add a new column representing the worst case ping time for the metric: responseTime/period/maximum
Make sure that it's identified and grouped with the other metric visualizations, and is aligned and sorted properly.
Change the "Visibility" of this column to "false" so that it can be exposed on demand from the edit menu in the top right of the table, but is hidden by default.
Test toggling the visibility of this column by clicking on the edit icon on the top right of the dashboard table.
You now have a sophisticated tabular display of the custom agent data, including visualizations for several different aspects of the target metric and a custom sparkline Renderer.
If you have questions or comments about this article, please add them below. More general questions about building dashboards can be posted in the Custom Dashboards & Scripts Discussion forum.
Stay tuned for the next installment of this custom agent series, when we'll cover the configuration and use of agent properties in script agents.