As I mentioned in my last post (Advanced Reporting Part 1: Re-Creating the &quot;All Alerts&quot; Resource With Extras ), I was asked by a customer to help them create a screen that showed the active alerts, could be sorted by custom fields, and had an “acknowledge” button onscreen for the NOC to use. In the course of creating a solution, I realized that the skills needed to address this need weren’t particularly complex or specialized, but they relied on the monitoring engineer to be familiar with certain fundamental aspects of the Orion® Platform that not everyone has had a chance to explore. And so, in this post (and in the two that come after this), I’m going to dive into each one of those techniques. Just so you have a map, they are:
The Magic Word is “SWQL”
When I speak of customizing reports, I’m not focusing on the cosmetic items like the title, colors, logos, etc. I want to get at the data. While there are a host of pre-existing views, tables, and Orion objects that you can pull into a report simply by selecting them (and I strongly recommend you have a look, via all the pre-built reports that you get upon installation of Orion and each SolarWinds module), the true power of the Orion Platform has always been the ability to pull information directly from the database and display it however you want. All it takes is a little know-how.
As I mentioned in the last post, I started with the “All Active Alerts” report, then customized it to my needs. I believe this is the best way to begin most projects because it usually gets you further ahead than you would if you’d started from scratch.
Going to the Reports, All Reports menu, I found my starting report and opened it to see what it looked like.
Taking this as my starting point, I knew there were a few things I wanted to do:
Of course, I don’t want to directly edit this report because I may want to fall back to the original at some point, so instead of clicking “Edit Report,” I go back to the report list and click the “Manage Reports” link in the upper-right corner. Then I find my report again, select it, and click “Duplicate and Edit.”
Now we’re ready to get to work. Of course, you should change the title of the report first thing, along with other essentials like the logo, footer, etc. But the meat-and-potatoes of the work is the tiny little “edit” button that rests next to the “For” drop-down.
Clicking this will bring up the “Add Content” window, and you’ll be automatically dropped into the query editor. There are other options—static device selection and a dynamic query builder that strongly resembles the system used to create alerts. But we’re going to focus on SWQL because that’s one of the most useful (and often least-appreciated) skills a monitoring specialist can develop.
From within that window, you can include additional tables, add fields, and more. There’s only one problem: there’s no explorer, let alone a “test” option, so you have no way of knowing if any of your edits are going to work.
Or do you?
The Entrance to the Chamber of SWQL Secrets
...lies through SWQL Studio.
Now, many will say that the dynamic query builder is the way to go, and I won’t argue that it’s a good start for many projects. But there are still limitations to the query builder, including the inability to pull in data from other tables, and that’s precisely what we need here.
Without a web-based tool, where does a monitoring specialist turn? To the Orion Software Developer’s Kit (SDK). This free set of tools can be downloaded from GitHub (https://github.com/solarwinds/OrionSDK) and has a large and active forum on the THWACK® community (https://thwack.solarwinds.com/community/resources/orion-sdk) with plenty of how-to guides and tutorials to get you started.
Now if your first thought is that the SDK is meant for, well, “developers,” you wouldn’t be wrong. But the fact is that it’s a great tool for any SolarWinds aficionado to have in their toolkit because it includes the SWQL Studio, which lets you interactively (and safely) explore the entire Orion database and schema.
As long as you have a grasp of SQL query basics, you can use the SWQL Studio as a jumping-off point to create far more powerful alerts, reports, and resources.
In this example, we’re going to take the existing “All Alerts” query and add the “importance” custom property to the output.
Getting connected in SWQL Studio is just a matter of inputting the name or IP of your primary Orion polling engine along with the username and password you normally use to log in through the web portal.
Now the first thing I want to do is make sure I know where those darn custom properties are. If you’ve used SolarWinds tools for a few years, then you know they’ve moved from the main Nodes table into their own table.
I didn’t use any magic tricks here. I just kept clicking and searching until I found something that said “custom properties” on it. To be certain it had the information I wanted (i.e., the “Importance” custom property”), I right-clicked the table and clicked “Generate Select Query,” then the “Run” button to see the data.
Scrolling through the columns, I found the “Importance” column and verified the data, so I knew I had found what I needed.
The SWQL Two-Step Tango
First things first, I needed to pull the query out of the existing All Alerts report. This didn’t prove difficult at all, as I just duplicated the existing report (because I’ve worked in IT for more than 15 minutes, so I know to make backup copies of everything), click the “Edit” link next to the data source drop-down, et voila! There’s my query.
I can cut and paste that into the SWQL Studio just to see how it runs.
Now, the next step really leans on your existing SQL knowledge. You should see that the Custom Properties table uses NodeID as its key field. The question is whether that data exists in any of the tables that the original All Alerts report uses. To figure that out, I found each of the tables in the All Alerts query and did that same “Generate Select Query” action to see what fields were there.
Wouldn’t you know it, the Orion.AlertObjects table includes a “Related NodeID” field, which works perfectly for us. Now I can add the table source to the bottom of the All Alerts query with this line:
INNER JOIN Orion.NodesCustomProperties (nolock=true) NodeCP
ON AlertObjects.RelatedNodeID = NodeCP.NodeID
Then add the “Importance” field to the list of fields being collected:
Once I verify that everything works in SWQL Studio, I can copy and paste it back into the Customized All Alerts report in my Orion Portal.
But that’s only half (OK, more like three-quarters) of the battle. Just because I’m pulling that field into the data source doesn’t mean it’s going to show. Now I have to use the “Edit Table” button to add the new field.
And move it to the first column position.
Now I’m able to customize the report display by removing the grouping (that’s just a personal preference of mine) and sort the results first by importance, then by alert name, and finally by node name.
When I run it, I have the report I wanted (at least so far).
The Mostly Un-Necessary Summary
Hopefully you’re now a bit more comfortable with the techniques to add fields to reports (even somewhat complex ones like this). Stay tuned for the next post, where I’ll show you how to add HTML elements into the query output, so that things like the Node name are clickable and can take you to the Node Details page (or elsewhere).
Pro-tip I found along the way these past years, the Metadata entities are perfect for the "Where is that thing?/What can I do?" -type questions.
Finding entity names:
WHERE Name LIKE '%CustomProp%'
Finding all columns for a given entity, or the entities a specific column name is in:
-- You can search by either the entity name ("table" name), or directly for a column, across all entities
--WHERE EntityName = 'Orion.NodesCustomProperties'
WHERE Name LIKE '%Comments%'
Seeing all possible SDK Verbs, with arguments, in one place:
Just some extra data to the mix. Loving this series adatole
Awesome post Leon Adato Thank you! I've been trying to figure out how to add a button to that page so our NOC can click on it to approve the message and then send the command on along to our ticketing system to create a ticket.
SolarWinds solutions are rooted in our deep connection to our user base in the THWACK® online community. More than 150,000 members are here to solve problems, share technology and best practices, and directly contribute to our product development process. Learn more today by joining now.