Posh-GraylogLogger

Powershell Modul for logging your script logs into GrayLog via GELF.

ATTENTION! This module is experimental only at the moment. i'll try to get it stable as soon as possible! therefore if you enable $DebugPreference = 'Continue' you will see a lot of messages for debugging purposes

Description

this repository contains a powershell module for writting log entries into graylog via gelf http (tcp/udp work in progress). following features are implemented:

• simple text logging
• structured logging

TODO's

• global logging properties
• glogal logging properties as hashtable
• http gelf support
• basic logging and structured logging
• additional log properties per request
• add tcp and udp support
• tcp tls support?

more to come...

Functions

New-GLServerConnection

Creates connection to graylog server

Parameter	ParameterSet	Mandatory	Type	DefaultValue	Description
Server	Server	true	string	-	servername or ip
Port	Server	true	int	-	port of your gelf http endpoint
TransportMode	Server	true	GLTransportMode	Http	transport mode for logging (https/http/tcp/udp)
Endpoint	Server	false	string	gelf	your endpoint name (text behind :Port/...)
ConfigFile	ConfigFile	false	switch	false	use this switch if you wanna use a config file for parmeters
ConfigFilePath	ConfigFile	false	string	-	if you wanna provide a custom settings file (full path)

Configfile

the default config file is called psgrayloglogger.settings which is basically a json file and looks like this

{
    "Server" : "yourserver",
    "Port" : 12201,
    "Endpoint" : "gelf",
    "TransportMode" : "Http"
}

default path is the powershell module directory.

Add-GLGlobalLogProperty

Adding a global logging property which will be appended on each log entry

Parameter	Mandatory	Type	DefaultValue	Description
PropertyName	true	string	-	name of the property
PropertyValue	true	object	-	value of the property (will be converted to string value)

Add-GLGlobalLogProperties

Adding multiple global logging properties which will be appended on each log entry

Parameter	Mandatory	Type	DefaultValue	Description
Properties	true	hashtable	-	hashtable with properties

Write-GLLog

Creates a log entry and writes it into graylog

Parameter	Mandatory	Type	DefaultValue	Description
LogLevel	true	GLLogLevel	-	loglevel of current entry
LogText	true	string	-	logtext (simple or structured)
PropertyValues	false	object	-	if Logtext is structured you have to provide the properties to replace the placeholders
AdditionalProperties	true	object	-	additional properties which will be indexed into graylog but not shown in the logtext (scope logentry only) Hashtable

you can also add custom objects to the PropertyValues and AdditionalProperties. PSGraylogLogger will try to convert these to json and adds these values to the logtext or as additional property

Set-GLDefaultCmdlets

Overwrites the basic cmdlets Write-Debug, Write-Verbose, Write-Output, Write-Warning and Write-Error. As a result you are able to send every message written by these cmdlets additional to the graylog server.

Parameter	Mandatory	Type	DefaultValue	Description
Enable	false	switch	-	imports the overwrite functions
Disable	false	switch	-	removes the overwrite functions

Examples

import the module

Import-Module PSGrayLogLogger

set connection to graylog server with 'server' parameterset

New-GLServerConnection -Server <SERVERNAME or IP> -Port <GELF Port> -Endpoint <Endpointname (Default 'gelf')> -TransportMode Http
New-GLServerConnection -Server <SERVERNAME or IP> -Port <GELF Port> -TransportMode Udp

set connection to graylog server with 'configfile' parameterset

New-GLServerConnection -ConfigFile #using default filename 'psgrayloglogger.settings' and default path
New-GLServerConnection -ConfigFile -ConfigFilePath "C:\dev\myconfig.json" #using custom config file

add global log properties to context. these properties will be added to each log entry you will fire up

Add-GLGlobalLogProperty -PropertyName "ScriptName" -PropertyValue "TestScript.ps1"

this will add a property called ScriptName with value TestScript.ps1 to every log entry you will create

add multiple global log properties to context. these properties will be added to each log entry you will fire up

Add-GLGlobalLogProperties -Properties @{PropertyOne = "Hello"; PropertyTwo = "World"}

this will add a two properties called PropertyOne/PropertyTwo with values Hello/World to every log entry you will create

create simple log entry

Write-GLLog -LogLevel Information -LogText "This is a simple logtext" 

Screenshot

create a structured log entry

Write-GLLog -LogLevel Information -LogText "Current status from api: {apiStatus}" -PropertyValues @('up')

this produces a log with logtext: "Current status from api: up" and adds a property to graylog called apiStatus with value up

Screenshot

create a structured log with simple logtext and additional properties

Write-GLLog -LogLevel Information -LogText "This is a simple logtext" -AdditionalProperties @{TimeElapsedSeconds = 12.5}

this produces a log with logtext: "This is a simple logtext" and adds a property to graylog called TimeElapsedSeconds with value 12.5

Screenshot

create a structured log with and additional properties

Write-GLLog -LogLevel Information "Current status from api: {apiStatus}" -PropertyValues @('up') -AdditionalProperties @{TimeElapsedSeconds = 12.5}

this produces a log with logtext: "Current status from api: up" and adds a two properties to graylog called apiStatus with value up and TimeElapsedSeconds with value 12.5

Screenshot