vRealize Network Insight 6.3 brought a new API endpoint: /search/ql. The QL stands for Query Language, which is the same language that’s used in the search bar. I added support for that endpoint in PowervRNI 2.0 with the cmdlet Invoke-vRNISearch. With this post, I’d like to explain why that’s the best since sliced bread. 😉

Previously, there was the /search API endpoint, but that used an internal query language. You would run a search in the vRNI interface, open up the browser Developer Tools and look for the internal query that went against the vRNI backend. You could then copy that internal query and use it in the API. A lot of work.

The query language used in the search bar is based on Elastic Search and can access all of the data that vRNI collects. There’s also the Search Exchange where you can copy and paste a ton of searches. In any case, it’s a lot easier to get any type of data out of vRNI’s public API using this new endpoint!

Running Searches

First thing you need, is at least v1.9 of PowervRNI (get it from the PowerShellGallery). The cmdlet you’re using is Invoke-vRNISearch. Before running it, it’s good to understand that there are three types of search results: entity list, aggregation, groupby. These result types determine how you interpret the result structure, which is important when you’re building a script. I’ll go through them separately below.

Entity List Result

An entity is an object in vRNI: things like VMs, hosts, firewall rules, etc. The Entity List result type comes back when you are searching for a list of entities. For example: searching for VMs, flows, security groups, with or without the where operator, returns a list of entities. Here’s an example:

The search VMs where Incoming Port = 80 lists every VM (vSphere, Azure, VMC, any VM) that has port 80 open and is receiving traffic. The result is a list of entities that refer to these VMs. Inside the initial result, you can see a field called $list.search_response_total_hits, which is the total number of results (VMs) returned. Then $list.entity_list_response.results is an array with the VMs.

As with the /entities/vms API endpoint, the list of VMs only has the entity_id and entity_type. You can use the entity_id to request the information about the VM via the /entities/vms/$entity_id API. 

Aggregation Result

Next up: aggregations. When you use an aggregation operator (sum, max, min, avg, count) in a search, vRNI aggregates data into one result. Let’s say you want to see the total number of bytes that go towards the internet, or the total number of GBs that VMs are using, or the count of security groups in a specific NSX Manager, these aggregation operators are your friend. Here’s an example:

The search sum(bytes) of flow where flow type = ‘internet’ gives you a sum of all the traffic going to or coming from the internet. The initial result has two fields: $sum.search_response_total_hits is indicating how many flows were taking into account, and $sum.aggregation_response.aggregations has the output. The aggregations field is an array, because you can also request multiple aggregations in one search. Here’s an example of that: 

Group By Result

The final result type is when you have groupings of results. For example, searching for all the internet flows and then grouping by VMs. You’ll get the amount of traffic traffic specified per VM. This result usually also combines aggregations, as it’s typically used to get the sum/avg/max/etc. of a metric (bytes) attached to an entity (flow) and grouped by another indirect entity (VM). Here’s an example:

The search sum(bytes) of flow where flow type = ‘internet’ group by VM gives you the internet traffic per VM and the first level of results have similar fields as before. The $groupby.search_response_total_hits indicates how many results have been used to get here (internet flows). And because it’s a grouping search, the main results are in $groupby.groupby_response. That’s then split up in some property fields for the size of the result, the time window, and a cursor if it’s a paged response. The meat is in the $groupby.groupby_response.results array.

Results are filled with a bucket (the value of the entity you’re grouping on, the VM name in this example), count (number of flows), and a nested array for either the aggregations or series_values. I’m doing a sum() in the example, which is an aggregations. Series are sets of metric points over a period of time. One example is this search: max(series(sum(bytes))) of flow where..etc.. You’d get a network usage graph back as result in the UI and the API output would be the raw data behind the graph.

Anyway, the agrgegations field behaves the same way as the regular aggregations result. Field is the metric that’s reported (bytes), aggregation_type is the math function (SUM), and value is the…value. 😉 In this example, the VM web-w-906 had a sum of 40735002 bytes in 40 flows.

Conclusion

The new search API endpoint in the 6.3 release of vRNI, makes it a lot easier to consume the search engine programmatically. Form the search query in the web interface, using the guidance that provides, and once you’ve found the right query: copy and paste it into the API endpoint. Using PowervRNI abstracts the API usage and makes it even easier. 

Happy automating! 🙂

Share the wealth!