Release - PSFramework v1.15.472

Just released v1.15.472 of the PSFramework module!

This update is all about the logging system, with some additional convenience utilities and bugfixes added on top.

Hand over the deets

The quick summary of what changed:

• New Azure Log Analytics logging provider, as the old provider no longer works in baseline Azure.
• Massively improved performance of default logging provider
• A lot of smaller tweaks and fixes, as well as backend changes invisible for now to open the path to future features.
• New command: Test-PSFHashtableEquality - compare two hashtables with each other.
• New command: Test-PSFParameterSet - check, whether the specified command with the specified parameters would resolve to the specified parameter set, without actually executing it.
• ConvertTo-PSFHashTable now comes with parameters to strip key/value pairs out of it that are either $null, empty string or empty collections
• Other fixes

Azure Log Analytics V2 Provider

The old means to send logs to Azure Log Analytics were retired in September. The new V2 Logging Provider uses the new way to do so, involving Data Collection Rules and Data Collection Endpoints.

Note: This method is significantly more complex to set up. Tooling is available (see the provider documentation), but it limits the examples that can be usefully given in a blog post.

The new provider supports out of the box:

• Client Secret / Certificate authentication
• System-Assigned and User-Assigned Managed identity authentication
• Federated Credentials
• Delegate Authentication via Browser
• All Environments
• Custom EntraAuth tokens, if the provided options don't suffice.

The old provider is still included and working unchanged, as in some Azure Environments or Azure Local it might still be desired.

Speed up the Default Logging Provider

By default, whenever you use PSFramework, there is one Logging Provider enabled by default: The Filesystem provider. It's automatic and ... well, most don't even know it's there.

Which is fine.

So what does it matter, if we improved its performance? Well, all logging happens in a background runspace, and it happens sequentially. Which means, if you did not disable the Filesystem Provider, it would limit overall log throughput.

Yes: Its speed impacts the overall logs throughput.

Since it was to the local filesystem, the overall cost shouldn't have been too bad, right?

Well, here's the cap it enforced on message throughput (measured on a regular commercial SSD):

• Old Version: ~1,600 Messages / Minute
• New Version: ~500,000 Messages / Minute

These numbers do not factor in whatever logging was configured on top of that, but it meant that unless disabled, it used to impose a 26.6 msg/s limit on overall throughput!

The consequence: Very verbose code - especially when parallelizing - could blow up memory with backlogged messages waiting to be logged. The new version, with its 8333.3 msg/s could theoretically still suffer from the same problem, but ... well, this should be reserved to the absolutely most absurd high-scaling scenarios that would have already had to manage this.

Other Logging-System-Related changes

The remaining changes are mostly internal, but there are two a PSFramework user might encounter:

1. Provider Description and Display

Logging Providers can now be assigned a description when registering them through Register-PSFLoggingProvider. Unless you author your own providers, this will not matter to you directly, but we also changed how Logging Providers are displayed when retrieved for the console:

Get-PSFloggingProvider

Name                Enabled ProviderVersion Description
----                ------- --------------- -----------
filesystem          True    Version_1       The default debuglog, enabled by default.
AzureLogAnalytics   False   Version_2       [Deprecated] Logs to Azure Log Analytics through the legacy Data Collector API
AzureLogAnalyticsV2 False   Version_2       Logs to Azure Log Analytics through the Logs Ingestion API
console             False   Version_2       Writes messages to the console screen. Intended for use in orchestration tools that report what is written to screen.
eventlog            False   Version_2       Sends messages to the Windows Eventlog on the local computer.
gelf                False   Version_2       Log to a Graylog server
logfile             False   Version_2       The universal logfile provider, useful for any given logfile format
splunk              False   Version_2       Log to a splunk instance.
Sql                 False   Version_2       Use dbatools to log to a MS SQL Database. Creates & configures the table if needed.

2. Get-ConfigValue gains a -Fallback parameter

Do not confuse with Get-PSFConfigValue! This update is only relevant to authors of Logging Providers - and used to access Instance-specific configuration settings (e.g. as provided by Set-PSFLoggingProvider).

It now has the option to provide a default / fallback value to simplify code a little.

Utilities

Test-PSFHashtableEquality

Makes it easy to compare two hashtables for equality.

Problem:

$hash1 = @{ A = 1; B = 2 }
$hash2 = @{ A = 1; B = 2 }
$hash1 -eq $hash2 # $false

Plain equality comparison does not work as the eye would let us believe things should be. The two hashtables have the exact same structure, but they are not equal, because there is no special comparison logic implemented here, so PowerShell only compares, whether the two hashtables reference the same piece of memory.

$hash1 = @{ A = 1; B = 2 }
$hash2 = @{ A = 1; B = 2 }
Test-PSFHashtableEquality -Table1 $hash1 -Table2 $hash2 # $true

It also supports recursive comparisons, one-way comparisons or case sensitivity.

Test-PSFParameterSet

Tests, whether the command specified would resolve to the specified parameter set with the parameters provided.

Test-PSFParameterSet -Name Connect-EntraService -Parameters $param.Keys -Sets 'Browser','DeviceCode

Returns whether with the specified parameters, Connect-EntraService would end up using either the 'DeviceCode' or 'Browser' Parameterset.