Private/Logging/Write-StructuredLogEntry.ps1

function Write-StructuredLogEntry {
    <#
    .SYNOPSIS
        Writes structured log entries with consistent formatting
    #>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Message,

        [Parameter(Mandatory)]
        [ValidateSet('Critical', 'Error', 'Warning', 'Information', 'Debug', 'Verbose', 'INFO')]
        [string]$Level,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]$Component = 'General',

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string]$CorrelationId = [System.Guid]::NewGuid().ToString(),

        [Parameter()]
        [string]$LogPath,

        [Parameter()]
        [hashtable]$Details = @{}
    )

    # Normalize INFO to Information
    if ($Level -eq 'INFO') {
        $Level = 'Information'
    }

    # File output honours the configured -LogLevel; console output does not, so that warnings and
    # errors still reach an operator who lowered the file verbosity. Security entries bypass this
    # filter through Write-SecurityStructuredLogEntry.
    $writeToFile = $true
    if ($ExecutionContext.InvokeCommand.GetCommand('Test-LogLevel', 'Function')) {
        $writeToFile = Test-LogLevel $Level
    }

    # Debug and Verbose entries reach the console only when that stream is on, which is the
    # check Write-Debug and Write-Verbose make themselves
    $showOnConsole = -not $script:SuppressConsoleOutput
    if ($showOnConsole -and $Level -eq 'Debug') {
        $showOnConsole = $DebugPreference -notin 'SilentlyContinue', 'Ignore'
    } elseif ($showOnConsole -and $Level -eq 'Verbose') {
        $showOnConsole = $VerbosePreference -notin 'SilentlyContinue', 'Ignore'
    }

    # Most entries detection writes are Debug lines that go nowhere. Formatting one anyway cost
    # several milliseconds, and detection writes several per access rule, so it took about half of
    # each object's time (#111). An entry with no destination stops here.
    if (-not $writeToFile -and -not $showOnConsole) {
        return
    }

    try {
        $formattedEntryForFile = "[$(Get-Date -Format 'yyyy-MM-ddTHH:mm:ss.fff')] [$Level] [$Component] [$CorrelationId] $Message"
        if ($Details.Count -gt 0) {
            $detailsJson = $Details | ConvertTo-Json -Compress
            $formattedEntryForFile += " | Details: $detailsJson"
        }

        if ($showOnConsole) {
            Write-ConsoleLogEntry -FormattedMessage "[$Level] [$Component] $Message" -Level $Level
        }

        if ($writeToFile) {
            # Use the path passed in, otherwise the logging system's
            $effectiveLogPath = $LogPath
            if (-not $effectiveLogPath -and $ExecutionContext.InvokeCommand.GetCommand('Get-LoggingSystemState', 'Function')) {
                try {
                    $effectiveLogPath = (Get-LoggingSystemState).LogPath
                } catch {
                    Write-Verbose "Could not retrieve logging system state: $($_.Exception.Message)"
                }
            }

            if ($effectiveLogPath) {
                try {
                    # -WhatIf on the public command reaches here through $WhatIfPreference; the log is
                    # not what is being rehearsed, so the write is pinned
                    # -ErrorAction Stop: Add-Content's failures are non-terminating and would skip the catch
                    Add-Content -Path $effectiveLogPath -Value $formattedEntryForFile -Encoding UTF8 -WhatIf:$false -ErrorAction Stop
                } catch {
                    Write-Warning "Failed to write log entry to file: $($_.Exception.Message)"
                }
            }
        }    } catch {
        Write-Warning "Failed to write structured log entry: $($_.Exception.Message)"
    }
}

function Write-ConsoleLogEntry {
    [CmdletBinding()]
    param(
        [string]$FormattedMessage,
        [string]$Level
    )

    # -SuppressConsoleOutput on the public commands sets this; the file still receives every entry
    if ($script:SuppressConsoleOutput) {
        return
    }

    switch ($Level) {
        'Critical' { Write-Error $FormattedMessage }
        'Error' { Write-Error $FormattedMessage }
        'Warning' { Write-Warning $FormattedMessage }
        'Information' { Write-Information $FormattedMessage -InformationAction Continue }
        'Debug' { Write-Debug $FormattedMessage }
        'Verbose' { Write-Verbose $FormattedMessage }
        default { Write-Information $FormattedMessage -InformationAction Continue }
    }
}