en-US/about_uLog.help.txt
|
TOPIC
uLog module help SHORT DESCRIPTION This module eases management of logs for PowerShell scripts. It is also functional on Linux platform. It aims to be used by administrators to help them add logging to there Scripts. LONG DESCRIPTION It provides different log handlers, like console, file, eventlog, mail. It aims to be easy to use, by providing automatic initialization handlers. Hence, using Log-Info for instance, will generate a default log handler. You can still configure the handlers you need, so you can log on the console, in a file and the eventlog at the same time. Formatters provide the layout, for example on the console and in a file, you would expect the message to be <date><severy><message>. But in the eventlog you would expect to find the source that emit the message, so path to the script is included in the log. You can -Include/-Exclude handlers, useful for instance if you create a mail handler an only write to it for the major steps in the script. You can retain handlers that provide this functionality by setting Keep=$true. The purpose is for example a mail or the evenlog where you do not want to send a mail for every action, but only send the log content at the end of the script. The following sections describe the different usage and scenarios USAGE The best usage it to install the module on your platforms, logging is then very easy to use, just by using a Log-<level> function, or by configuring the log manager object. The log location is displayed on the console so even if you don’t configure any handler, you know where the log is placed. FIRST LOG The following code present the simpliest usage: Log-Info -Message 'Hello' Log-Warning -Message 'Attention' -Indent 3 The first call creates a default handler regarding the type of script, ps1, or psm1, see later. It creates a global variable uLOG, so you do not need to specify the log object at each time you write to it. DEFAULT LOGGING Regarding the $MyInvocation.ScriptName value : - The log is written on the console if the value contains a path to a .ps1 file, or is empty (run from command prompt). - It is written to the eventlog if the value contains a path to a .psm1. For example, directly using Log-Info -Message 'Hello' will write "Hello" on the console if used from a script, and write "Hello" in the eventlog. DEFAULT LOGGING FOR EVENTLOG If the script is run with administrative privilege, the event is created in the "Application" eventlog. A source named after the script/module's name is created. If the script is not run with administrative privilege, the user cannot create a source, so the "Windows PowerShell" source is used. If an Id is used, 1000 will be added, so it does not conflict with "Windows PowerShell" Ids. Using "Windows PowerShell" log is not perfect because the source ids will Will not be known and a message is generated in the log. DEFAULT LOGGING FOR FILE If the script is run with administrative privilege, the log is located in %SystemRoot%\Logs. If the script is not run with administrative privilege, the module tries to create the log in the script folder, otherwise it creates the log in the %temp% folder. LOG LEVELS Logging levels are specified globally or for each handler, if it needs to be refined. Log levels are implemented has a .Net type [uLogLevel]. So to use it, type [uLogLevel]:: and autocomplete will propose the levels available. FORMATTERS Formatters handle the layout of logs. They can be set using the .Net type [uLogFormatter]. Default layout are proposed for each handler, but others are available. For example ccmtrace will use a SCCM log format. DEVELOPMENT The folder structure is the following: ULOG ├───en-US ├───formatters ├───handlers └───test - en-US: contains the help for the about_ulog command. - formatters: contains a module for each layout. If a module is added, it should also be added in the formatters.psd1 to be available. - handlers: contains a module for each handler. If a module is added, it should also be added in the handlers.psd1 to be available. - test: contains examples script. EXAMPLES KEYWORDS ulog log logging trace |