Turn "The Script Failed" into "Here's What Failed, Where, and Why" — Enterprise Logging for Unattended PowerShell

A production log should help an administrator answer:

• What script ran?
• When did it start and finish?
• Which version ran?
• Who or what executed it?
• On which system did it run?
• What parameters or configuration were used?
• Which major operations succeeded?
• Which operations failed?
• Which object was affected?
• Was the run fully successful, partially successful, or failed?
• How long did each major operation take?
• Can the failure be safely retried?
• Were any changes made before the failure?
• Where can additional diagnostic evidence be found?

param(
    [string]$InputPath,
    [string]$OutputPath
)

Write-Host "Starting"

$users = Import-Csv $InputPath

foreach ($user in $users) {
    try {
        Set-ADUser -Identity $user.SamAccountName -Department $user.Department
        Write-Host "Updated $($user.SamAccountName)"
    }
    catch {
        Write-Host "Failed $($user.SamAccountName)"
    }
}

$users | Export-Csv $OutputPath -NoTypeInformation

Write-Host "Done"

The script performs a bulk Active Directory update and should record:

• Script start
• Input and output paths
• Number of imported records
• Start and result of each user update
• Skipped or invalid records
• Exception details for failed updates
• Export result
• Final totals
• Overall duration
• Final status

The script should not log:

• Credential contents
• Full Active Directory user objects
• Unnecessary personal information
• Authentication details
• Entire CSV rows

The SamAccountName may be used as the operational identifier if organizational policy permits it. In a more restricted environment, a hashed or internal correlation value may be preferable.

The existing catch block hides the underlying exception, making failures difficult to diagnose. Logging should capture safe exception metadata while preserving a failure count and final status.

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [ValidateSet('Debug', 'Information', 'Warning', 'Error', 'Critical')]
        [string]$Level,

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

        [Parameter()]
        [string]$Operation,

        [Parameter()]
        [string]$Target,

        [Parameter()]
        [hashtable]$Data,

        [Parameter()]
        [System.Exception]$Exception
    )

    $logEvent = [ordered]@{
        Timestamp        = (Get-Date).ToUniversalTime().ToString('o')
        Level            = $Level
        Script           = $script:ScriptName
        ScriptVersion    = $script:ScriptVersion
        RunId            = $script:RunId
        Hostname         = [Environment]::MachineName
        User             = [Environment]::UserName
        ProcessId        = $PID
        PowerShell       = $PSVersionTable.PSVersion.ToString()
        Operation        = $Operation
        Target           = $Target
        Message          = $Message
        ExceptionType    = $null
        ExceptionMessage = $null
        Data             = $Data
    }

    if ($Exception) {
        $logEvent.ExceptionType = $Exception.GetType().FullName
        $logEvent.ExceptionMessage = $Exception.Message
    }

    $json = $logEvent | ConvertTo-Json -Depth 6 -Compress

    try {
        Add-Content -LiteralPath $script:LogPath -Value $json -Encoding utf8
    }
    catch {
        Write-Warning "Logging failed: $($_.Exception.Message)"
    }

    switch ($Level) {
        'Debug'       { Write-Debug $Message }
        'Information' { Write-Verbose $Message }
        'Warning'     { Write-Warning $Message }
        'Error'       { Write-Error $Message -ErrorAction Continue }
        'Critical'    { Write-Error $Message -ErrorAction Continue }
    }
}

[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [ValidateScript({
        if (-not (Test-Path -LiteralPath $_ -PathType Leaf)) {
            throw "Input file does not exist: $_"
        }
        $true
    })]
    [string]$InputPath,

    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string]$OutputPath,

    [Parameter()]
    [ValidateNotNullOrEmpty()]
    [string]$LogDirectory = "$PSScriptRoot\\Logs"
)

$script:ScriptName = 'Update-AdUserDepartment'
$script:ScriptVersion = '1.0.0'
$script:RunId = [guid]::NewGuid().ToString()
$scriptStartTime = Get-Date

if (-not (Test-Path -LiteralPath $LogDirectory -PathType Container)) {
    New-Item -Path $LogDirectory -ItemType Directory -Force | Out-Null
}

$script:LogPath = Join-Path -Path $LogDirectory -ChildPath "$($script:ScriptName)-$($scriptStartTime.ToString('yyyyMMdd')).jsonl"

# [Write-Log function as defined above]

$successCount = 0
$failureCount = 0
$processedCount = 0
$finalStatus = 'Succeeded'

try {
    Write-Log -Level Information -Operation 'ScriptStart' -Message 'Active Directory department update started.' -Data @{ InputPath = $InputPath; OutputPath = $OutputPath }

    $users = Import-Csv -LiteralPath $InputPath -ErrorAction Stop

    Write-Log -Level Information -Operation 'ImportInput' -Message "Imported $($users.Count) user records." -Data @{ RecordCount = $users.Count }

    foreach ($user in $users) {
        $processedCount++
        try {
            Set-ADUser -Identity $user.SamAccountName -Department $user.Department -ErrorAction Stop
            $successCount++
            Write-Log -Level Information -Operation 'UpdateDepartment' -Target $user.SamAccountName -Message 'Active Directory department updated.'
        }
        catch {
            $failureCount++
            $finalStatus = 'CompletedWithErrors'
            Write-Log -Level Error -Operation 'UpdateDepartment' -Target $user.SamAccountName -Message 'Active Directory department update failed.' -Exception $_.Exception
        }
    }

    $users | Export-Csv -LiteralPath $OutputPath -NoTypeInformation -Encoding utf8 -ErrorAction Stop

    Write-Log -Level Information -Operation 'ExportResults' -Message 'Result file exported successfully.' -Data @{ OutputPath = $OutputPath }
}
catch {
    $finalStatus = 'Failed'
    Write-Log -Level Critical -Operation 'ScriptExecution' -Message 'The script encountered a terminating failure.' -Exception $_.Exception
    throw
}
finally {
    $duration = (Get-Date) - $scriptStartTime
    Write-Log -Level Information -Operation 'ScriptComplete' -Message "Script completed with status: $finalStatus" -Data @{ Status = $finalStatus; ProcessedCount = $processedCount; SuccessCount = $successCount; FailureCount = $failureCount; DurationMs = [math]::Round($duration.TotalMilliseconds) }
}

{"Timestamp":"2026-07-21T15:04:12.3468120Z","Level":"Information","Script":"Update-AdUserDepartment","ScriptVersion":"1.0.0","RunId":"7ad29d42-b89f-43da-927f-9a946bc5fe49","Hostname":"ADMIN01","User":"svc-automation","ProcessId":4820,"PowerShell":"7.4.6","Operation":"ScriptStart","Target":null,"Message":"Active Directory department update started.","ExceptionType":null,"ExceptionMessage":null,"Data":{"InputPath":"C:\\Input\\users.csv","OutputPath":"C:\\Output\\results.csv"}}

{"Timestamp":"2026-07-21T15:04:14.9237810Z","Level":"Error","Script":"Update-AdUserDepartment","ScriptVersion":"1.0.0","RunId":"7ad29d42-b89f-43da-927f-9a946bc5fe49","Hostname":"ADMIN01","User":"svc-automation","ProcessId":4820,"PowerShell":"7.4.6","Operation":"UpdateDepartment","Target":"jsmith","Message":"Active Directory department update failed.","ExceptionType":"Microsoft.ActiveDirectory.Management.ADIdentityNotFoundException","ExceptionMessage":"Cannot find an object with identity: 'jsmith'.","Data":null}

{"Timestamp":"2026-07-21T15:04:18.1024380Z","Level":"Information","Script":"Update-AdUserDepartment","ScriptVersion":"1.0.0","RunId":"7ad29d42-b89f-43da-927f-9a946bc5fe49","Hostname":"ADMIN01","User":"svc-automation","ProcessId":4820,"PowerShell":"7.4.6","Operation":"ScriptComplete","Target":null,"Message":"Script completed with status: CompletedWithErrors","ExceptionType":null,"ExceptionMessage":null,"Data":{"Status":"CompletedWithErrors","ProcessedCount":250,"SuccessCount":249,"FailureCount":1,"DurationMs":15756}}

Define retention based on execution frequency and operational need. Possible controls include:

• Maximum file age
• Maximum file size
• Maximum number of log files
• Compression of old logs
• Central archival
• Secure deletion
• Legal-hold exclusions

Example approach:

• One file per script per day
• Rotate at 100 MB
• Retain locally for 30 days
• Forward centrally within five minutes
• Retain centrally according to policy
• Alert when local log forwarding fails

These values are examples and should be adjusted to the environment.

Potential alert conditions include:

• Critical event recorded
• Final status equals Failed
• Final status equals CompletedWithErrors
• Failure count exceeds threshold
• Runtime exceeds expected duration
• No successful execution within expected window
• Authentication failure
• Repeated retry activity
• Log file not updated
• Record count deviates significantly from baseline
• Output artifact not created
• Cleanup or rollback failure
• Logging destination unavailable

Alerts should include:

• Script name
• Run ID
• Host
• Start time
• Final status
• Failure summary
• Link or path to detailed logs
• Recommended first action