3.0 Advanced Dashboard Primer
Aren't you an intrepid explorer!  Look at you jumping right to the advanced section!  Well, we are glad you are here.  In this section we'll be looking at how you can create much more complex dashboard content.

As soon as you want to go beyond supplied panels, or direct data from inventory queries, then things are going to get a bit more complex.  However, don't be daunted!  We are going to give you the building blocks here for building complex and very meaningful aggregate data from FileWave sources.

Please see the articles below for the elements we'll build on:

3.1 Aggregating Data
What
The FileWave dashboard can show raw device data, but aggregated data is what gives you the quick summary. Aggregation rolls many records into something easier to read, such as counts by version, model, or status.
When/Why
Use aggregation when you need the big picture instead of a long list. For example, if you are rolling Java from build 183 to build 196, a per-device report shows every record, but an aggregated view shows how many devices are still on each version. That makes rollout progress much easier to understand at a glance.
How
To get aggregated data into Grafana, create a Prometheus scrape job that summarizes the inventory-query data you care about. The next articles in this section walk through that process: define the Prometheus job, test the scrape, review the resulting metric in Explore, and then turn it into a panel.

3.1.1 Grouping Data Using Prometheus
What
In order to do summary reporting, we need to leverage the power of Prometheus.
When/Why
Anytime we want to do something like report on a rollout or general status, we are going to want to summarize a report.  We will accomplish this by using a Prometheus config file on the FileWave server itself.
How
The configuration (or yml files) that we'll create will always be placed in the /usr/local/etc/filewave/prometheus/conf.d/jobs/https directory on the FileWave server.  Anything placed in this directory will automatically be read by Prometheus, and the data presented to our dashboard.  (Example yml files can be found in /usr/local/etc/filewave/prometheus/conf.d/jobs)
The syntax of these files is quite picky, so it is best to copy an existing one, and then modify it.  It may seem complicated, but we are always going to do the following steps:
 
 
Step
Example
1. Place a new (or copied) yml file into /usr/local/etc/filewave/prometheus/conf.d/jobs/https with a meaningful name.
2. Edit the new file to specify the following 3 things:
* The inventory query (report) to use
* The field you want to count by...device_id is almost always a good one if reporting by device
* The field you want summarize (aggregate) by...in this case, the filewave client version
 
3. Once your report is created, the report id to use is most easily accessed through the webadmin.  Note that the fields you want to use for aggregation must be in the report.
4. Get the definition for the fields you want to use from the API...the easiest way is to do a curl from the command line like this: 
bash<br>curl -s -k -H "Authorization: <Base64_API_Token>" https://<my.server.address>:20445/inv/api/v1/query/<report_id> | python -mjson.tool<br>
Make sure and substitute in your values for the <Base64_API_Token>, <my.server.address> and <report_id>
You'll get a response that includes the component and the field names as shown at right
4. Edit the YML file to specify the 3 items as they match your report definition, then save the file.  If using the sample file, remember to take out the comment # at the beginning of each line.  Example at right:
Within a minute or two of creation of the file, the data should be available in your dashboard for a new panel.
 

3.1.2 Testing the Prometheus Scrape
What
If a scrape target does not appear in Grafana, first check whether Prometheus can see the job and whether the scrape is failing.
When/Why
Prometheus exposes a targets page that shows the status of configured scrapes. That page is the quickest place to check for YAML mistakes, missing jobs, and scrape errors.
How
The Prometheus targets page is not open to external systems by default. If the port were open, you would browse to https://my.server.address:21090/targets. Because it is closed, create an SSH tunnel from your computer instead. From Terminal on macOS, run:
ssh -L 8000:localhost:21090 user@my.server.address
On Windows, you can do the same thing in PuTTY by configuring a tunnel from a local port of your choice to the FileWave Server:
These configurations send local traffic on port 8000 through the SSH connection to port 21090 on the FileWave Server. After the tunnel is connected, open http://localhost:8000/targets in your browser to view the scrape data.
The example below shows a job with a bad query reference. Query 153 does not exist, so Prometheus reports the scrape error on the targets page:

3.1.3 "Exploring" Your New Aggregate Data
What
Before you build a formal Grafana panel, it often helps to look at the aggregated data directly. The Explore view is the fastest way to sanity-check what your report is producing.
When/Why
Use Explore after you have configured the Prometheus scrape and want to confirm the metric looks right before turning it into a panel.
How
Aggregated inventory-query data is exposed in Dashboard metrics as 
filewave_inventory_query_<id>, where 
<id> is the report ID you used. The attached video shows the Explore workflow for one of those metrics.
In this example, the data is no longer shown as five separate records. Instead, it has been grouped into three records because only three different FileWave client versions are present across the endpoints. That grouped result is much easier to use when you build a chart, such as a pie chart, in the next step.

3.1.4 Creating your Data Panel
What
Once your aggregated metric is available in Grafana, you can turn it into a panel that answers the question you actually care about.
When/Why
Pick the visualization based on the story the data needs to tell. Pie charts work well for a current distribution, such as how many devices are on each client version right now. Line or bar charts are better when you want to watch that same data change over time.
How
Creating the panel is similar to the earlier dashboard examples, but now you are working with aggregated Prometheus data instead of a simple raw query result. The video below shows the basic workflow.
Grafana gives you a lot of freedom in how a panel is presented. One small detail that helps immediately is the legend format. In this example, using 
{{genericdesktopclient__filewave_client_version}} makes the legend display the actual version value instead of a less useful raw field name.
We chose Instant in this example because the goal is a current snapshot, which is usually the right choice for a pie chart. If you want to see the same metric trend over time, use a visualization such as a bar or line chart and query the time-series data instead.

3.2 Extra Metrics
What
We learned in the 3.1 section how to build our own custom panels.  "Extra Metrics" is an independently built tool to automate creation of a few reporting elements for us without doing it manually.  This solution is NOT directly supported by FileWave, but you may find it useful in your environment.
When/Why
"Extra Metrics" gives data on applications, and generally on patch status of your devices.  The patch status elements are hard-coded, but the application versions panels are driven by dynamic reports that you can tweak to fit your needs.  All information for installation and upgrade of this solution is found here: https://pypi.org/project/filewave-extra-metrics/#description
How
In this example, we have Extra Metrics installed, and are adding a new report to view Firefox information on macOS devices.