AuditLogger

A PowerShell module providing reusable audit logging functionality for PowerShell scripts. This module creates timestamped, structured log files with automatic file naming and organization.

Features

• Automatic log file naming with timestamps, script names, computer names, and usernames
• Structured logging with multiple severity levels
• JSON data attachment support for complex objects
• Session-based logging with automatic path management
• Tab-delimited log format for easy parsing
• Automatic log directory creation

Installation

1. Download or clone this module to your PowerShell modules directory
2. Import the module in your scripts:

Import-Module "path\to\AuditLogger.psm1"

Quick Start

# Start audit logging
$logPath = Start-AuditLog

# Write log entries
Write-AuditLog -Message "Script execution started" -Level Info
Write-AuditLog -Message "Resource created successfully" -Level Success -Data @{ ResourceId = "vm-001"; Location = "East US" }
Write-AuditLog -Message "Warning: deprecated API used" -Level Warning

# End audit logging
Stop-AuditLog

Functions

Start-AuditLog

Initializes a new audit log session with automatic file naming.

Parameters:

• ScriptName (optional): Name of the script being logged. Auto-detected if not specified.
• LogDirectory (optional): Directory for log files. Defaults to logs folder relative to calling script.
• Username (optional): Username for log file naming. Defaults to $env:USERNAME.
• ComputerName (optional): Computer name for log file naming. Defaults to $env:COMPUTERNAME.
• Timestamp (optional): Timestamp for log file naming. Defaults to current time.

Returns: Full path to the created log file.

Example:

$logPath = Start-AuditLog -ScriptName "MyScript" -LogDirectory "C:\Logs"

Write-AuditLog

Writes a log entry to the current audit log.

Parameters:

• Message (required): The log message text.
• Level (optional): Log level. Valid values: Info, Warning, Error, Success, Verbose, Debug. Default: Info.
• LogFile (optional): Specific log file path. Uses current session log if not specified.
• Data (optional): Additional data object to be serialized as JSON.

Returns: The formatted log entry string.

Example:

Write-AuditLog -Message "User login successful" -Level Success -Data @{ UserId = "user123"; LoginTime = (Get-Date) }

Get-AuditLogPath

Returns the path of the current audit log session.

Example:

$currentLogPath = Get-AuditLogPath

Stop-AuditLog

Ends the current audit log session with a final log entry.

Parameters:

• Message (optional): Final log message. Default: "Audit log completed".

Returns: Path to the completed log file.

Example:

$completedLogPath = Stop-AuditLog -Message "Script execution finished"

Log File Format

Log files use a tab-delimited format with the following structure:

[Timestamp]    [Level]    [Message]    [JSON Data (optional)]

Example log entries:

2025-10-02 21:34:29Z    INFO    Audit log started for MyScript
2025-10-02 21:34:30Z    SUCCESS    Resource created    {"ResourceId":"vm-001","Location":"East US"}
2025-10-02 21:34:31Z    WARNING    Deprecated API used
2025-10-02 21:34:32Z    INFO    Audit log completed

Log File Naming

Log files are automatically named using the pattern:

[YYYYMMDDHHMMSS]-[ScriptName]-[ComputerName]-[Username].log

Example: 20251002213429-MyScript-WORKSTATION-john.log

Log Levels

• Info: General informational messages
• Success: Successful operations
• Warning: Warning conditions that don't stop execution
• Error: Error conditions
• Verbose: Detailed information for troubleshooting
• Debug: Debug-level information

Requirements

• PowerShell 5.1 or later
• Write permissions to the log directory

Examples

Basic Logging

Import-Module ".\AuditLogger.psm1"

Start-AuditLog
Write-AuditLog -Message "Process started" -Level Info
Write-AuditLog -Message "Process completed successfully" -Level Success
Stop-AuditLog

Advanced Logging with Data

Import-Module ".\AuditLogger.psm1"

$logPath = Start-AuditLog -ScriptName "DataMigration"

$migrationData = @{
    SourceTable = "Users"
    DestinationTable = "UserProfiles"
    RecordCount = 1500
    Duration = "00:02:30"
}

Write-AuditLog -Message "Data migration completed" -Level Success -Data $migrationData

$finalLogPath = Stop-AuditLog
Write-Host "Migration log saved to: $finalLogPath"

Error Handling

Import-Module ".\AuditLogger.psm1"

Start-AuditLog

try {
    # Some operation that might fail
    Write-AuditLog -Message "Starting risky operation" -Level Info
    throw "Something went wrong"
} catch {
    Write-AuditLog -Message "Operation failed: $($_.Exception.Message)" -Level Error -Data @{ StackTrace = $_.ScriptStackTrace }
}

Stop-AuditLog

License

Copyright (c) Ray .M. All rights reserved.

Author

Ray .M

Version

1.0.0