swiftLogger

A PowerShell module for comprehensive logging with optional syslog integration. Supports RFC5424/RFC3164, JSON formatting, IPv6, and intelligent UDP/TCP/TLS fallback. Works standalone for local logging or with enterprise syslog servers.

Features

Local-Only Mode: Use for file/console logging without any syslog configuration
RFC5424 & RFC3164 Compliance: Full support for both modern and legacy syslog protocols
JSON Structured Logging: Generate structured JSON log entries with comprehensive context
Multi-Format Output: Plain text .log or structured .json files (configurable per-call or globally)
IPv6 Support: Works with both IPv4 and IPv6 addresses with automatic detection
Intelligent Transport Fallback: TCP/TLS with automatic fallback to UDP on failure
Colored Console Output: Color-coded log levels (Error, Warning, Success, General, Debug)
Pipeline Support: -PassThru switch returns log entry objects for downstream processing
Quiet Mode: Suppress console output globally or per-call
Connection Timeouts: Configurable timeouts prevent hangs on unreachable syslog servers
Configuration Management: Query, validate, and reset configuration with helper functions
Structured Data Support: Create RFC5424 structured data elements with custom SDIDs

Installation

Install from the PowerShell Gallery:

Install-Module -Name swiftLogger

Quick Start

1. Configure Logging (Local Only)

For simple local logging without syslog:

Set-LogConfiguration -LogFilePath "C:\Logs" `
                     -LogName "MyApplication" `
                     -ScriptName "MyScript" `
                     -ScriptVersion "1.0"

1b. Configure with Syslog (Optional)

To also send logs to a syslog server:

Set-LogConfiguration -LogFilePath "C:\Logs" `
                     -LogName "MyApplication" `
                     -ScriptName "MyScript" `
                     -ScriptVersion "1.0" `
                     -SysLogServer "syslog.example.com" `
                     -SysLogPort 514 `
                     -SendSyslog $true

2. Write Logs

Use the Write-Log function with different log types:

Write-Log -msg "Application started" -type "general"
Write-Log -msg "Processing file" -type "success"
Write-Log -msg "Something went wrong" -type "error"
Write-Log -msg "Detailed debug info" -type "debug"
Write-Log -msg "Check this condition" -type "warn"

3. Send Direct Syslog Messages

For more control over syslog parameters:

Invoke-Syslog -EndPoint "syslog.example.com" `
              -Port 514 `
              -Message "Custom syslog message" `
              -Facility 16 `
              -Severity 5 `
              -Transport "TCP"

4. Create Structured Syslog Data

Build RFC5424 structured data elements:

$structData = New-StructuredSyslogData -SDID "exampleSDID@32473" `
                                       -Params @{
                                           user = "john.doe"
                                           action = "login"
                                           result = "success"
                                       }

Detailed Function Reference

Set-LogConfiguration

Configures global logging settings used by other functions.

Parameters:

Parameter	Type	Required	Description
`AppName`	String	No	Application name identifier, included in JSON logs and syslog messages.
`LogFilePath`	String	No	Directory path where log files will be created.
`LogName`	String	No	Base name for log files (without extension).
`ScriptName`	String	No	Name of the calling script, included in logs.
`ScriptVersion`	String	No	Version of the calling script.
`JsonLogging`	Boolean	No	Output JSON format logs. Default: $false
`QuietMode`	Boolean	No	Suppress console output globally. Default: $false
`SysLogServer`	String	No	Hostname or IP of syslog server (optional).
`SysLogPort`	Integer	No	Syslog server port (514 for UDP/TCP, 6514 for TLS).
`SysLogRFC`	String	No	Syslog protocol: `RFC5424` (default) or `RFC3164`.
`SendSyslog`	Boolean	No	Send messages to syslog server. Default: $false
`ConnectionTimeoutSeconds`	Integer	No	Timeout for TCP/TLS connections. Default: 5

Example:

Set-LogConfiguration -AppName "MyApplication" `
                     -SysLogServer "10.0.0.50" `
                     -SysLogPort 514 `
                     -SysLogRFC "RFC5424" `
                     -LogFilePath "C:\Logs\MyApp" `
                     -LogName "Application" `
                     -ScriptName "Deploy-Script" `
                     -ScriptVersion "2.1.0" `
                     -SendSyslog $true `
                     -JsonLogging $true

Write-Log

Writes log entries to file and optionally to syslog server. Handles colored console output, file logging, JSON logging, and syslog delivery.

Parameters:

Parameter	Type	Required	Default	Description
`msg`	String	Yes	-	The log message text to write.
`type`	String	Yes	-	Log level/type. Valid values: `error`, `warn`, `success`, `general`, `debug`
`SendSysLog`	Boolean	No	$Global:SendSyslog	Override global setting to send this message to syslog.
`OutputJson`	Boolean	No	$Global:JsonLogging	Override global setting to output this message in JSON format.
`Quiet`	Switch	No	$false	Suppress console output for this message only.
`PassThru`	Switch	No	$false	Return the log entry object for pipeline processing.

Log Type Color Mapping:

Type	Console Color	Syslog Severity	Description
`error`	Dark Red on Red	3 (Error)	Critical error condition
`warn`	Dark Yellow on Yellow	4 (Warning)	Warning condition
`success`	Dark Green on Green	5 (Notice)	Successful operation
`general`	Black on White	6 (Info)	General informational message
`debug`	Dark Blue on Blue	7 (Debug)	Debug-level detail

Output Files:

Plain Text: {LogFilePath}\{LogName}.log - Used when OutputJson is false.
JSON Format: {LogFilePath}\{LogName}.json - Used when OutputJson is true. Contains structured JSON with metadata.

JSON Log Entry Example:

{"timestamp":"2025-12-04 16:35:22","level":"error","message":"Database connection failed","appName":"MyApplication","script":"Deploy-Script","version":"2.1.0","computerName":"SERVER01"}

Message ID Mapping:

When using Write-Log with the syslog feature enabled, MsgID is automatically mapped based on the log type:

Log Type	MsgID	Purpose
`error`	ERR	Error condition messages
`warn`	WRN	Warning condition messages
`success`	SUC	Successful operation messages
`general`	INF	General informational messages
`debug`	DBG	Debug-level detail messages

Example:

Write-Log -msg "User authentication successful" -type "success"
Write-Log -msg "Retry attempt 3 of 5" -type "debug" -SendSysLog $true

Invoke-Syslog

Sends syslog messages directly to a syslog server with full RFC5424/RFC3164 support, multiple transport options, and intelligent fallback.

Parameters:

Parameter	Type	Required	Default	Description
`EndPoint`	String	Yes	-	Hostname or IP address of the syslog server. Can be IPv4, IPv6, or FQDN.
`Port`	Integer	Yes	-	Port number of the syslog server (514 for standard, 6514 for TLS).
`Message`	String	Yes	-	The syslog message body.
`Facility`	Integer	No	1 (User-level)	RFC5424 facility code (0-23). Defines message source category.
`Severity`	Integer	No	6 (Informational)	RFC5424 severity level (0-7). Defines message priority.
`AppName`	String	No	"swiftLogger"	Application name in syslog header. Identifies the source application. Set via `Set-LogConfiguration`.
`ProcID`	String	No	$PID (current process ID)	Process identifier in syslog header.
`MsgID`	String	No	"PSLogging"	Message identifier in syslog header for tracking/correlation. Auto-mapped by `Write-Log` based on log type.
`StructuredData`	String	No	"-"	RFC5424 structured data element (e.g., `[exampleSDID@32473 key1="value1"]`). Use "-" for none.
`RFC`	String	No	"RFC5424"	Syslog protocol version. Valid values: `RFC5424` (modern), `RFC3164` (legacy).
`Transport`	String	No	"UDP"	Primary transport protocol. Valid values: `UDP`, `TCP`, `TLS`
`IsJson`	Boolean	No	$false	If $true, forces specific structured data tag `[json@32473 tag="json"]` if not otherwise specified.

Facility Codes (0-23):

Code	Name	Purpose
0	kernel messages	Operating system kernel
1	user-level messages	User-level applications
2	mail system	Mail system
3	system daemons	System daemons
4	security/authorization	Security/authorization messages
16	local use 0 (local0)	Local application use
17-23	local use 1-7 (local1-7)	Local application use

Severity Codes (0-7):

Code	Name	Description
0	Emergency	System unusable
1	Alert	Action must be taken immediately
2	Critical	Critical condition
3	Error	Error condition
4	Warning	Warning condition
5	Notice	Normal but significant condition
6	Informational	Informational message
7	Debug	Debug-level detail

Transport Behavior:

UDP: Connectionless, fast, best-effort delivery. Tries first in fallback chain.
TCP: Connection-based, reliable delivery. Falls back to UDP on failure.
TLS: Encrypted TCP connection with certificate validation. Falls back to UDP on failure.

Example - Basic Syslog:

Invoke-Syslog -EndPoint "syslog.corp.com" `
              -Port 514 `
              -Message "Application startup completed successfully"

Example - With Severity and Facility:

Invoke-Syslog -EndPoint "syslog.corp.com" `
              -Port 514 `
              -Message "Database connection failed" `
              -Facility 16 `
              -Severity 3 `
              -AppName "DatabaseService"

Example - RFC3164 Legacy Format:

Invoke-Syslog -EndPoint "legacy-syslog.internal" `
              -Port 514 `
              -Message "Old system event" `
              -RFC "RFC3164" `
              -Transport "UDP"

Example - With Structured Data:

$structData = New-StructuredSyslogData -SDID "user@32473" `
                                       -Params @{uid="12345"; username="jdoe"}
Invoke-Syslog -EndPoint "syslog.corp.com" `
              -Port 514 `
              -Message "User login event" `
              -Facility 4 `
              -Severity 6 `
              -StructuredData $structData

New-StructuredSyslogData

Creates RFC5424-compliant structured data elements for inclusion in syslog messages.

Parameters:

Parameter	Type	Required	Description
`SDID`	String	Yes	Structured Data ID (SDID). Custom SDIDs should follow format: `name@enterpriseNumber`. Example: `exampleSDID@32473`
`Params`	Hashtable	Yes	Key-value pairs containing the structured data fields. Values are automatically quoted.

Returns: String in format [SDID key1="value1" key2="value2"]

Example:

$structData = New-StructuredSyslogData -SDID "user@32473" `
                                       -Params @{
                                           username = "jdoe"
                                           action = "login"
                                           result = "success"
                                           ipaddress = "192.168.1.100"
                                       }
# Output: [user@32473 username="jdoe" action="login" result="success" ipaddress="192.168.1.100"]

Get-LogConfiguration

Retrieves the current SwiftLogger configuration settings.

Parameters:

Parameter	Type	Required	Description
`AsHashtable`	Switch	No	Return configuration as a hashtable instead of PSCustomObject.

Example:

Get-LogConfiguration
# Returns current configuration as PSCustomObject

Get-LogConfiguration -AsHashtable
# Returns configuration as hashtable for export

Test-LogConfiguration

Validates the current SwiftLogger configuration.

Parameters:

Parameter	Type	Required	Description
`RequireSyslog`	Switch	No	Also validate syslog-specific settings.
`ThrowOnError`	Switch	No	Throw an exception instead of returning $false if validation fails.

Example:

if (Test-LogConfiguration) {
    Write-Log -msg "Configuration is valid" -type "success"
}

# Validate and throw on error
Test-LogConfiguration -ThrowOnError

Reset-LogConfiguration

Resets the SwiftLogger configuration to default (unconfigured) state.

Example:

Reset-LogConfiguration
# Clears all SwiftLogger settings

Advanced Usage Examples

Complete Logging Workflow

# 1. Configure once at script start
Set-LogConfiguration -SysLogServer "syslog.corp.com" `
                     -SysLogPort 514 `
                     -LogFilePath "C:\Logs\Deployment" `
                     -LogName "Deploy-2025-12-04" `
                     -ScriptName "Deploy-WebApp" `
                     -ScriptVersion "3.2.1" `
                     -SendSyslog $true `
                     -JsonLogging $true

# 2. Use Write-Log throughout script
try {
    Write-Log -msg "Starting application deployment" -type "general"
    
    # Do work...
    
    Write-Log -msg "Application deployed successfully" -type "success"
} catch {
    Write-Log -msg "Deployment failed: $_" -type "error"
}

# 3. Send audit event with structured data
$auditData = New-StructuredSyslogData -SDID "audit@32473" `
                                      -Params @{
                                          action = "deploy"
                                          user = $env:USERNAME
                                          target = "prod-web-01"
                                          status = "completed"
                                      }
Invoke-Syslog -EndPoint "syslog.corp.com" `
              -Port 514 `
              -Message "Production deployment completed" `
              -Facility 4 `
              -Severity 5 `
              -StructuredData $auditData

Multi-Transport Scenario

# Try encrypted TLS first, fallback to TCP, then UDP
Invoke-Syslog -EndPoint "secure-syslog.internal" `
              -Port 6514 `
              -Message "Sensitive audit event" `
              -Transport "TLS" `
              -Facility 4 `
              -Severity 2

JSON-Only Logging

# Log structured JSON for downstream processing
Set-LogConfiguration -LogFilePath "C:\Logs\API" `
                     -LogName "rest-api" `
                     -ScriptName "API-Service" `
                     -ScriptVersion "1.0" `
                     -JsonLogging $true

Write-Log -msg "Incoming request from 192.168.1.50 for /api/users" -type "general"
# Creates JSON in .json file: {"timestamp":"2025-12-04 16:35:22",...}

Global Variables

After calling Set-LogConfiguration, the following global variables are available:

$Global:AppName - Application name identifier
$Global:SysLogServer - Syslog server hostname/IP
$Global:SysLogPort - Syslog server port
$Global:SysLogRFC - Syslog RFC version
$Global:LogFilePath - Log file directory
$Global:LogName - Log file name
$Global:ScriptName - Calling script name
$Global:ScriptVersion - Script version
$Global:SendSyslog - Whether to send to syslog
$Global:JsonLogging - Whether to use JSON format

Requirements

PowerShell 5.1 or higher
Network access to syslog server (for syslog functionality)
Write permissions to log file path
For TLS transport: Valid SSL/TLS certificates on syslog server

License

This project is licensed under the GNU General Public License v3.0 - see GNU GPL-3.0 for details.

Author

Scott Powdrill

Support

For issues, feature requests, or contributions, please visit the project repository or the PowerShell Gallery package page.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
1.0.0.4		1.0.0.4
1.0.0.5		1.0.0.5
.gitattributes		.gitattributes
LICENSE		LICENSE
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

swiftLogger

Features

Installation

Quick Start

1. Configure Logging (Local Only)

1b. Configure with Syslog (Optional)

2. Write Logs

3. Send Direct Syslog Messages

4. Create Structured Syslog Data

Detailed Function Reference

Set-LogConfiguration

Write-Log

Invoke-Syslog

New-StructuredSyslogData

Get-LogConfiguration

Test-LogConfiguration

Reset-LogConfiguration

Advanced Usage Examples

Complete Logging Workflow

Multi-Transport Scenario

JSON-Only Logging

Global Variables

Requirements

License

Author

Support

About

Uh oh!

Releases

Packages

Languages

License

Jellman86/SwiftLogger

Folders and files

Latest commit

History

Repository files navigation

swiftLogger

Features

Installation

Quick Start

1. Configure Logging (Local Only)

1b. Configure with Syslog (Optional)

2. Write Logs

3. Send Direct Syslog Messages

4. Create Structured Syslog Data

Detailed Function Reference

Set-LogConfiguration

Write-Log

Invoke-Syslog

New-StructuredSyslogData

Get-LogConfiguration

Test-LogConfiguration

Reset-LogConfiguration

Advanced Usage Examples

Complete Logging Workflow

Multi-Transport Scenario

JSON-Only Logging

Global Variables

Requirements

License

Author

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages