bin/SnsPsScriptsMonitoring.xml
|
<?xml version="1.0"?>
<doc> <assembly> <name>SnsPsScriptsMonitoring</name> </assembly> <members> <member name="T:SnsPsScriptsMonitoring.DisableSnsScriptMonitoring"> <summary> <para type="synopsis">Disables A Monitoring Entry In The Monitoring DataBase.</para> <para type="description">Disables A Monitoring Entry In The Monitoring DataBase.</para> <para type="description"></para> <para type="description"></para> <para type="description"> Whenever A Script Fails It Either Have Its Process Stuck Without Being Able To Continue Further Or Its Process Completely Stop. In Both Cases The Script Cannot Notify About The Failure Nor Continue Further. From That Perspective Whenever We Have Automation Scripts Doing Business Critical Tasks We Need To Monitor Their Running Using Another Script Named Here Monitoring Script. </para> <para type="description"> Detecting A Failed Script Is Relatively Easy, Whenever We Have Failed Script Its Process Stops And No Longer Could Be Enumerated With The Machines Processes. A Monitoring Script Could Detect The Failure And Either Report Or Take Actions. However That's Not The Case With The Stuck Scripts. Their Processes Are Still Running And Just Doing Nothing. A Monitoring Script Could Be Easily Mistaken That A Stuck Script Is Running As Usual. Monitoring Of Stuck Scripts Can Be Achieved Via Using Of Transcript Files By The Monitored Scripts Which To Be Updated Regularly. The Monitored Script Could Check The LastWriteTime Of Those Transcript Files And Based On A Threshold Could Decide Whether Specific Monitored Script Is Stuck Or Continue To Be Updated. </para> <para type="description"> The Module Requires The Monitored Scripts To Write Output Regularly On Either Transcript Or Log File, Named Here Monitored File. From Within The Monitored Script Must Be Created A Monitoring Entry Kept In A Monitoring DataBase About The Monitored File Using Enable-SnsScriptMonitoring CmdLet. At The End Of The Monitored Script Running It Must Run Disable-SnsScriptMonitoring To Indicate It Is Completed Successfully And No Longer Needs To Be Monitored. Whenever Disabling From Monitoring Is Omitted The Module Still Can Identify Successfully Completed Scripts Using The Monitored Script Exit Code Supplied To Its Scheduled Task. In Order This To Work As Expected The Monitoring Entry Must Have The Correct Scheduled Task Path And Access Rights To Verify Whether Its State Is Ready And The Last Exit Code Is 0 (Exit Without Failures). Additionally The Monitored Script Must Supply That Information To Its Task. Whenever The Disabling From Monitoring Is Omitted Could Lead To Unexpected Results. </para> <para type="description"> We Use Get-SnsScriptMonitoringEntry CmdLet From Within The Monitoring Script To Monitor The Monitored Scripts. The CmdLet Is Capable To Automatically Restart The Failed Scripts, If Needed And The Prerequisites For That Are Met. </para> <para type="description"> Because The Monitored Script Could Be Stuck Or Failed We Need Additional Script Executed On A Schedule To Run Get-SnsScriptMonitoringEntry In Order To Monitor The Monitored Scripts Operation. The Monitoring Script Must Be Reliable And Not Resource Intensive. The Reliability And Performance Considerations Are The Main Reason This Module To Be Developed As Binary PowerShell Module. </para> <para type="description"> The "SnsPsScriptsMonitoring" PowerShell Module Contains All The CmdLets Required For Enable Monitoring, Disable Monitoring, And Being Monitored By A Dedicated Monitoring Script. All The Needed CmdLets Are In One Place And There Is No Monitoring And Monitoring Agent PowerShell Modules. </para> <para type="description"> The Module Requires The Monitored Scripts To Comply With The Following Requirements: </para> <para type="description"> - The Monitored Scripts Must Update Periodically Transcript Or Log Files. Whenever Those Files Are Not Modified For Specified Period Of Time Their Scripts Are Considered As Stuck. The Monitoring CmdLet Does Not Read The Content Of The Transcript Files. We Need The Monitoring Processes To Be Fast As Possible. Reading File Content Is Not Among The Operations Considered As Fast. The Account That Running The Get-SnsScriptMonitoringEntry CmdLet Requires NTFS Permissions Over The Monitored Files To Read Their LastWriteTime. </para> <para type="description"> - To Identify Failed Script Processes The Get-SnsScriptMonitoringEntry CmdLet Verifies Whether The Script Process Is Still Running. This Requires The Correct Process ID Of The Script Process To Be Present In The Monitoring Entry. The Process ID's Are Assigned By The Operating System Dynamically, Therefore They Cannot Be Specified At The Time When The Monitored Script Is Written And Provided To Enable-SnsScriptMonitoring CmdLet. However The PowerShell Can Dynamically Identify Its Own Process, And The Enable-SnsScriptMonitoring CmdLet Do So Dynamically. Therefore It Is Mandatory It To Be Run From The Monitored Script. In That Way In The Monitoring Entry Will Be Present The Correct Process ID Of The Monitored Script Process. </para> <para type="description"> Get-SnsScriptMonitoringEntry Can Identify The Properly Running Scripts. Depending On The Specified Parameters And The Information Available In The Monitoring Entry Could Action The Enumerated Failed And Or Stuck Scripts Via Stopping The Monitored Script Process And Restarting Of The Monitored Script Scheduled Task. To Ensure This Feature Is Available Make Sure As Much As Possible Information Is Provided When The Monitored Script Is Enabled For Monitoring. </para> <para type="description"> The CmdLets In This Module Can Work Only Locally Which Means That The Monitored Scripts And The Monitoring Script Must Run On The Same Machine. </para> <para type="description"></para> <para type="description"></para> <para type="description"> The SnsPsScriptsMonitoring Uses An SQLite V3 Serverless DataBase To Keep Track Of The Monitored Scripts Information. When The PowerShell Module Is Loaded For The First Time It Automatically Creates The Monitoring DataBase At The Following Location: </para> <para type="description">"%ProgramData%\SnsPsScriptsMonitoring\SnsScrMon.db"</para> <para type="description"> Because Creation Of Folders And Files Within That Folder Requires Elevated Access Rights The First Load Of The Module Must Be In Elevated PowerShell Process. The Consequent Loads Of The Module Does not Require Elevated Mode, Except Specific Feature Requires It, And The Feature Itself Is Required. For Example Restart Of The Failed Scripts Requires The Monitored Script To Be Run In Elevated Mode, But The User Might Need The Failures To Be Reported And Not Actioned. In That Case There Is No Point To Run The Monitoring Script In Elevated Mode. </para> <para type="description"> The Information Kept In The Monitoring DataBase Is: "Machine", "Directory", "Script", "MonitoredFile", "Task", "Pid", "Threshold", "Enabled" And "Disabled". </para> <para type="description"> "Machine" Is The Fully Qualified Domain Name (FQDN) Of The Machine Where The Monitored Script Is Running. This Is Automatically Enumerated By Enable-SnsScriptMonitoring CmdLet And No User Input Is Possible. </para> <para type="description"> "Directory" Is The Folder Where The Monitored File Reside. This Information Is Automatically Enumerated From The Specified Monitored File And No User Input Is Possible. </para> <para type="description"> "Script" Is The .PS1 FileName Of The Monitored Script. This Information Is Automatically Enumerated. In Order The Enumeration To Work Correctly, Enable-SnsScriptMonitoring CmdLet Must Be Run From The Monitored Script. The "Script" Name Is Used For RestartFailed Feature, And For The Automatic Disabling From Monitoring Of Failed Scripts When The Failed Script Is Restarted And Newer Monitoring Entry Is Created About New Monitoring File Of The Same Script. "Script" Is Not Mandatory However When The Value Is Missing Or Incorrect Those Features Will Not Work. In Case The CmdLet Is Included In Scripts PowerShell Modules, The CmdLet Will Wrongly Identify The Script Module File As Monitored Script, From That Perspective The CmdLet Must Be Called From The Monitored Script Main .PS1 File. </para> <para type="description"> "MonitoredFile" Is The Full Absolute UNC Path To The Specified Monitored File. This Must Be Explicitly Specified To Enable-SnsScriptMonitoring CmdLet. There Is No Automatic Enumeration. </para> <para type="description"> "Task" Is The Full Path Of The Monitored Script Windows Scheduled Task. This Information Is Not Mandatory However Without It No Automatic Restart Of The Failed Scripts Is Possible. The Module Can Auto Enumerate It With Limited Success. It Is Preferable That "Task" Is Explicitly Specified To Enable-SnsScriptMonitoring CmdLet. </para> <para type="description"> "Pid" Is The Process ID Of The Script's PowerShell Process. This Is Automatically Enumerated. In Order The Auto Enumeration To Identify The Correct Process, The Enable-SnsScriptMonitoring Must Be Run From The Monitored Script. </para> <para type="description"> "Threshold" Is The Time Interval In Minutes About Inactivity Of The Monitored Script Used As A Threshold To Identify Whether It Is Stuck. The Inactivity Is Measured Via Reading The LastWriteTime Of The Script Transcript Or Log File Specified As Monitored File. For The Correct Identifying Please Make Shure That The Monitored Script Updates Periodically The Specified Monitored File. The Threshold Shall Be Considered Carefully Depending On The Intervals That The Monitored File Is Updated. Wrong Threshold Could Cause False Positives And Working Script To Be Stopped And Restarted In The Middle Of A Heavy Task. </para> <para type="description"> "Enabled" Is The DateTime When The Monitoring Entry Is Created, Converted To FileTime. </para> <para type="description"> "Disabled" Is The DateTime When The Monitoring Entry Is Disabled And The Monitored Script Stopped To Be Monitored, Converted To FileTime. Disabling From Monitoring Might Happen In Three Scenarios: </para> <para type="description"></para> <para type="description"> -- When The Monitored Script Finish Successfully. This Requires At The End Of The Monitored Script Have To Be Called Disable-SnsScriptMonitoring CmdLet. The CmdLet Updates The Monitoring Entry Via Specifying The Current DateTime Converted To FileTime In "Disabled" Column Of The Monitoring Entry. From That Moment On The Monitored File Updates And The Script Process Running Are No Longer Evaluated. </para> <para type="description"> -- When The Monitored Script Fail And AutoDisable Feature Is Used And New Instance Of The Monitoring Script Is Started And Enabled For Monitoring. Then The Failed Old Instance Will Be Disabled From Monitoring. The Way The Failed Script Is Restarted Does Not Make Any Difference. This Feature Will Work As Long As The Monitored Entry Have The Correct Values In "Script", "Directory" And "Task" Properties. It Is Not Related With RestartFailed Feature. </para> <para type="description"> -- When The User Runs Manually Disable-SnsScriptMonitoring CmdLet. This Is The Only Option To Stop The Reports For Failed Scripts That Did Not Disabled Themselves From Monitoring And The Prerequisites For AutoDisable Feature Are Not Met. For Example When The Scheduled Task Is Not Provided And Its Enumeration Failed. </para> <para type="description"> During The Module Load The Outdated Monitoring Entries Are Deleted And The Monitoring Database Is Defragmented And Shrank To Release Its White Space To The Operating System. For Outdated Entries Are Considered The Ones Which Are Disabled More Than 14 Days Ago. Enabled Entries Are Never Threated As Outdated Regardless Of Their Age. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov</para> <para>THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK</para> <para>OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.</para> <para></para> <para></para> <para></para> </description> </item> </list> <example> <code> Disable-SnsScriptMonitoring -Path "C:\Transcript.txt"; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry]$objEntry = Disable-SnsScriptMonitoring -Path "C:\Transcript.txt" ` -PassThru; </code> <para></para> </example> </summary> <para type="link" uri="https://github.com/svesavov/SnsPsScriptsMonitoring"> svesavov / SnsPsScriptsMonitoring - </para> <para type="link" uri="https://www.powershellgallery.com/packages/SnsPsScriptsMonitoring/"> PowerShell Gallery - </para> <para type="link" uri="https://www.linkedin.com/in/svetoslavsavov"> Svetoslav Savov on LinkedIn - </para> <para type="link" uri="https://sqlite.org/index.html"> SQLite V3 - </para> </member> <member name="P:SnsPsScriptsMonitoring.DisableSnsScriptMonitoring.Path"> <summary> <para type="description">Specifies The Full Absolute UNC File Path To The Monitored Script Transcript File.</para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.DisableSnsScriptMonitoring.PassThru"> <summary> <para type="description">Specifies To The CmdLet To Revert A MonitoringEntry Object.</para> </summary> </member> <member name="T:SnsPsScriptsMonitoring.EnableSnsScriptMonitoring"> <summary> <para type="synopsis">Creates A Monitoring Entry In The Monitoring DataBase.</para> <para type="description">Creates A Monitoring Entry In The Monitoring DataBase.</para> <para type="description"></para> <para type="description"></para> <para type="description"> Whenever A Script Fails It Either Have Its Process Stuck Without Being Able To Continue Further Or Its Process Completely Stop. In Both Cases The Script Cannot Notify About The Failure Nor Continue Further. From That Perspective Whenever We Have Automation Scripts Doing Business Critical Tasks We Need To Monitor Their Running Using Another Script Named Here Monitoring Script. </para> <para type="description"> Detecting A Failed Script Is Relatively Easy, Whenever We Have Failed Script Its Process Stops And No Longer Could Be Enumerated With The Machines Processes. A Monitoring Script Could Detect The Failure And Either Report Or Take Actions. However That's Not The Case With The Stuck Scripts. Their Processes Are Still Running And Just Doing Nothing. A Monitoring Script Could Be Easily Mistaken That A Stuck Script Is Running As Usual. Monitoring Of Stuck Scripts Can Be Achieved Via Using Of Transcript Files By The Monitored Scripts Which To Be Updated Regularly. The Monitored Script Could Check The LastWriteTime Of Those Transcript Files And Based On A Threshold Could Decide Whether Specific Monitored Script Is Stuck Or Continue To Be Updated. </para> <para type="description"> The Module Requires The Monitored Scripts To Write Output Regularly On Either Transcript Or Log File, Named Here Monitored File. From Within The Monitored Script Must Be Created A Monitoring Entry Kept In A Monitoring DataBase About The Monitored File Using Enable-SnsScriptMonitoring CmdLet. At The End Of The Monitored Script Running It Must Run Disable-SnsScriptMonitoring To Indicate It Is Completed Successfully And No Longer Needs To Be Monitored. Whenever Disabling From Monitoring Is Omitted The Module Still Can Identify Successfully Completed Scripts Using The Monitored Script Exit Code Supplied To Its Scheduled Task. In Order This To Work As Expected The Monitoring Entry Must Have The Correct Scheduled Task Path And Access Rights To Verify Whether Its State Is Ready And The Last Exit Code Is 0 (Exit Without Failures). Additionally The Monitored Script Must Supply That Information To Its Task. Whenever The Disabling From Monitoring Is Omitted Could Lead To Unexpected Results. </para> <para type="description"> We Use Get-SnsScriptMonitoringEntry CmdLet From Within The Monitoring Script To Monitor The Monitored Scripts. The CmdLet Is Capable To Automatically Restart The Failed Scripts, If Needed And The Prerequisites For That Are Met. </para> <para type="description"> Because The Monitored Script Could Be Stuck Or Failed We Need Additional Script Executed On A Schedule To Run Get-SnsScriptMonitoringEntry In Order To Monitor The Monitored Scripts Operation. The Monitoring Script Must Be Reliable And Not Resource Intensive. The Reliability And Performance Considerations Are The Main Reason This Module To Be Developed As Binary PowerShell Module. </para> <para type="description"> The "SnsPsScriptsMonitoring" PowerShell Module Contains All The CmdLets Required For Enable Monitoring, Disable Monitoring, And Being Monitored By A Dedicated Monitoring Script. All The Needed CmdLets Are In One Place And There Is No Monitoring And Monitoring Agent PowerShell Modules. </para> <para type="description"> The Module Requires The Monitored Scripts To Comply With The Following Requirements: </para> <para type="description"> - The Monitored Scripts Must Update Periodically Transcript Or Log Files. Whenever Those Files Are Not Modified For Specified Period Of Time Their Scripts Are Considered As Stuck. The Monitoring CmdLet Does Not Read The Content Of The Transcript Files. We Need The Monitoring Processes To Be Fast As Possible. Reading File Content Is Not Among The Operations Considered As Fast. The Account That Running The Get-SnsScriptMonitoringEntry CmdLet Requires NTFS Permissions Over The Monitored Files To Read Their LastWriteTime. </para> <para type="description"> - To Identify Failed Script Processes The Get-SnsScriptMonitoringEntry CmdLet Verifies Whether The Script Process Is Still Running. This Requires The Correct Process ID Of The Script Process To Be Present In The Monitoring Entry. The Process ID's Are Assigned By The Operating System Dynamically, Therefore They Cannot Be Specified At The Time When The Monitored Script Is Written And Provided To Enable-SnsScriptMonitoring CmdLet. However The PowerShell Can Dynamically Identify Its Own Process, And The Enable-SnsScriptMonitoring CmdLet Do So Dynamically. Therefore It Is Mandatory It To Be Run From The Monitored Script. In That Way In The Monitoring Entry Will Be Present The Correct Process ID Of The Monitored Script Process. </para> <para type="description"> Get-SnsScriptMonitoringEntry Can Identify The Properly Running Scripts. Depending On The Specified Parameters And The Information Available In The Monitoring Entry Could Action The Enumerated Failed And Or Stuck Scripts Via Stopping The Monitored Script Process And Restarting Of The Monitored Script Scheduled Task. To Ensure This Feature Is Available Make Sure As Much As Possible Information Is Provided When The Monitored Script Is Enabled For Monitoring. </para> <para type="description"> The CmdLets In This Module Can Work Only Locally Which Means That The Monitored Scripts And The Monitoring Script Must Run On The Same Machine. </para> <para type="description"></para> <para type="description"></para> <para type="description"> The SnsPsScriptsMonitoring Uses An SQLite V3 Serverless DataBase To Keep Track Of The Monitored Scripts Information. When The PowerShell Module Is Loaded For The First Time It Automatically Creates The Monitoring DataBase At The Following Location: </para> <para type="description">"%ProgramData%\SnsPsScriptsMonitoring\SnsScrMon.db"</para> <para type="description"> Because Creation Of Folders And Files Within That Folder Requires Elevated Access Rights The First Load Of The Module Must Be In Elevated PowerShell Process. The Consequent Loads Of The Module Does not Require Elevated Mode, Except Specific Feature Requires It, And The Feature Itself Is Required. For Example Restart Of The Failed Scripts Requires The Monitored Script To Be Run In Elevated Mode, But The User Might Need The Failures To Be Reported And Not Actioned. In That Case There Is No Point To Run The Monitoring Script In Elevated Mode. </para> <para type="description"> The Information Kept In The Monitoring DataBase Is: "Machine", "Directory", "Script", "MonitoredFile", "Task", "Pid", "Threshold", "Enabled" And "Disabled". </para> <para type="description"> "Machine" Is The Fully Qualified Domain Name (FQDN) Of The Machine Where The Monitored Script Is Running. This Is Automatically Enumerated By Enable-SnsScriptMonitoring CmdLet And No User Input Is Possible. </para> <para type="description"> "Directory" Is The Folder Where The Monitored File Reside. This Information Is Automatically Enumerated From The Specified Monitored File And No User Input Is Possible. </para> <para type="description"> "Script" Is The .PS1 FileName Of The Monitored Script. This Information Is Automatically Enumerated. In Order The Enumeration To Work Correctly, Enable-SnsScriptMonitoring CmdLet Must Be Run From The Monitored Script. The "Script" Name Is Used For RestartFailed Feature, And For The Automatic Disabling From Monitoring Of Failed Scripts When The Failed Script Is Restarted And Newer Monitoring Entry Is Created About New Monitoring File Of The Same Script. "Script" Is Not Mandatory However When The Value Is Missing Or Incorrect Those Features Will Not Work. In Case The CmdLet Is Included In Scripts PowerShell Modules, The CmdLet Will Wrongly Identify The Script Module File As Monitored Script, From That Perspective The CmdLet Must Be Called From The Monitored Script Main .PS1 File. </para> <para type="description"> "MonitoredFile" Is The Full Absolute UNC Path To The Specified Monitored File. This Must Be Explicitly Specified To Enable-SnsScriptMonitoring CmdLet. There Is No Automatic Enumeration. </para> <para type="description"> "Task" Is The Full Path Of The Monitored Script Windows Scheduled Task. This Information Is Not Mandatory However Without It No Automatic Restart Of The Failed Scripts Is Possible. The Module Can Auto Enumerate It With Limited Success. It Is Preferable That "Task" Is Explicitly Specified To Enable-SnsScriptMonitoring CmdLet. </para> <para type="description"> "Pid" Is The Process ID Of The Script's PowerShell Process. This Is Automatically Enumerated. In Order The Auto Enumeration To Identify The Correct Process, The Enable-SnsScriptMonitoring Must Be Run From The Monitored Script. </para> <para type="description"> "Threshold" Is The Time Interval In Minutes About Inactivity Of The Monitored Script Used As A Threshold To Identify Whether It Is Stuck. The Inactivity Is Measured Via Reading The LastWriteTime Of The Script Transcript Or Log File Specified As Monitored File. For The Correct Identifying Please Make Shure That The Monitored Script Updates Periodically The Specified Monitored File. The Threshold Shall Be Considered Carefully Depending On The Intervals That The Monitored File Is Updated. Wrong Threshold Could Cause False Positives And Working Script To Be Stopped And Restarted In The Middle Of A Heavy Task. </para> <para type="description"> "Enabled" Is The DateTime When The Monitoring Entry Is Created, Converted To FileTime. </para> <para type="description"> "Disabled" Is The DateTime When The Monitoring Entry Is Disabled And The Monitored Script Stopped To Be Monitored, Converted To FileTime. Disabling From Monitoring Might Happen In Three Scenarios: </para> <para type="description"></para> <para type="description"> -- When The Monitored Script Finish Successfully. This Requires At The End Of The Monitored Script Have To Be Called Disable-SnsScriptMonitoring CmdLet. The CmdLet Updates The Monitoring Entry Via Specifying The Current DateTime Converted To FileTime In "Disabled" Column Of The Monitoring Entry. From That Moment On The Monitored File Updates And The Script Process Running Are No Longer Evaluated. </para> <para type="description"> -- When The Monitored Script Fail And AutoDisable Feature Is Used And New Instance Of The Monitoring Script Is Started And Enabled For Monitoring. Then The Failed Old Instance Will Be Disabled From Monitoring. The Way The Failed Script Is Restarted Does Not Make Any Difference. This Feature Will Work As Long As The Monitored Entry Have The Correct Values In "Script", "Directory" And "Task" Properties. It Is Not Related With RestartFailed Feature. </para> <para type="description"> -- When The User Runs Manually Disable-SnsScriptMonitoring CmdLet. This Is The Only Option To Stop The Reports For Failed Scripts That Did Not Disabled Themselves From Monitoring And The Prerequisites For AutoDisable Feature Are Not Met. For Example When The Scheduled Task Is Not Provided And Its Enumeration Failed. </para> <para type="description"> During The Module Load The Outdated Monitoring Entries Are Deleted And The Monitoring Database Is Defragmented And Shrank To Release Its White Space To The Operating System. For Outdated Entries Are Considered The Ones Which Are Disabled More Than 14 Days Ago. Enabled Entries Are Never Threated As Outdated Regardless Of Their Age. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov</para> <para>THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK</para> <para>OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.</para> <para></para> <para></para> <para></para> </description> </item> </list> <example> <code> Enable-SnsScriptMonitoring -Path "C:\Transcript.txt" -ScheduledTask "\MyScript" -Threshold 30; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry]$objEntry = Enable-SnsScriptMonitoring -Path "C:\Transcript.txt" ` -ScheduledTask "\MyScript" -Threshold 30 -PassThru; </code> <para></para> </example> </summary> <para type="link" uri="https://github.com/svesavov/SnsPsScriptsMonitoring"> svesavov / SnsPsScriptsMonitoring - </para> <para type="link" uri="https://www.powershellgallery.com/packages/SnsPsScriptsMonitoring/"> PowerShell Gallery - </para> <para type="link" uri="https://www.linkedin.com/in/svetoslavsavov"> Svetoslav Savov on LinkedIn - </para> <para type="link" uri="https://sqlite.org/index.html"> SQLite V3 - </para> </member> <member name="P:SnsPsScriptsMonitoring.EnableSnsScriptMonitoring.Path"> <summary> <para type="description">Specifies The Full Absolute UNC File Path To The Monitored Script Transcript File.</para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.EnableSnsScriptMonitoring.ScheduledTask"> <summary> <para type="description">Specifies The Path To The Monitored Script Windows Scheduled Task.</para> <para type="description">If Omitted The CmdLet Will Try To Auto Enumerate It.</para> <para type="description"> If Auto Enumeration Fail And The Monitoring Entry Is Created Without Scheduled Task Path, The Auto Restart Feature Of Get-SnsScriptMonitoringEntry CmdLet Will Not Work. </para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.EnableSnsScriptMonitoring.Threshold"> <summary> <para type="description">Specifies The Script Inactivity Threshold In Minutes.</para> <para type="description">Valid Range From 1 To 1440.</para> <para type="description"> The Threshold Have To Be Considered Carefully. In Case The Monitored Script Makes Heavy Tasks Which Could Take Time. While Those Tasks Are Running The Monitored Script Will Be Unable To Update Its Transcript Or Log File. If The Threshold Is Less Than The Time Required For The Heavy Task, The Monitoring CmdLet Will Wrongly Identify The Monitored Script As Failed And Depending On The Specified Parameters Might Restart The Script In The Middle Of The Heavy Task Causing Its Failure And Starting It From The Beginning. </para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.EnableSnsScriptMonitoring.PassThru"> <summary> <para type="description">Specifies To The CmdLet To Revert The New MonitoringEntry Object.</para> </summary> </member> <member name="T:SnsPsScriptsMonitoring.GetSnsScriptMonitoringEntry"> <summary> <para type="synopsis">Enumerates Monitoring Entries, Evaluates About Failed Scripts And Restarts Them If Requested.</para> <para type="description">Enumerates Monitoring Entries, Evaluates About Failed Scripts And Restarts Them If Requested.</para> <para type="description"></para> <para type="description"></para> <para type="description"> Whenever A Script Fails It Either Have Its Process Stuck Without Being Able To Continue Further Or Its Process Completely Stop. In Both Cases The Script Cannot Notify About The Failure Nor Continue Further. From That Perspective Whenever We Have Automation Scripts Doing Business Critical Tasks We Need To Monitor Their Running Using Another Script Named Here Monitoring Script. </para> <para type="description"> Detecting A Failed Script Is Relatively Easy, Whenever We Have Failed Script Its Process Stops And No Longer Could Be Enumerated With The Machines Processes. A Monitoring Script Could Detect The Failure And Either Report Or Take Actions. However That's Not The Case With The Stuck Scripts. Their Processes Are Still Running And Just Doing Nothing. A Monitoring Script Could Be Easily Mistaken That A Stuck Script Is Running As Usual. Monitoring Of Stuck Scripts Can Be Achieved Via Using Of Transcript Files By The Monitored Scripts Which To Be Updated Regularly. The Monitored Script Could Check The LastWriteTime Of Those Transcript Files And Based On A Threshold Could Decide Whether Specific Monitored Script Is Stuck Or Continue To Be Updated. </para> <para type="description"> The Module Requires The Monitored Scripts To Write Output Regularly On Either Transcript Or Log File, Named Here Monitored File. From Within The Monitored Script Must Be Created A Monitoring Entry Kept In A Monitoring DataBase About The Monitored File Using Enable-SnsScriptMonitoring CmdLet. At The End Of The Monitored Script Running It Must Run Disable-SnsScriptMonitoring To Indicate It Is Completed Successfully And No Longer Needs To Be Monitored. Whenever Disabling From Monitoring Is Omitted The Module Still Can Identify Successfully Completed Scripts Using The Monitored Script Exit Code Supplied To Its Scheduled Task. In Order This To Work As Expected The Monitoring Entry Must Have The Correct Scheduled Task Path And Access Rights To Verify Whether Its State Is Ready And The Last Exit Code Is 0 (Exit Without Failures). Additionally The Monitored Script Must Supply That Information To Its Task. Whenever The Disabling From Monitoring Is Omitted Could Lead To Unexpected Results. </para> <para type="description"> We Use Get-SnsScriptMonitoringEntry CmdLet From Within The Monitoring Script To Monitor The Monitored Scripts. The CmdLet Is Capable To Automatically Restart The Failed Scripts, If Needed And The Prerequisites For That Are Met. </para> <para type="description"> Because The Monitored Script Could Be Stuck Or Failed We Need Additional Script Executed On A Schedule To Run Get-SnsScriptMonitoringEntry In Order To Monitor The Monitored Scripts Operation. The Monitoring Script Must Be Reliable And Not Resource Intensive. The Reliability And Performance Considerations Are The Main Reason This Module To Be Developed As Binary PowerShell Module. </para> <para type="description"> The "SnsPsScriptsMonitoring" PowerShell Module Contains All The CmdLets Required For Enable Monitoring, Disable Monitoring, And Being Monitored By A Dedicated Monitoring Script. All The Needed CmdLets Are In One Place And There Is No Monitoring And Monitoring Agent PowerShell Modules. </para> <para type="description"> The Module Requires The Monitored Scripts To Comply With The Following Requirements: </para> <para type="description"> - The Monitored Scripts Must Update Periodically Transcript Or Log Files. Whenever Those Files Are Not Modified For Specified Period Of Time Their Scripts Are Considered As Stuck. The Monitoring CmdLet Does Not Read The Content Of The Transcript Files. We Need The Monitoring Processes To Be Fast As Possible. Reading File Content Is Not Among The Operations Considered As Fast. The Account That Running The Get-SnsScriptMonitoringEntry CmdLet Requires NTFS Permissions Over The Monitored Files To Read Their LastWriteTime. </para> <para type="description"> - To Identify Failed Script Processes The Get-SnsScriptMonitoringEntry CmdLet Verifies Whether The Script Process Is Still Running. This Requires The Correct Process ID Of The Script Process To Be Present In The Monitoring Entry. The Process ID's Are Assigned By The Operating System Dynamically, Therefore They Cannot Be Specified At The Time When The Monitored Script Is Written And Provided To Enable-SnsScriptMonitoring CmdLet. However The PowerShell Can Dynamically Identify Its Own Process, And The Enable-SnsScriptMonitoring CmdLet Do So Dynamically. Therefore It Is Mandatory It To Be Run From The Monitored Script. In That Way In The Monitoring Entry Will Be Present The Correct Process ID Of The Monitored Script Process. </para> <para type="description"> Get-SnsScriptMonitoringEntry Can Identify The Properly Running Scripts. Depending On The Specified Parameters And The Information Available In The Monitoring Entry Could Action The Enumerated Failed And Or Stuck Scripts Via Stopping The Monitored Script Process And Restarting Of The Monitored Script Scheduled Task. To Ensure This Feature Is Available Make Sure As Much As Possible Information Is Provided When The Monitored Script Is Enabled For Monitoring. </para> <para type="description"> The CmdLets In This Module Can Work Only Locally Which Means That The Monitored Scripts And The Monitoring Script Must Run On The Same Machine. </para> <para type="description"></para> <para type="description"></para> <para type="description"> The SnsPsScriptsMonitoring Uses An SQLite V3 Serverless DataBase To Keep Track Of The Monitored Scripts Information. When The PowerShell Module Is Loaded For The First Time It Automatically Creates The Monitoring DataBase At The Following Location: </para> <para type="description">"%ProgramData%\SnsPsScriptsMonitoring\SnsScrMon.db"</para> <para type="description"> Because Creation Of Folders And Files Within That Folder Requires Elevated Access Rights The First Load Of The Module Must Be In Elevated PowerShell Process. The Consequent Loads Of The Module Does not Require Elevated Mode, Except Specific Feature Requires It, And The Feature Itself Is Required. For Example Restart Of The Failed Scripts Requires The Monitored Script To Be Run In Elevated Mode, But The User Might Need The Failures To Be Reported And Not Actioned. In That Case There Is No Point To Run The Monitoring Script In Elevated Mode. </para> <para type="description"> The Information Kept In The Monitoring DataBase Is: "Machine", "Directory", "Script", "MonitoredFile", "Task", "Pid", "Threshold", "Enabled" And "Disabled". </para> <para type="description"> "Machine" Is The Fully Qualified Domain Name (FQDN) Of The Machine Where The Monitored Script Is Running. This Is Automatically Enumerated By Enable-SnsScriptMonitoring CmdLet And No User Input Is Possible. </para> <para type="description"> "Directory" Is The Folder Where The Monitored File Reside. This Information Is Automatically Enumerated From The Specified Monitored File And No User Input Is Possible. </para> <para type="description"> "Script" Is The .PS1 FileName Of The Monitored Script. This Information Is Automatically Enumerated. In Order The Enumeration To Work Correctly, Enable-SnsScriptMonitoring CmdLet Must Be Run From The Monitored Script. The "Script" Name Is Used For RestartFailed Feature, And For The Automatic Disabling From Monitoring Of Failed Scripts When The Failed Script Is Restarted And Newer Monitoring Entry Is Created About New Monitoring File Of The Same Script. "Script" Is Not Mandatory However When The Value Is Missing Or Incorrect Those Features Will Not Work. In Case The CmdLet Is Included In Scripts PowerShell Modules, The CmdLet Will Wrongly Identify The Script Module File As Monitored Script, From That Perspective The CmdLet Must Be Called From The Monitored Script Main .PS1 File. </para> <para type="description"> "MonitoredFile" Is The Full Absolute UNC Path To The Specified Monitored File. This Must Be Explicitly Specified To Enable-SnsScriptMonitoring CmdLet. There Is No Automatic Enumeration. </para> <para type="description"> "Task" Is The Full Path Of The Monitored Script Windows Scheduled Task. This Information Is Not Mandatory However Without It No Automatic Restart Of The Failed Scripts Is Possible. The Module Can Auto Enumerate It With Limited Success. It Is Preferable That "Task" Is Explicitly Specified To Enable-SnsScriptMonitoring CmdLet. </para> <para type="description"> "Pid" Is The Process ID Of The Script's PowerShell Process. This Is Automatically Enumerated. In Order The Auto Enumeration To Identify The Correct Process, The Enable-SnsScriptMonitoring Must Be Run From The Monitored Script. </para> <para type="description"> "Threshold" Is The Time Interval In Minutes About Inactivity Of The Monitored Script Used As A Threshold To Identify Whether It Is Stuck. The Inactivity Is Measured Via Reading The LastWriteTime Of The Script Transcript Or Log File Specified As Monitored File. For The Correct Identifying Please Make Shure That The Monitored Script Updates Periodically The Specified Monitored File. The Threshold Shall Be Considered Carefully Depending On The Intervals That The Monitored File Is Updated. Wrong Threshold Could Cause False Positives And Working Script To Be Stopped And Restarted In The Middle Of A Heavy Task. </para> <para type="description"> "Enabled" Is The DateTime When The Monitoring Entry Is Created, Converted To FileTime. </para> <para type="description"> "Disabled" Is The DateTime When The Monitoring Entry Is Disabled And The Monitored Script Stopped To Be Monitored, Converted To FileTime. Disabling From Monitoring Might Happen In Three Scenarios: </para> <para type="description"></para> <para type="description"> -- When The Monitored Script Finish Successfully. This Requires At The End Of The Monitored Script Have To Be Called Disable-SnsScriptMonitoring CmdLet. The CmdLet Updates The Monitoring Entry Via Specifying The Current DateTime Converted To FileTime In "Disabled" Column Of The Monitoring Entry. From That Moment On The Monitored File Updates And The Script Process Running Are No Longer Evaluated. </para> <para type="description"> -- When The Monitored Script Fail And AutoDisable Feature Is Used And New Instance Of The Monitoring Script Is Started And Enabled For Monitoring. Then The Failed Old Instance Will Be Disabled From Monitoring. The Way The Failed Script Is Restarted Does Not Make Any Difference. This Feature Will Work As Long As The Monitored Entry Have The Correct Values In "Script", "Directory" And "Task" Properties. It Is Not Related With RestartFailed Feature. </para> <para type="description"> -- When The User Runs Manually Disable-SnsScriptMonitoring CmdLet. This Is The Only Option To Stop The Reports For Failed Scripts That Did Not Disabled Themselves From Monitoring And The Prerequisites For AutoDisable Feature Are Not Met. For Example When The Scheduled Task Is Not Provided And Its Enumeration Failed. </para> <para type="description"> During The Module Load The Outdated Monitoring Entries Are Deleted And The Monitoring Database Is Defragmented And Shrank To Release Its White Space To The Operating System. For Outdated Entries Are Considered The Ones Which Are Disabled More Than 14 Days Ago. Enabled Entries Are Never Threated As Outdated Regardless Of Their Age. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov</para> <para>THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK</para> <para>OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.</para> <para></para> <para></para> <para></para> </description> </item> </list> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsScriptMonitoringEntry -Path "C:\Transcript.txt"; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsScriptMonitoringEntry -All; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsScriptMonitoringEntry -Enabled; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsScriptMonitoringEntry -Enabled -RestartFailed; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsScriptMonitoringEntry -Failed; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsScriptMonitoringEntry -Failed -RestartFailed; </code> <para></para> </example> </summary> <para type="link" uri="https://github.com/svesavov/SnsPsScriptsMonitoring"> svesavov / SnsPsScriptsMonitoring - </para> <para type="link" uri="https://www.powershellgallery.com/packages/SnsPsScriptsMonitoring/"> PowerShell Gallery - </para> <para type="link" uri="https://www.linkedin.com/in/svetoslavsavov"> Svetoslav Savov on LinkedIn - </para> <para type="link" uri="https://sqlite.org/index.html"> SQLite V3 - </para> </member> <member name="P:SnsPsScriptsMonitoring.GetSnsScriptMonitoringEntry.Path"> <summary> <para type="description">Specifies The Full Absolute UNC File Path To The Monitored Script Transcript File.</para> <para type="description">The Parameter Allows Wildcards Both In PowerShell And SQL Syntax.</para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.GetSnsScriptMonitoringEntry.All"> <summary> <para type="description">Specifies To The CmdLet To Revert All Monitoring Entries Including The Disabled Ones.</para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.GetSnsScriptMonitoringEntry.Enabled"> <summary> <para type="description">Specifies To The CmdLet To Revert Only The Enabled Entries Without To Take Any Mitigation Actions.</para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.GetSnsScriptMonitoringEntry.Failed"> <summary> <para type="description"> Specifies To The CmdLet To Verify The State Of The Scripts Associated With The Monitoring Entries And Revert Only The Ones Which Are Enabled For Monitoring And Failed Or Stuck. </para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.GetSnsScriptMonitoringEntry.RestartFailed"> <summary> <para type="description">Specifies To The CmdLet To Restart The Failed Scripts.</para> <para type="description">This Happens In Two Steps:</para> <para type="description"> -- Stopping The PowerShell Process Of A Stuck Script. The Script Must Not Updated Its Own Transcript File For Longer Than The Specified Threshold. This Step Requires The Correct Process ID To Be Available In The Monitoring Entry. Once The Process Of Stuck Script Is Stopped Effectively It Become Failed Script. This Requires The Account That Calling The CmdLet To Have Local Administrative Access Rights And To Be Run In Elevated PowerShell Session. </para> <para type="description"> -- Restarting Script's Scheduled Task. It Requires The Correct Scheduled Task Path To Be Available In The Monitoring Entry. In Order This To Work Properly The Scheduled Task Have To Be Configured To Allow Run On Demand And The Account That Runs The CmdLet To Have Local Administrative Access Rights On The Machine And The CmdLet To Be Run In Elevated PowerShell Session. </para> </summary> </member> <member name="T:SnsPsScriptsMonitoring.InitializeSnsModuleState"> <summary> <para type="synopsis">Verifies The Monitoring DataBase Existence And Creates It If Needed.</para> <para type="description">Verifies The Monitoring DataBase Existence And Creates It If Needed.</para> <para type="description">The CmdLet Is Hidden For The User And Run Once On The PowerShell Module Load.</para> <para type="description"> The SnsPsScriptsMonitoring PowerShell Module Uses An SQLite Serverless DataBase To Store The Required Information About The Enabled For Monitoring Scripts. It Requires The Monitoring DataBase To Be Stored Somewhere Permanently Regardless Of Location Where The PowerShell Module Is Installed. The PowerShell Modules Are Installed In Different Locations Depending On The Installation Scope. And All Those Locations Are Protected Which Means That If The User Is Running The Module In Not Elevated Mode Will Be Not Able To Write Into The Monitoring DataBase. The Most Appropriate Location In Such Scenarios Is To Make A Subfolder In "ProgramData" Folder Which Is Enumerated By .NET And There Is No Need To Hardcode The Path To The DataBase. The "ProgramData" Folder Itself Is Protected, However The User Created Folders Inside Are Not. From That Perspective The Monitoring DataBase Is Created In: </para> <para type="description">"%ProgramData%\SnsPsScriptsMonitoring\SnsScrMon.db"</para> <para type="description"> The Monitoring DataBase Used Is A Simple One With A Single Table. However The Loading Checks Are Quite Complete And Heavy. If All Of Them Are Performed Could Lead To Unnecessary Decrease Of The Monitored Scripts Performance. The DataBase Verification Checks And DataBase Maintenance Tasks Are Distinguished Into 3 Groups. The Monitoring DataBase Is Verified About: </para> <para type="description"> -- DataBase Folder Enumeration. Because The ProgramData Folder Is Managed By The OS Its Location Could Be Modified. Therefore The DataBase And DataBase Folder Paths Are Considered As Dynamic And Their Values Have To Be Enumerated. The Enumeration Happens Once On The Module Lode. In Case Something Is Modified After The Module Load Will Lead To Errors As Long As The Module Will Not Be Able To Access Its Own DataBase. </para> <para type="description"> -- DataBase File Path Enumeration. The Enumeration Happens Just Once At The Module Load. </para> <para type="description"> -- The Existence Of The DataBase File And Its LastWriteTime. In Case The DataBase Does Not Exists Or The LastWriteTime Of The DataBase File Is Not In The Current Date, All DataBase Verification Checks Are Enabled. The LastWriteTime Is Taken Only When The DataBase File Exists To Prevent Errors. This Evaluation Is Always Made. Therefore If The Module Is Loaded And Left In PowerShell Process For Long Time On The First Run Of Any Command After The Date Is Changed The Module Will Do The Complete Set Of Verifications. This Evaluation Happens Before Each CmdLet Run In Its Begin Method. </para> <para type="description"> -- The Existence Of The DataBase Folder. In Case The Folder Does Not Exists It Is Created. This Requires The First PS Module Load To Be Made In Elevated Mode. This Verification Is Part Of The First Group Of Checks Named Basic Checks. </para> <para type="description"> -- The NTFS Permissions Of The DataBase Folder. "Full Control" To Local Users Group Is Verified And If Needed Is Granted. In Order Granting To Work The Module Have To Be Imported In Elevated PowerShell Process. Because The Creation Of The Folder Requires Elevated Right After The Creation Access Rights Are Immediately Granted And Remains Afterward. Therefore Elevated Mode Is Required Only On The First Module Import. This Is Part Of The Basic Checks Group. </para> <para type="description"> -- The Existence Of The DataBase File. In Case The DataBase Is Missing The Module Creates One. This Is Part Of The Basic Checks. </para> <para type="description"> -- The CmdLet Verifies The Existence And The Schema Of The Monitoring Table Within The Monitoring DataBase. In Case The Table Is Missing New One Is Created. In Case The Table Is There But The Table Schema Does Not Match The Module Requirements, A DataBase Backup Is Made And The Invalid Table Is Deleted, Then New Table Is Created With The Correct Schema. This Task Is Part Of The Basic Verifications. </para> <para type="description"> -- The Existence Of Any Other Than The Monitoring DataBase Files In The DataBase Folder. In Case Such Files Exist They Are Deleted. Any Monitoring DataBase Backup Files Existence Is Tolerated For 61 Days. This Is Part Of The Next Group Of Task Named Advanced Verifications. </para> <para type="description"> -- The Existence Of Any Nested Folders. The Module Requires And Creates A Single DataBase File, Except In The Cases When DB Backup Is Made. It Does Not Create Any Subfolders Within The DataBase Folder. If Any Are Detected They Are Deleted Immediately. This Task Is Part Of The Advanced Verifications Group. </para> <para type="description"> -- The Tables Located Inside The DataBase. The SnsPsScriptsMonitoring PowerShell Module Uses A Single Table Within Its Own DataBase. In Case Any Other Tables Appear Would Mean That The DataBase Is Modified By The User Using 3rd Party Tools. Such Tables Are Deleted. This Task Is Part Of The Advanced Verifications Group. </para> <para type="description"> -- The CmdLet Verifies The Existence And The Schema Of The Indexes Associated With The Monitoring Table Within The Monitoring DataBase. In Case The Indexes Are Missing New Ones Are Created. This Task Is Part Of The Advanced Verifications Group. </para> <para type="description"> -- The CmdLet Creates A Test Monitoring Entry, Verify Its Creation, Then Delete The Test Entry And Verifies The Deletion. This To Be Confirmed Before The Work Is Started That The User Have The Required Access Rights To The Monitoring DataBase. This Task Is Part Of The Advanced Verifications Group. </para> <para type="description"> -- The CmdLet Verifies About The Existence Of Outdated Entries Related With Scripts Not Being Monitored For More Than 14 Days And Deletes Them. Whenever Deletion Of Outdated Entries Is Made, The CmdLet Defragments And Compacts The Monitoring DataBase To Release The White Space To The Operating System. This Task Is In A Group Of Its Own Named Delete Outdated Entries. </para> <para type="description"> Once Verifications From A Specific Group Are Successfully Completed, They Are Not Performed Again In The Same PowerShell Session, Except If The Session Is Long Enough To Spread Across Dates. Which Means For Example Starting A Session At 11PM And Leave The Session Open On The Next Command Run In 1 AM All The Verifications Will Be Made From Scratch. </para> <para type="description"> The Verification Tasks Are Executed When: </para> <para type="description"> -- It Is The First PowerShell Module Load Or Run Of A Command From The Module For The First Time On The Date. In That Case All 3 Groups Of Verification Tasks Will Be Run. </para> <para type="description"> -- The PowerShell Module Is Loaded Interactively And The Calling Of The Module IS Not Part Of Script Or Automation. In That Case All The 3 Groups Of Verification Tasks Will Run. </para> <para type="description"> -- The PowerShell Module Is Loaded With Call From A Script Or With Call From A Not Interactive Process. Then Will Be Executed The Verification Tasks From The Basic Group. </para> <para type="description"> -- A Command Is Run To Enable Or Disabled The Monitoring Of A Script. Then Will Be Executed The Basic Verification Tasks If They Are Not Already Made. </para> <para type="description"> -- A Command Is Run To Get The Monitored Scripts. Then Will Be Executed Only The Verification Groups Which Are Not Already Completed. Lets For Example Assume The Module Is Loaded With The Monitoring Script Run On A Schedule As A Service. During The Module Load The Basic Tasks Will Complete. Then The Script Call Get-SnsScriptMonitoringEntry CmdLet. Before The CmdLet To Do Its Job Within Its Begin Method Will Call The DataBase Verifications Method To Complete All The Verifications. Since The Basic Tasks Are Already Completed During The Module Import, Only The Advanced And Delete Outdated Entries Groups Will Run. On The Consequent Run Of The Get-SnsScriptMonitoringEntry CmdLet No Verifications Will Be Made Because All 3 Groups Are Completed. On Consequent Enable Or Disable Commands No Verifications Will Be Made Because The Basic Verifications Are Already Completed. Unless The Consequent Runs Of The CmdLets Are In The Next Date. </para> <para type="description"> The Monitoring Table In The Monitoring DataBase Have Schema Closely Related With The Desired Monitoring Logic. The Table Have The Following DataBase Schema: </para> <para type="description">CREATE TABLE IF NOT EXISTS [Monitor]</para> <para type="description">(</para> <para type="description">[Machine] VARCHAR NOT NULL,</para> <para type="description">[Directory] VARCHAR NOT NULL,</para> <para type="description">[Script] VARCHAR NULL,</para> <para type="description">[MonitoredFile] VARCHAR PRIMARY KEY UNIQUE NOT NULL,</para> <para type="description">[Task] VARCHAR NULL,</para> <para type="description">[Pid] INTEGER NULL,</para> <para type="description">[Threshold] INTEGER NOT NULL,</para> <para type="description">[Enabled] LONG NOT NULL,</para> <para type="description">[Disabled] LONG NOT NULL DEFAULT (0)</para> <para type="description">);</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Machine] ON [Monitor] ( [Machine] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Directory] ON [Monitor] ( [Directory] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Script] ON [Monitor] ( [Script] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_MonitoredFile] ON [Monitor] ( [MonitoredFile] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Task] ON [Monitor] ( [Task] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Pid] ON [Monitor] ( [Pid] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Threshold] ON [Monitor] ( [Threshold] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Enabled] ON [Monitor] ( [Enabled] );</para> <para type="description">CREATE INDEX IF NOT EXISTS [ind_Monitor_Disabled] ON [Monitor] ( [Disabled] );</para> <para type="description"> The "MonitoredFile" Column Is Used To Specify A Transcript Or Log File Produced By The Monitored Script Which Is Regularly Updated. The Script That Produces This File Is Considered As Failed Whenever The File Was Not Updated For Period Specified Within "Threshold" Column Or Its Process Is No Longer Running. </para> <para type="description"> The "Task" And "Pid" Columns Are Used To Store Information About The Monitored Script. They Are The Input Needed For The Feature Which Stops The Failed Scripts Processes And Restarts Their Tasks. This Information Is Not Required As Long As The Restarting Feature Is Not Essential For The Module Normal Operation. However Without That Information The Restarting Feature Will Not Work. </para> <para type="description"> The "Directory", "Script" And "Task" Columns Are Used By The Feature Which Automatically Disable From Monitoring The Failed Scripts Entries, Whenever New Instance Of The Same Script Is Enabled For Monitoring. An Example Will Be More Appropriate Explanation. If We Have A Script That Produces Different Transcript File On Each Run And It Is Executed With A Scheduled Task. When The Script Fail Will Not Disable Its Own Entry. Lets Assume The CmdLet For Monitoring Detect That And Restarts The Script. Then The Script Will Produce New Transcript File Within The Same Folder And It Is Started With The Same Scheduled Task. In That Case The Monitoring CmdLet Have To Take Care And Disable The Entry Related With The Failed Instance Since The New Instance Is Running. For Monitoring Entries With Missing The Above Information, This Auto Monitoring Disable Feature Will Not Work. When This Happen The Failed Monitoring Entry Will Remain And The Monitored Script Will Continue To Be Reported As Failed Until A Human Manually Disable The Entry Using Disable-SnsScriptMonitoring CmdLet. </para> <para type="description"> "Enabled" And "Disabled" - The "Enabled" Column Contains The FileTime When The Monitoring Entry Was Created And The Monitored File Enabled For Monitoring. The "Disabled" Column Shall Contain The FileTime When The Entry Was Disabled And The Script Is No Longer Monitored. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov</para> <para>THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK</para> <para>OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.</para> <para></para> <para></para> <para></para> </description> </item> </list> <example> <code> Initialize-SnsModuleState -DeleteOutdatedEntries; </code> <para></para> </example> </summary> <para type="link" uri="https://github.com/svesavov/SnsPsScriptsMonitoring"> svesavov / SnsPsScriptsMonitoring - </para> <para type="link" uri="https://www.powershellgallery.com/packages/SnsPsScriptsMonitoring/"> PowerShell Gallery - </para> <para type="link" uri="https://www.linkedin.com/in/svetoslavsavov"> Svetoslav Savov on LinkedIn - </para> <para type="link" uri="https://sqlite.org/index.html"> SQLite V3 - </para> </member> <member name="P:SnsPsScriptsMonitoring.InitializeSnsModuleState.DeleteOutdatedEntries"> <summary> <para type="description"> Specifies To The CmdLet To Delete The Outdated Monitoring Entries. As Outdated Monitoring Entries Are Considered Ones Related With Scripts Not Being Monitored For More Than 31 Days. </para> <para type="description"> Deletion Of The Outdated Entries Automatically Enable The DataBase Defragmentation And Compacting The DataBase File To Release The Whitespace To The Operating System. </para> <para type="description">In Case There Are No Deleted Outdated Monitoring Entries, DataBase Defragmentation And Compacting Is Not Made.</para> </summary> </member> </members> </doc> |