While Archimedes once said “Give me a place to stand and with a lever I will move the whole world”, my personal preferred statement nowadays is “Give me an API, and I will automate it!”. And the LogInsight module I’m announcing is another step on that path.
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).
| Log Insight 3.3: Authentication API |
| Log Insight 3.3: Query API |
| Log Insight Query API: Use Cases, Basics, Caveats, and Best Practices |
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.
- Connect-LogInsight: this cmdlet will allow you to connect to your Log Insight server.
- Get-LogInsightEvent: this cmdlet will allow you to retrieve events of event bins from the Log Insight server
- 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
|
1 2 3 4 5 6 7 8 9 |
$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.
|
1 2 3 4 5 6 |
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.
|
1 2 3 4 5 6 7 8 9 |
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.
|
1 2 3 4 5 6 |
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.
|
1 2 3 4 5 6 |
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
|
1 |
Find-Module -Name LogInsight | Install-Module -Scope CurrentUser -Force -Confirm:$false |
Enjoy!
Derek Baines
Hi, has anyone managed to do a combination of and & or constraints ?
eg: event and host or host?
Thanks
LucD
Hi Derek,
No, I’m afraid I haven’t seen that yet.
Lars
Any luck with getting \”Authsource=ActiveDirectory\” to work? Thanks
Sean
@fabd
Hi fabd and LucD,
I have the same error message. Using powershell v5 now.
Any ideas for this kind of error message.
Thanks.
LucD
Drop me an email, I have a newer version of the module that you could try.
fabd
@LucD
Thanks
i will continue to develop my dashboard and check after for the API 🙂
fabd
@LucD
Hi,
i did it, (even if it v4), and after i get another error
PS C:\Users\> Import-Module -Name LogInsight
PS C:\Users\>
PS C:\Users\> $sConnect = @{
>> Server = ‘com’
>> User = ‘admin’
>> Password = ‘pass!!’
>> }
>>
PS C:\Users\> Connect-LogInsight @sConnect
Cannot index into a null array.
At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\loginsight\LogInsight.psm1:114 char:37
+ Write-Debug “`tERROR-CODE = $($excpt.Response.Headers[‘ERROR-CODE’])”
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : NullArray
PS C:\Users\fdupin>
LucD
It looks as if the connection fails.
And my code doesn’t seem to do a good job of extracting the status code (hence the error).
I’ll check if I can improve the error return from the connection.
fabd
hello LucD
i tryed to use the connect function but i get the error
Property ‘DontShow’ cannot be found for type ‘System.Management.Automation.ParameterAttribute’.
At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\loginsight\LogInsight.psm1:141 char:5
+ [Parameter(DontShow)]
+ ~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : PropertyNotFoundForType
LucD
The DontShow parameter attribute was introduced in PowerShell v4.
Or you leave it out, won’t have any effect, or you upgrade your PowerShell version, which I would advise.
brtlvrs
@LucD
well… I had to run it with $Debugpreferences=”Continue”.
And had to put a breakpoint at line 96. Because I got an error
“Cannot index into a null array.
At C:\Users\Bart Lievers\Documents\WindowsPowerShell\Modules\LogInsight\LogInsight.psm1:97 char:37
+ … Write-Debug “`tERROR-CODE = $($excpt.Response.Headers[‘ERROR-CODE’])”
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : NullArray”
the $excpt variable didn’t had a response property… it did contain the error message, saying “The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.” …
That’s when I replaced the certificate, and all when’t well :-)… looking forward to see this module grow….
tnx in advance
LucD
I’ll see if I can update the code to intercept that situation.
brtlvrs
I got it to work…. but found out it doesn’t work with a self-signed certificate….
it looks nice… going to play a bit more with it
LucD
Strange, I have it working with a self-signed certificate in my lab.
Any specific errors ?
Ian Salisbury
Sorry to resurrect an old thread, but I am seeing the same error and may have some info to help. We are using a self-signed cert, but even after adding it to the Trusted Root CA store, IE still complains that the address doesn’t match. This is accurate because the CN = “VMware vCenter log Insight”. Does the self-signed cert in your lab match the server name? We will try a proper cert but maybe not for some time, is there any way to bypass the error? Thanks!