So I was very pleased when the Release Notes of the latest Log Insight version announced the availability of a Query API. On the blog of Steve Flanders there are several posts that go further into this new feature. Definitely worth a read to get a better understanding of what is available, and what is not (yet).

My LogInsight PowerShell module makes use of these new API, and it will allow you to automate your interaction with Log Insight from within your PowerShell scripts.

First a word of warning, this module is still in an early development stage, so please only use in your test environment. And definitely provide feedback in the form of issues and suggestions.

The use of the LogInsight module is quite simple, there are in fact only 3 cmdlets you should use.

1. Connect-LogInsight: this cmdlet will allow you to connect to your Log Insight server.
2. Get-LogInsightEvent: this cmdlet will allow you to retrieve events of event bins from the Log Insight server
3. Get-LogInsightConstraint: is in fact a “helper” cmdlet. It provides a more user friendly way to create the constraints for your queries

Examples

Retrieve Events

$sConnect = @{
  Server = 'LogInsight.local.lab'
  User = 'admin'
  Password = 'VMware1!'
}
Connect-LogInsight @sConnect

$result = Get-LogInsightEvent -Event
$result.events

This is the most simple way to retrieve events from the Log Insight server. Since there are no constraints, all events will be returned, within the limitations of the API. The result looks something like this.

As a side note, the objects that are returned by the Get-LogInsightEvent cmdlet, contain more information than just the event text. There is also an indication if the query actually completed within the default timeout interval.

Retrieve Events with Constraints

On each query you can specify one or more “constraints”. In other words, you specify some conditions, and only the events that comply with these conditions will be returned.

Connect-LogInsight @sConnect

$constraint = Get-LogInsightConstraint -Field 'hostname' -Operator STARTS_WITH -Value 'esx1'

$result = Get-LogInsightEvent -Event -Constraint $constraint -Limit 100
$result.events

To make the creation of these constraints easier, the cmdlet Get-LogInsightConstraint is available. It takes three parameters, a field, an operator and a value. In the previous code the constraint says the hostname shall start with the string “esx1“. The Field parameter can take any of the field names that you see in the query builder in the Log Insight console.

Notice how we also limit the returned number of events to 100 with the Limit parameter.

You can combine constraints, for that you just need to add all your constraints to an array.

Connect-LogInsight @sConnect

$constraint = @(
(Get-LogInsightConstraint -Field 'text' -Operator CONTAINS -Value 'error'),
(Get-LogInsightConstraint -Field 'hostname' -Operator STARTS_WITH -Value 'esx1')
)

$result = Get-LogInsightEvent -Constraint $constraint -Event
$result.events

Which results in just one event in my test lab.

Retrieve Bins

This feature allows running aggregate functions against fields which are returned in time-based fixed-width bins. It sounds more complex than it is.

Connect-LogInsight @sConnect

$constraint = Get-LogInsightConstraint -Field 'hostname' -Operator STARTS_WITH -Value 'esx1'

$result = Get-LogInsightEvent -Constraint $constraint -Aggregate
$result.bins

This will return the COUNT of events in each bin, and a bin has the default width of 5000 milliseconds.

Note that we can use the same constraints we used before to retrieve the events.

There are other aggregate functions available. An interesting one is the SAMPLE function.

Connect-LogInsight @sConnect

$constraint = Get-LogInsightConstraint -Field 'hostname' -Operator STARTS_WITH -Value 'esx1'

$result = Get-LogInsightEvent -Constraint $constraint -Aggregate -Function SAMPLE -BinWidth 10000
$result.bins

Note that we also changed the width of the bin to 10 seconds. The result looks like this

This LogInsight module is still in the early stages of development. There are tons of improvements and additions that I have in mind, but I’m also counting on feedback from the Community to prioritise my work on the module. And since the module is on GitHub, feel free to pull and improve.

The module is available in the PSGallery.

If you’re using WMF 5, you can do

Find-Module -Name LogInsight | Install-Module -Scope CurrentUser -Force -Confirm:$false

Enjoy!