In the previous installment of this series, Quest Principal Solutions Architect Brian Wheeldon created a custom script agent to push data into Foglight and trigger an alert. In this continuation, he steps through the process of building a WCF dashboard to view the agent data highlighting best practices along the way.
Requirements
After deploying and activating a script agent and configuring a rule to trigger an alert if the agent indicates a problem, we have basic monitoring in place. But in addition to getting alerts when something breaks we'd also like to be able to easily validate that the monitored TCP ports are healthy. The data is visible in the Foglight model, but it's not in a convenient place to inspect, or presented in a useful way for Foglight operators.
We can get a pretty good result by configuring a drag and drop dashboard:
But this dashboard is static and we'd ideally like to see a dashboard that automatically populates when new TCP Check agents are deployed and activated. We'd also like to have fine-grained control of flow actions like pop ups and drilldowns.
For these two reasons (and because WCF is cool) we'll step through the process of creating a WCF dashboard for this custom agent. We'll use the drag and drop table at the top of the screenshot above as the starting design reference for our dashboard.
Getting Started with WCF
WCF (Web Console Framework) is the technology underlying all Foglight dashboards and reports. WCF consists of a rich set of configurable components that can be combined in uncountable ways to produce great-looking dashboards and reports. Drag and Drop dashboards and reports are built with a limited set of these compoents that can be configured in a limited sets of ways. WCF components are configured through the Configuration/Definiton dashboard in a set of screens that ultimately act as XML editors that open up a rich and powerful set of visualization options. This is the same configuration editor that Foglight cartridge develoers use to produce the out-of-the-box dashboards and reports that have become so popular with Foglight customers across many industries.
This article doesn't assume any familiarity with WCF, but you can learn more from the WCF tutorials in Foglight Help, or other articles in the Foglight Community.
The screenshots shown below are from Foglight 5.6. The WCF definition editor screens look a bit different in Foglight 5.5, but if you set each property to the same value, you should get the same result.
Setup
In order to create sharable "System" dashboards, you must log onto Foglight as a user with the "Dashboard Designer" role. Since Foglight 5.6, the default "foglight" user doesn't have this role. A user with "Foglight Security Administrator" can grant the "Dashboard Designer" role to a group or individual.
Best Practice: Prototype WCF dashboards on a staging or test FMS. Avoid cluttering Production FMSs with experimental views.
Once logged in as a "Dashboard Designer", create a module that will contain the custom views. Since WCF dashboards are query-driven rather than data-driven, WCF modules can be exported from one FMS and imported to another.
To create a new WCF System module, open the left navigation panel and select "Definitions" from the "Configuration" group under "Dashboards". In the top left pane of the Splitter window that appears, you will find a green "+" button at the bottom of the list. Click on this button to create a new system module.
You will be prompted for a name for the module and you can optionally enter a description, logo, and Allowed Role(s) for the module. Make sure that you enter at least one Relevant Role for the module. I recommend starting with Operator and Advanced Operator roles.
Set the name of the module to TCPcheck and select Advanced Operator, Operator as the "Relevant Role(s)", Click OK.
Best Practice: Choose a short but meaningful name for your custom dashboard module. It's easier to export and import the dashboard if there are no spaces in the name. You can set the display name for the module separately.
Building Queries
Once you've created a module to contain the custom views, you're ready to start building. You can add many types of elements to the module including Functions, Renderers, Types, Tasks, Icons, Files and Mappings, but stick to the basics: Queries and Views for now.
One of the most powerful things about WCF dashboards is that they are query driven. This means that these dashboards will automatically adjust when the target data model changes. To address the requirement for "a dashboard that automatically populates when new TCP Check agents are deployed and activated", we'll define a query that finds all the "tcp_check" agents in the model. We'll follow that up with a query to find all the "tcp_check" data tables given a set of "tcp_check" agents. Queries are basically just easy way to navigate Foglight models and return a list objects that match a specification given a starting place and a path to traverse.
Although the WCF editors look pretty complicated at first glance, you'll find with a bit of practice that they get easier to understand and work with. You don't need to understand every option to build good dashboards. You can get good results by using just a few basic properties that we'll step through in this and subsequent tutorials.
Query to Return a List of Custom Agents
Select the module you just created in the top left pane and you will see a blank slate of dashboard elements in the bottom pane.
Change the combo box that says "View" to "Queries". Click the 'plus' button beside the combo box. In the Add Query dialog with the "Create a Blank Query" tab selected, enter "tcp" in the search box. Select "tcp_check_Agent" (or whatever your custom agent name is) from the list and click OK.
The Query editor will appear in the main panel of the page.
Set the name of the query to "allTCPcheckAgents"
Set Root Reference From to "Monitoring : (Default Instance)"
Set Path to "Agent Map"
Click "Test" at the top. You should see your custom agent appear in the list. Click "Close"
Click "Save" at the top. If you're new to WCF, you've just created your first query.
Query to Return a List of Agent Tables Given a List of Agents
The next query is similar, but this time there's an input parameter.
Click the 'plus' button beside the "Query" combo box again. In the Add Query dialog with the "Create a Blank Query" tab selected, you should see the results of the previous search for "tcp" in the search box. If not, search for your custom agent name again. Select "tcp_check_Agent_Table_TCP_CHECK" (or whatever your custom agent table name is) from the list and click OK.
The Query editor will appear in the main panel of the page.
Set the name of the query to "TCPcheckTables"
Add the query parameter definition by clicking on the 'plus' button below "Required Parameters"
Below "Key", click and enter "tcpCheckAgents". Change the List value to "true". Click below "Data Type" and click the "..." button to pop up the editor.
In the Select Type editor, enter "tcp" in the search box and select "tcp_check_Agent" (or your agent name) from the list and click "Save".
This time, the query will start with the input agents and look for matching tables below them in the model.
Click in Root Reference From field. Open parameters, and select the key name you just configured for the parameter.
Click in the Path field, scroll down and select "Tables (list of F4Tables)".
The query configuration is complete.
Click "Test" at the top. You'll be prompted for the Input Value for "tcpCheckAgents".
Click on the "..." button and select Query.
In the Edit - tcpCheckAgents dialog, click the down arrow beside the Query field, scroll down and open the TCPcheck module, then select "allTCPcheckAgents", the query you just created. Click Set.
Click "Results" to test the new query.
You should see your custom agent table(s) appear in the list. Click "Close"
Best Practice: Use the Test button to make sure that you have configured your queries (and views) correctly.
Click "Save" at the top. You now have the basic queries required to build lots of useful dashboards and reports with your agent data.
Build a Row-Oriented Table to Display the Agent Data Table Values
Keeping your custom module ("TCPcheck") selected, change the "Queries" dropdown to "Views".
Click on the 'plus' button beside "Views". From the Add View dialog in the "Create a Blank View" tab, open "Common" and select "Row-Oriented Table". Click OK.
The Row-Oriented Table View editor appears in the main window. The editor has four tabs: General, Context, Configuration, and Flow.
General tab
These are the general properties of the view, which describe how the view will be used.
Set Name to "TCP Check Table"
Enable the "Public" checkbox.
Click on the Purpose(s) editor. Select Dashboard, Pagelet, Portlet. Click Apply.
Context Tab
Context defines the inputs necessary to populate the view. "timeRange" is specified by default as almost all Foglight views respond to changes in the page time range. Inputs can be Required or Optional. If an input is Required, then the view can't draw unless that input is supplied. If an input is optional, provide a default value but allow the default to be overridden by a parent view. For this dynamic custom agent table, start by configuring a list of custom agents as an optional input and set the agent query defined above as the default value. Next, use the second query in "Additional" inputs to get the list of data tables from the agents defined in the Inputs section. These are the detailed steps:
Define Required Inputs
In the Input table, click on the 'plus' button in the second row, below timeRange.
In the Key column, replace "(not named)" with "tcpCheckAgents".
Change Usage to Optional
Change List to True
Click in the field in the Data Type column and click the "..." button.
In the Select Type dialog, enter "tcp" in the search field and select "tcp_check_Agent" from the result list. Click Save.
Click the 'edit' button in the Fallback Value column and select Query.
In the Edit - Context Input Entry "tcpCheckAgent", click the Query 'down' arrow, scroll down, open "TCPCheck" and select the "allTCPcheckAgents" query created above. Click Set.
Set Primary Input to "tcpCheckAgents".
Define Additional Inputs
In the Additional table, click on the 'plus' button in the first row.
In the Key column, replace "(not named)" with "tcpCheckTables".
Click the 'edit' button in the Value column and select Set to Binding > Query.
In the Edit - Context Input Entry "tcpCheckTables", click the Query 'down' arrow, scroll down, open "TCPCheck" and select the "TCPcheckTables" query. You will be prompted for the value of Parameter tcpCheckAgents. Click the 'edit' icon in the Value column and select Context. In the popup parameter editor, click on the down arrow in the Input Key field and select "tcpCheckAgent (List of tcp_check_Agents)". Click Set (parameter editor).
Click Set (context entry "tcpCheckTables").
Configuration - Rows and Columns
The basic table properties and the input data for the table have been defined. Next set the items to be displayed in the table rows and columns. Each row represents a monitored TCP port. Configure the same columns as the drag/drop table shown at the top of the first screenshot above.
Select the Configuration Tab
Rows: Click the 'edit' icon in the Value column beside Rows and select Context. Drop down the Input Key selector and select "tcpCheckTables (List of tcp_check_Agent_Table_TCP_CHECKs)". Click Set
.
Open Columns.
Column 1: Open Column.
Click the 'edit' button in the Value column beside the Value field and select Context.
In the Edit - Value dialog, drop down the Input Key field and select "currentRow (tcp_check_Agent_Table_TCP_CHECK)".
In the Path drop down, check "show all" and select "Aggregate State - Integer". This will appear as "aggregateState" in the Path field. Click Set.
Column 2: Click on the 'plus' sign to add a new column.
For the second column, click the 'edit' icon beside Value and select Context.
In the Edit - Value dialog, drop down the Input Key field and select "currentRow (tcp_check_Agent_Table_TCP_CHECK)".
In the Path drop down, select "hostname - String". This will appear as "hostname" in the Path field. Click Set.
Column 3: Click on the 'plus' sign to add a new column.
For the third column, click the 'edit' icon beside Value and select Context.
In the Edit - Value dialog, drop down the Input Key field and select "currentRow (tcp_check_Agent_Table_TCP_CHECK)".
In the Path drop down, select "port - String". This will appear as "port" in the Path field.Click Set.
Column 4: Click on the 'plus' sign to add a new column.
For the fourth column, click the 'edit' icon beside Value and select Context.
In the Edit - Value dialog, drop down the Input Key field and select "currentRow (tcp_check_Agent_Table_TCP_CHECK)".
In the Path drop down, open "message - String Observation". Open "Current - StringValue". Select "value - String". This will appear as "message/current/value" in the Path field. Click Set.
That's enough configuration for now. We'll refine the table once it's been tested.
Click Save at the top to save this Row-Oriented Table view.
Click on the Test button. Accept the default Input Values and click Results.
Depending on your browser, you may need to enable popups from this FMS in order to see the test table.
It should look something like this:
Refine the Table
This is pretty good, but some refinements are required:
- Change column titles to: "Health", "Hostname", "Port", and "Message".
- Center the icon in the "Health" column.
Return to the WCF Definitions editor.
Edit TCP Check Table
Open the Configuration Tab
Enable "Show Advanced Properties"
Open Columns
Open the first Column
Set ID=health
Click the edit icon beside "Header". Select "Set to Binding>Localized String".
In the Localized string editor, enter "Health". Click Set.
Open Cell Alignment. Click the edit icon beside Horizontal. Select Center.
Current Sort Order=Descending
Close the first column
Open the second Column
Set ID=hostname
Click the edit icon beside "Header". Select "Set to Binding>Localized String".
In the Localized string editor, enter "Hostname". Click Set.
Close the second column
Open the third Column
Set ID=port
Click the edit icon beside "Header". Select "Set to Binding>Localized String".
In the Localized string editor, enter "Port". Click Set.
Close the third column
Open the fourth Column
Set ID=message
Click the edit icon beside "Header". Select "Set to Binding>Localized String".
In the Localized string editor, enter "Message". Click Set.
Close the fourth column
Best Practice: Set the ID of each column to a brief meaningful name. This makes it easier to identify which column is which in the editor, and also enables customized actions for each column on click or dwell.
Save the view "TCP Check Table"
The definition summary for this view should look something like this:
Congratulations, you've built a WCF dashboard and drag/drop Portlet!
You can view this dashboard by selecting TCP Check Table under TCPcheck in the left Navigation page.
You can also drag and drop this table on a custom portal by selecting it from the right Action panel Views tab: TCPcheck/TCP Check Table.
In the next installment of this series, we'll configure the TCP response time as a Metric and add it to this dashboard.
Please post a comment if you successfully complete these steps or get stuck along the way.
If you have other questions about WCF, you can post these questions in the Custom Dashboards & Scripts Discussion Forum.
Happy Dashboarding!
Brian Wheeldon