bin/SnsPsScriptsMonitoring.xml
|
<?xml version="1.0"?>
<doc> <assembly> <name>SnsPsScriptsMonitoring</name> </assembly> <members> <member name="T:SnsPsScriptsMonitoring.DisableSnsScriptMonitoring"> <summary> <para type="synopsis"> This CmdLet Disables A Monitoring Entry In The Monitoring DataBase. </para> <para type="description"> This CmdLet Disables A Monitoring Entry In The Monitoring DataBase. </para> <para type="description"> The Way That This Module Monitors About Failed Scripts, Requires The Monitored Scripts To Write Some Output On A File, Either Transcript Or Log Ones, Called Here Monitored File. Then Get-SnsMonitoringEntry CmdLet Have To Be Executed From Another Script On A Schedule. During The Execution Of The CmdLet It Verifies Whether The Script Process Is running Or The Monitored File Has Not Been Updated For Specified Amount OF Time. In Order The Monitoring To Work Properly The Account Under Who’s Security Context Is Run The Get-SnsMonitoringEntry CmdLet Must Have Enough NTFS Permissions To Verify The Monitored File Existence And LastWriteTime (Modified) File Property. </para> <para type="description"> In Order The Monitoring To Work Smoothly It Requires Some CmdLets From This Module To Be Run From Within The Monitored Script And Some CmdLets To Be Run From Dedicated Monitoring Script. </para> <para type="description"> -- The SnsPsScriptsMonitoring Uses A SQLite V3 Serverless DataBase To Keep Track Of The Monitored Scripts And Essential For Their Monitoring 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"> "C:\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 Have To Be In Elevated PowerShell Process. The Consequent Loads Of The Module Doesn’t Require Elevated Mode In Most Of The Cases, Except The Scenario Whenever The Failed Scripts Have To Be Restarted. </para> <para type="description"> The Information Kept In The Monitoring DataBase Is: "Directory", "Script", "MonitoredFile", "Task", "Pid", "Threshold", "Enabled" And "Disabled". </para> <para type="description"> "Directory" Is The Folder Where The Monitored File Reside. This Information Is Automatically Generated From The Specified Monitored File. </para> <para type="description"> "Script" Is The .PS1 File Of The Monitored Script. This Information Is Automatically Generated. In Order The Monitored Script To Be Identified Correctly Enable-SnsScriptMonitoring Have To Be Run From The Monitored Script. In Case The CmdLet Is Included In Additional PowerShell Modules, The CmdLet Will Wrongly Identify The Module File As Monitored Script. This Is Critical Whenever Is Required Automatic Restart OF The Failed Scripts, And For The Automatic Disabling From Monitoring OF Failed Scripts When The Failed Script Is Restarted And Newer Transcript Or Log File Is Enabled For Monitoring. </para> <para type="description"> "MonitoredFile" Is The Full Absolute UNC Path To The Specified Monitored File. This Must Be Specified Explicitly To Enable-SnsScriptMonitoring CmdLet. There Is No Automatic Generation. </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 Generate The With Limited Success. It Is Preferable That Information To Be Specified To Enable-SnsScriptMonitoring CmdLet. </para> <para type="description"> "Pid" Is The Process ID Of The PowerShell Process Where Monitored Script Is Executed. This Is Automatically Generated. In Order The Auto Generate To Identify The Correct Process, The Enable-SnsScriptMonitoring Must Be Run From Inside 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 Failed Scripts. 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 Update Periodically The Specified Monitored File. The Threshold Shall Be Specified Carefully Depending Of The Intervals That The Monitored File Is Updated. Wrong Threshold Could Cause Working Script To Be Stopped And Restarted In The Middle Of Some Heavy Task. </para> <para type="description"> "Enabled" Is The Date And Time When The MonitoredFile Is Inserted In The DataBase And Enabled For Monitoring. </para> <para type="description"> "Disabled" Is The Date And Time When The Monitored Script Finished Successfully And Therefore No Longer Monitored. From That Perspective The CmdLet Disable-SnsScriptMonitoring Have To Be Executed From Within The Monitored Script At The End Of The Script. In Case The Script Fail It Will Not Get To The Point To Disable Itself From Monitoring, And Its Monitoring Entry Will Remain Enabled, Until Get-SnsMonitoringEntry CmdLet Is Executed By The Monitoring Script And The Failure Is Reported Or Actioned. Having That In Mind We Can Imagine That With The Time Will Remain A Lot Of Enabled DataBase Entries Related With Failed Scripts, As They Never Been Disabled. The Get-SnsMonitoringEntry Partially Takes Care About That Via Identifying Newer Monitoring Entries For The Existing Enabled Entries. For Newer Entries Are Considered The Ones That Have The Same Script, The Same Monitored File Directory, And The Same Windows Scheduled Task Path. Considering The Same Monitoring File Is Not An Option Because Whenever The Same File Is Enabled Again Its Previous Entry Is Overwritten Because "MonitoredFile" Column Is Primary Key In The DataBase Table. In Order The Automatic Detection For Newer Monitoring Entries To Work As Expected, The Evaluated Entries Must Have Values In All Of The Mentioned Above 3 Columns. In Case Some Entries Have No Values Them, They Will Be Not Evaluated, And Their Entries Will Remain Enabled In The Monitoring DataBase. To Disable Them The User Can Run Disable-SnsScriptMonitoring Manually To Disable Specific Entry. </para> <para type="description"> In Addition 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 31 Days Ago. Enabled Entries Are Never Threated As Outdated Regardless Of Their Age. </para> <para type="description"> -- The Script Which Have To Be Enabled For Monitoring Have To Run Enable-SnsScriptMonitoring CmdLet From Itself At The Beginning. The CmdLet Requires To Be Provided A Transcript Or Log File Which The Script Update Regularly. </para> <para type="description"> To Ensure That The Monitoring Will Be Able To Restart The Monitored Script The Monitoring Entry Have To Have Scheduled Task And Process Id Of The Monitored Script. The Process Id Is Taken Automatically Via Enumeration Of The Own Process Id. The Windows Scheduled Task Can Be Automatically Enumerated With Limited Success Via Search Among The Windows Schedule Tasks About Task That Have The Monitored Script .PS1 File In "Add arguments (optional):" In The Scheduled Task Action, The Same "Start in (optional):" In The Scheduled Task Action As The Monitored File Directory, Or The Monitored File Directory Have To Be Nested In The Scheduled Task Action "Start in (optional):" Folder. In Case The Enumerated Scheduled Tasks Are Only One Then It Is Considered As Script Scheduled Task. However This To Work The Monitoring Entry Shall Have The Script .PS1 File Which Might Happen Only If Enable-SnsScriptMonitoring Is Executed From The Monitored Script Itself. </para> <para type="description"> With Other Words If The Monitored Script Is Located In One Folder And The Monitored File Is Located In A Folder Not Nested In The Script Folder There Is No Chance The Windows Scheduled Task To Be Identified Correctly. Also When There Are Multiple Scheduled Tasks For A Single Script For Example To Prepare Daily Weekly And Monthly Reports. This Will Means That 3 Scheduled Tasks Will Be Enumerated and The CmdLet Will Not assign Neither Of Them Because It Is Not Certain Which One Of Them Have to Be Restarted For This Monitoring Entry. Therefore It Is Always Preferable The Windows Scheduled Task To Be Specified Via CmdLet Parameter. In That Case The CmdLet Will Not Enumerate The Windows Scheduled Tasks, And Will Complete A Little Bit Faster. </para> <para type="description"> To Ensure That The Proper PowerShell Process Is Stopped Whenever The Script Fail, The Information About The Process ID Is Kept In The Monitoring Entry. In Case The Process IS Still Running And Inactive Depending Of The Monitoring Preferences Get-SnsMonitoringEntry Might Try To Stop The Process And Restart The Failed Script Via Running Of Its Scheduled Task. However The Information About The Process ID IS Dynamically Generated, And In Order To Be Correct The Enable-SnsScriptMonitoring Must Be Executed From The Monitored Script. If It Is Run From Another PowerShell Process, The ID OF That Another PowerShell Process Will Be Inserted In The Monitoring DataBase And In Case Of Failure That Another Process Will Be Stopped. </para> <para type="description"> The Monitored Script Is Not Specified At All. The CmdLet Enumerates From The MyInvocationInfo Object Who Called The CmdLet. To Ensure That The Monitoring Features Works As Expected It IS Very Important The CmdLet To Ba Called From The Script Itself. In Case The Script Uses Its Own Module And The Monitoring Enablement IS Called From There The MyInvocationInfo Object Will Revert The Module Instead OF The Script. Which Might Lead To Improper Behavior Of The Monitoring. </para> <para type="description"> -- During The Monitored Script Running There Have To Be Another Script Executed On A Schedule Every Few Minutes Depending Of The Desired Outcome And Needed Threshold. The Monitoring Script Have To Invoke Get-SnsMonitoringEntry CmdLet In Regular Intervals To Get Information About The Status Of The Monitored Scripts. Depending Of The Specified To The CmdLet Parameters It Can: </para> <para type="description"> Enumerate Specific Monitoring Entry Present In The Monitoring DataBase Regardless Whether It Is Enabled Or Disabled. </para> <para type="description"> Enumerate All Monitoring Entries Present In The Monitoring DataBase Regardless Whether They Are Enabled Or Disabled. Although This Parameter Set Looks Like Suitable To Prepare A Report When The Monitored Scripts Are Ran, It Actually Is Not Suitable For That Purpose. The Problem Is That The "MonitoredFile" Column Is Primary Key In The Monitoring Table. Which Means That It Can Have Unique Values Only. In The Cases When Specific Script Creates A Transcript Or Log File With The Same Name And Path On Each Execution. There Will Be Only One Monitoring Entry For That Script, Because On Each Script Ran The Previous Monitoring Entry Will Be Overwritten, And The Monitoring DataBase Will Keep Only One Entry For Multiple Script Executions. In The Real Life The Monitored file Will Be Overwritten As Well, So In The DataBase Logic There Is No Big Difference. If You Ensure That Each Monitored Script Will Create Different New Transcript Or Log File To Be Monitored, Then The Data From The Monitoring DataBase Can Be Used For Statistics Reports. </para> <para type="description"> Enumerate All Enabled Monitoring Entries To The Moment Of The CmdLet Execution. </para> <para type="description"> Enumerate All Enabled Failed Monitoring Entries To The Moment Of The CmdLet Execution. As Failed Are Considered The Scripts Which Did Not Updated Their Transcript Or Log Files For Longer Than The Specified Threshold Or Their Process Is No Longer Running. </para> <para type="description"> If "RestartFailed" Switch Parameter Is Specified, To Stop The Processes Of The Failed Scripts If They Are Still Running And Restart Their Scheduled Tasks. "RestartFailed" Is Available Only In "Enabled" And "Failed" Parameter Sets. It Will Work Only If The CmdLet Is Executed In Elevated Mode And All The Needed Information Is Available In The Monitoring Entry Inside The Monitoring DataBase. </para> <para type="description"> Regardless Of The ParameterSet The CmdLet Will Try To Identify Whether There Are Newer Entries For The Enumerated Enabled Ones. In Case Such Are Identified All Older Entries Will Be Disabled And Only The Newer One Will Remain Enabled. Additionally The CmdLet Will Evaluate Whether All Enabled Monitored Files Exist. In Case Some Do Not They Will Be automatically Disabled From Monitoring. From That Perspective It Is Not A Good Idea To Modify The NTFS Permissions Or To Revoke The Access Of The Security Principal That Is Running The CmdLet During The Monitoring. If The CmdLet Looses The Access And Cannot Verify Their Existence, Will Decide That They Are Deleted And Will Disable The Corresponding Monitoring Entries. </para> <para type="description"> -- Before The Finish The Monitored Script Have To Run Disable-SnsScriptMonitoring To Set Its Monitoring Entry With Disabled Date. This Is Required To Prevent False Positives Related With Failed Scripts Which Actually Completed Successfully. There Is No Specific Requirement That This CmdLet Have To Be Executed From Within The Monitored Script As Long As The Correct Path Is Provided To The CmdLet. </para> <para type="description"> The SnsPsScriptsMonitoring Does Not Read What Is Inside The Monitored Files Or Monitored Scripts. It Does Not Send Any Information Outside Its Own Monitoring DataBase Stored Locally. The Module Have No Any Network Capabilities. All The Actions Are Performed Locally. In Case You Need To Put The Monitored File Or The Script On Network Located Resource, Is Possible But You Have To Do It On Such A Manner To Be Presented To The Monitoring PS Module As Local Resource. For Example Map Network Drive. </para> <para type="description"> The SnsPsScriptsMonitoring Does Not Send Any Information Over The Internet. Although It Needs Internet To Verify About Newer Versions. If You Feel This As A Tread Or You Need To Run The Module On A Machine Without Network Connection, You Can Modify The Module .PSM1 File To Not Search For Newer Versions. However You Are Missing Any Future New Features Or Bug Fixes If Any Are Reported Or Discovered. You Still Can Install The Newer Versions Manually. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov (svesavov@hotmail.com)</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 PSCustomObject With The Monitoring Entry</para> </summary> </member> <member name="T:SnsPsScriptsMonitoring.EnableSnsScriptMonitoring"> <summary> <para type="synopsis"> This CmdLet Creates A Monitoring Entry In The Monitoring DataBase. </para> <para type="description"> This CmdLet Creates A Monitoring Entry In The Monitoring DataBase. </para> <para type="description"> The Way That This Module Monitors About Failed Scripts, Requires The Monitored Scripts To Write Some Output On A File, Either Transcript Or Log Ones, Called Here Monitored File. Then Get-SnsMonitoringEntry CmdLet Have To Be Executed From Another Script On A Schedule. During The Execution Of The CmdLet It Verifies Whether The Script Process Is running Or The Monitored File Has Not Been Updated For Specified Amount OF Time. In Order The Monitoring To Work Properly The Account Under Who’s Security Context Is Run The Get-SnsMonitoringEntry CmdLet Must Have Enough NTFS Permissions To Verify The Monitored File Existence And LastWriteTime (Modified) File Property. </para> <para type="description"> In Order The Monitoring To Work Smoothly It Requires Some CmdLets From This Module To Be Run From Within The Monitored Script And Some CmdLets To Be Run From Dedicated Monitoring Script. </para> <para type="description"> -- The SnsPsScriptsMonitoring Uses A SQLite V3 Serverless DataBase To Keep Track Of The Monitored Scripts And Essential For Their Monitoring 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"> "C:\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 Have To Be In Elevated PowerShell Process. The Consequent Loads Of The Module Doesn’t Require Elevated Mode In Most Of The Cases, Except The Scenario Whenever The Failed Scripts Have To Be Restarted. </para> <para type="description"> The Information Kept In The Monitoring DataBase Is: "Directory", "Script", "MonitoredFile", "Task", "Pid", "Threshold", "Enabled" And "Disabled". </para> <para type="description"> "Directory" Is The Folder Where The Monitored File Reside. This Information Is Automatically Generated From The Specified Monitored File. </para> <para type="description"> "Script" Is The .PS1 File Of The Monitored Script. This Information Is Automatically Generated. In Order The Monitored Script To Be Identified Correctly Enable-SnsScriptMonitoring Have To Be Run From The Monitored Script. In Case The CmdLet Is Included In Additional PowerShell Modules, The CmdLet Will Wrongly Identify The Module File As Monitored Script. This Is Critical Whenever Is Required Automatic Restart OF The Failed Scripts, And For The Automatic Disabling From Monitoring OF Failed Scripts When The Failed Script Is Restarted And Newer Transcript Or Log File Is Enabled For Monitoring. </para> <para type="description"> "MonitoredFile" Is The Full Absolute UNC Path To The Specified Monitored File. This Must Be Specified Explicitly To Enable-SnsScriptMonitoring CmdLet. There Is No Automatic Generation. </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 Generate The With Limited Success. It Is Preferable That Information To Be Specified To Enable-SnsScriptMonitoring CmdLet. </para> <para type="description"> "Pid" Is The Process ID Of The PowerShell Process Where Monitored Script Is Executed. This Is Automatically Generated. In Order The Auto Generate To Identify The Correct Process, The Enable-SnsScriptMonitoring Must Be Run From Inside 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 Failed Scripts. 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 Update Periodically The Specified Monitored File. The Threshold Shall Be Specified Carefully Depending Of The Intervals That The Monitored File Is Updated. Wrong Threshold Could Cause Working Script To Be Stopped And Restarted In The Middle Of Some Heavy Task. </para> <para type="description"> "Enabled" Is The Date And Time When The MonitoredFile Is Inserted In The DataBase And Enabled For Monitoring. </para> <para type="description"> "Disabled" Is The Date And Time When The Monitored Script Finished Successfully And Therefore No Longer Monitored. From That Perspective The CmdLet Disable-SnsScriptMonitoring Have To Be Executed From Within The Monitored Script At The End Of The Script. In Case The Script Fail It Will Not Get To The Point To Disable Itself From Monitoring, And Its Monitoring Entry Will Remain Enabled, Until Get-SnsMonitoringEntry CmdLet Is Executed By The Monitoring Script And The Failure Is Reported Or Actioned. Having That In Mind We Can Imagine That With The Time Will Remain A Lot Of Enabled DataBase Entries Related With Failed Scripts, As They Never Been Disabled. The Get-SnsMonitoringEntry Partially Takes Care About That Via Identifying Newer Monitoring Entries For The Existing Enabled Entries. For Newer Entries Are Considered The Ones That Have The Same Script, The Same Monitored File Directory, And The Same Windows Scheduled Task Path. Considering The Same Monitoring File Is Not An Option Because Whenever The Same File Is Enabled Again Its Previous Entry Is Overwritten Because "MonitoredFile" Column Is Primary Key In The DataBase Table. In Order The Automatic Detection For Newer Monitoring Entries To Work As Expected, The Evaluated Entries Must Have Values In All Of The Mentioned Above 3 Columns. In Case Some Entries Have No Values Them, They Will Be Not Evaluated, And Their Entries Will Remain Enabled In The Monitoring DataBase. To Disable Them The User Can Run Disable-SnsScriptMonitoring Manually To Disable Specific Entry. </para> <para type="description"> In Addition 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 31 Days Ago. Enabled Entries Are Never Threated As Outdated Regardless Of Their Age. </para> <para type="description"> -- The Script Which Have To Be Enabled For Monitoring Have To Run Enable-SnsScriptMonitoring CmdLet From Itself At The Beginning. The CmdLet Requires To Be Provided A Transcript Or Log File Which The Script Update Regularly. </para> <para type="description"> To Ensure That The Monitoring Will Be Able To Restart The Monitored Script The Monitoring Entry Have To Have Scheduled Task And Process Id Of The Monitored Script. The Process Id Is Taken Automatically Via Enumeration Of The Own Process Id. The Windows Scheduled Task Can Be Automatically Enumerated With Limited Success Via Search Among The Windows Schedule Tasks About Task That Have The Monitored Script .PS1 File In "Add arguments (optional):" In The Scheduled Task Action, The Same "Start in (optional):" In The Scheduled Task Action As The Monitored File Directory, Or The Monitored File Directory Have To Be Nested In The Scheduled Task Action "Start in (optional):" Folder. In Case The Enumerated Scheduled Tasks Are Only One Then It Is Considered As Script Scheduled Task. However This To Work The Monitoring Entry Shall Have The Script .PS1 File Which Might Happen Only If Enable-SnsScriptMonitoring Is Executed From The Monitored Script Itself. </para> <para type="description"> With Other Words If The Monitored Script Is Located In One Folder And The Monitored File Is Located In A Folder Not Nested In The Script Folder There Is No Chance The Windows Scheduled Task To Be Identified Correctly. Also When There Are Multiple Scheduled Tasks For A Single Script For Example To Prepare Daily Weekly And Monthly Reports. This Will Means That 3 Scheduled Tasks Will Be Enumerated and The CmdLet Will Not assign Neither Of Them Because It Is Not Certain Which One Of Them Have to Be Restarted For This Monitoring Entry. Therefore It Is Always Preferable The Windows Scheduled Task To Be Specified Via CmdLet Parameter. In That Case The CmdLet Will Not Enumerate The Windows Scheduled Tasks, And Will Complete A Little Bit Faster. </para> <para type="description"> To Ensure That The Proper PowerShell Process Is Stopped Whenever The Script Fail, The Information About The Process ID Is Kept In The Monitoring Entry. In Case The Process IS Still Running And Inactive Depending Of The Monitoring Preferences Get-SnsMonitoringEntry Might Try To Stop The Process And Restart The Failed Script Via Running Of Its Scheduled Task. However The Information About The Process ID IS Dynamically Generated, And In Order To Be Correct The Enable-SnsScriptMonitoring Must Be Executed From The Monitored Script. If It Is Run From Another PowerShell Process, The ID OF That Another PowerShell Process Will Be Inserted In The Monitoring DataBase And In Case Of Failure That Another Process Will Be Stopped. </para> <para type="description"> The Monitored Script Is Not Specified At All. The CmdLet Enumerates From The MyInvocationInfo Object Who Called The CmdLet. To Ensure That The Monitoring Features Works As Expected It IS Very Important The CmdLet To Ba Called From The Script Itself. In Case The Script Uses Its Own Module And The Monitoring Enablement IS Called From There The MyInvocationInfo Object Will Revert The Module Instead OF The Script. Which Might Lead To Improper Behavior Of The Monitoring. </para> <para type="description"> -- During The Monitored Script Running There Have To Be Another Script Executed On A Schedule Every Few Minutes Depending Of The Desired Outcome And Needed Threshold. The Monitoring Script Have To Invoke Get-SnsMonitoringEntry CmdLet In Regular Intervals To Get Information About The Status Of The Monitored Scripts. Depending Of The Specified To The CmdLet Parameters It Can: </para> <para type="description"> Enumerate Specific Monitoring Entry Present In The Monitoring DataBase Regardless Whether It Is Enabled Or Disabled. </para> <para type="description"> Enumerate All Monitoring Entries Present In The Monitoring DataBase Regardless Whether They Are Enabled Or Disabled. Although This Parameter Set Looks Like Suitable To Prepare A Report When The Monitored Scripts Are Ran, It Actually Is Not Suitable For That Purpose. The Problem Is That The "MonitoredFile" Column Is Primary Key In The Monitoring Table. Which Means That It Can Have Unique Values Only. In The Cases When Specific Script Creates A Transcript Or Log File With The Same Name And Path On Each Execution. There Will Be Only One Monitoring Entry For That Script, Because On Each Script Ran The Previous Monitoring Entry Will Be Overwritten, And The Monitoring DataBase Will Keep Only One Entry For Multiple Script Executions. In The Real Life The Monitored file Will Be Overwritten As Well, So In The DataBase Logic There Is No Big Difference. If You Ensure That Each Monitored Script Will Create Different New Transcript Or Log File To Be Monitored, Then The Data From The Monitoring DataBase Can Be Used For Statistics Reports. </para> <para type="description"> Enumerate All Enabled Monitoring Entries To The Moment Of The CmdLet Execution. </para> <para type="description"> Enumerate All Enabled Failed Monitoring Entries To The Moment Of The CmdLet Execution. As Failed Are Considered The Scripts Which Did Not Updated Their Transcript Or Log Files For Longer Than The Specified Threshold Or Their Process Is No Longer Running. </para> <para type="description"> If "RestartFailed" Switch Parameter Is Specified, To Stop The Processes Of The Failed Scripts If They Are Still Running And Restart Their Scheduled Tasks. "RestartFailed" Is Available Only In "Enabled" And "Failed" Parameter Sets. It Will Work Only If The CmdLet Is Executed In Elevated Mode And All The Needed Information Is Available In The Monitoring Entry Inside The Monitoring DataBase. </para> <para type="description"> Regardless Of The ParameterSet The CmdLet Will Try To Identify Whether There Are Newer Entries For The Enumerated Enabled Ones. In Case Such Are Identified All Older Entries Will Be Disabled And Only The Newer One Will Remain Enabled. Additionally The CmdLet Will Evaluate Whether All Enabled Monitored Files Exist. In Case Some Do Not They Will Be automatically Disabled From Monitoring. From That Perspective It Is Not A Good Idea To Modify The NTFS Permissions Or To Revoke The Access Of The Security Principal That Is Running The CmdLet During The Monitoring. If The CmdLet Looses The Access And Cannot Verify Their Existence, Will Decide That They Are Deleted And Will Disable The Corresponding Monitoring Entries. </para> <para type="description"> -- Before The Finish The Monitored Script Have To Run Disable-SnsScriptMonitoring To Set Its Monitoring Entry With Disabled Date. This Is Required To Prevent False Positives Related With Failed Scripts Which Actually Completed Successfully. There Is No Specific Requirement That This CmdLet Have To Be Executed From Within The Monitored Script As Long As The Correct Path Is Provided To The CmdLet. </para> <para type="description"> The SnsPsScriptsMonitoring Does Not Read What Is Inside The Monitored Files Or Monitored Scripts. It Does Not Send Any Information Outside Its Own Monitoring DataBase Stored Locally. The Module Have No Any Network Capabilities. All The Actions Are Performed Locally. In Case You Need To Put The Monitored File Or The Script On Network Located Resource, Is Possible But You Have To Do It On Such A Manner To Be Presented To The Monitoring PS Module As Local Resource. For Example Map Network Drive. </para> <para type="description"> The SnsPsScriptsMonitoring Does Not Send Any Information Over The Internet. Although It Needs Internet To Verify About Newer Versions. If You Feel This As A Tread Or You Need To Run The Module On A Machine Without Network Connection, You Can Modify The Module .PSM1 File To Not Search For Newer Versions. However You Are Missing Any Future New Features Or Bug Fixes If Any Are Reported Or Discovered. You Still Can Install The Newer Versions Manually. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov (svesavov@hotmail.com)</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 Generate It</para> <para type="description">If Auto Generation Fail And The Monitoring Entry Is Created Without Scheduled Task</para> <para type="description">The Monitoring CmdLet Will Not Attempt To Restart The Script In Case The Script Fail</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 Specified Carefully. It Might Happen That The Monitored Script Makes Some Heavy Tasks Against Remote Location. Like For Example To Get Azure Logs With Thousands Of Entries Over Internet. This Could Take Several Minutes. During That Time The Monitored Script Will Be Unable To Update Its Transcript Or Log File. If The Threshold Is Less Than The Time Required For The Next Update, The Monitoring CmdLet Will Wrongly Identify The Monitored Script As Failed And Depending Of The Specified Parameters Might Restart The Script In The Middle Of The Task. </para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.EnableSnsScriptMonitoring.PassThru"> <summary> <para type="description">Specifies To The CmdLet To Revert A PSCustomObject With The Monitoring Entry</para> </summary> </member> <member name="T:SnsPsScriptsMonitoring.GetSnsMonitoringEntry"> <summary> <para type="synopsis"> This CmdLet Enumerates Monitoring Entries, Evaluates About Failed Scripts And If Needed Restarts Them. </para> <para type="description"> This CmdLet Enumerates Monitoring Entries, Evaluates About Failed Scripts And If Needed Restarts Them. </para> <para type="description"> The Way That This Module Monitors About Failed Scripts, Requires The Monitored Scripts To Write Some Output On A File, Either Transcript Or Log Ones, Called Here Monitored File. Then Get-SnsMonitoringEntry CmdLet Have To Be Executed From Another Script On A Schedule. During The Execution Of The CmdLet It Verifies Whether The Script Process Is running Or The Monitored File Has Not Been Updated For Specified Amount OF Time. In Order The Monitoring To Work Properly The Account Under Who’s Security Context Is Run The Get-SnsMonitoringEntry CmdLet Must Have Enough NTFS Permissions To Verify The Monitored File Existence And LastWriteTime (Modified) File Property. </para> <para type="description"> In Order The Monitoring To Work Smoothly It Requires Some CmdLets From This Module To Be Run From Within The Monitored Script And Some CmdLets To Be Run From Dedicated Monitoring Script. </para> <para type="description"> -- The SnsPsScriptsMonitoring Uses A SQLite V3 Serverless DataBase To Keep Track Of The Monitored Scripts And Essential For Their Monitoring 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"> "C:\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 Have To Be In Elevated PowerShell Process. The Consequent Loads Of The Module Doesn’t Require Elevated Mode In Most Of The Cases, Except The Scenario Whenever The Failed Scripts Have To Be Restarted. </para> <para type="description"> The Information Kept In The Monitoring DataBase Is: "Directory", "Script", "MonitoredFile", "Task", "Pid", "Threshold", "Enabled" And "Disabled". </para> <para type="description"> "Directory" Is The Folder Where The Monitored File Reside. This Information Is Automatically Generated From The Specified Monitored File. </para> <para type="description"> "Script" Is The .PS1 File Of The Monitored Script. This Information Is Automatically Generated. In Order The Monitored Script To Be Identified Correctly Enable-SnsScriptMonitoring Have To Be Run From The Monitored Script. In Case The CmdLet Is Included In Additional PowerShell Modules, The CmdLet Will Wrongly Identify The Module File As Monitored Script. This Is Critical Whenever Is Required Automatic Restart OF The Failed Scripts, And For The Automatic Disabling From Monitoring OF Failed Scripts When The Failed Script Is Restarted And Newer Transcript Or Log File Is Enabled For Monitoring. </para> <para type="description"> "MonitoredFile" Is The Full Absolute UNC Path To The Specified Monitored File. This Must Be Specified Explicitly To Enable-SnsScriptMonitoring CmdLet. There Is No Automatic Generation. </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 Generate The With Limited Success. It Is Preferable That Information To Be Specified To Enable-SnsScriptMonitoring CmdLet. </para> <para type="description"> "Pid" Is The Process ID Of The PowerShell Process Where Monitored Script Is Executed. This Is Automatically Generated. In Order The Auto Generate To Identify The Correct Process, The Enable-SnsScriptMonitoring Must Be Run From Inside 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 Failed Scripts. 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 Update Periodically The Specified Monitored File. The Threshold Shall Be Specified Carefully Depending Of The Intervals That The Monitored File Is Updated. Wrong Threshold Could Cause Working Script To Be Stopped And Restarted In The Middle Of Some Heavy Task. </para> <para type="description"> "Enabled" Is The Date And Time When The MonitoredFile Is Inserted In The DataBase And Enabled For Monitoring. </para> <para type="description"> "Disabled" Is The Date And Time When The Monitored Script Finished Successfully And Therefore No Longer Monitored. From That Perspective The CmdLet Disable-SnsScriptMonitoring Have To Be Executed From Within The Monitored Script At The End Of The Script. In Case The Script Fail It Will Not Get To The Point To Disable Itself From Monitoring, And Its Monitoring Entry Will Remain Enabled, Until Get-SnsMonitoringEntry CmdLet Is Executed By The Monitoring Script And The Failure Is Reported Or Actioned. Having That In Mind We Can Imagine That With The Time Will Remain A Lot Of Enabled DataBase Entries Related With Failed Scripts, As They Never Been Disabled. The Get-SnsMonitoringEntry Partially Takes Care About That Via Identifying Newer Monitoring Entries For The Existing Enabled Entries. For Newer Entries Are Considered The Ones That Have The Same Script, The Same Monitored File Directory, And The Same Windows Scheduled Task Path. Considering The Same Monitoring File Is Not An Option Because Whenever The Same File Is Enabled Again Its Previous Entry Is Overwritten Because "MonitoredFile" Column Is Primary Key In The DataBase Table. In Order The Automatic Detection For Newer Monitoring Entries To Work As Expected, The Evaluated Entries Must Have Values In All Of The Mentioned Above 3 Columns. In Case Some Entries Have No Values Them, They Will Be Not Evaluated, And Their Entries Will Remain Enabled In The Monitoring DataBase. To Disable Them The User Can Run Disable-SnsScriptMonitoring Manually To Disable Specific Entry. </para> <para type="description"> In Addition 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 31 Days Ago. Enabled Entries Are Never Threated As Outdated Regardless Of Their Age. </para> <para type="description"> -- The Script Which Have To Be Enabled For Monitoring Have To Run Enable-SnsScriptMonitoring CmdLet From Itself At The Beginning. The CmdLet Requires To Be Provided A Transcript Or Log File Which The Script Update Regularly. </para> <para type="description"> To Ensure That The Monitoring Will Be Able To Restart The Monitored Script The Monitoring Entry Have To Have Scheduled Task And Process Id Of The Monitored Script. The Process Id Is Taken Automatically Via Enumeration Of The Own Process Id. The Windows Scheduled Task Can Be Automatically Enumerated With Limited Success Via Search Among The Windows Schedule Tasks About Task That Have The Monitored Script .PS1 File In "Add arguments (optional):" In The Scheduled Task Action, The Same "Start in (optional):" In The Scheduled Task Action As The Monitored File Directory, Or The Monitored File Directory Have To Be Nested In The Scheduled Task Action "Start in (optional):" Folder. In Case The Enumerated Scheduled Tasks Are Only One Then It Is Considered As Script Scheduled Task. However This To Work The Monitoring Entry Shall Have The Script .PS1 File Which Might Happen Only If Enable-SnsScriptMonitoring Is Executed From The Monitored Script Itself. </para> <para type="description"> With Other Words If The Monitored Script Is Located In One Folder And The Monitored File Is Located In A Folder Not Nested In The Script Folder There Is No Chance The Windows Scheduled Task To Be Identified Correctly. Also When There Are Multiple Scheduled Tasks For A Single Script For Example To Prepare Daily Weekly And Monthly Reports. This Will Means That 3 Scheduled Tasks Will Be Enumerated and The CmdLet Will Not assign Neither Of Them Because It Is Not Certain Which One Of Them Have to Be Restarted For This Monitoring Entry. Therefore It Is Always Preferable The Windows Scheduled Task To Be Specified Via CmdLet Parameter. In That Case The CmdLet Will Not Enumerate The Windows Scheduled Tasks, And Will Complete A Little Bit Faster. </para> <para type="description"> To Ensure That The Proper PowerShell Process Is Stopped Whenever The Script Fail, The Information About The Process ID Is Kept In The Monitoring Entry. In Case The Process IS Still Running And Inactive Depending Of The Monitoring Preferences Get-SnsMonitoringEntry Might Try To Stop The Process And Restart The Failed Script Via Running Of Its Scheduled Task. However The Information About The Process ID IS Dynamically Generated, And In Order To Be Correct The Enable-SnsScriptMonitoring Must Be Executed From The Monitored Script. If It Is Run From Another PowerShell Process, The ID OF That Another PowerShell Process Will Be Inserted In The Monitoring DataBase And In Case Of Failure That Another Process Will Be Stopped. </para> <para type="description"> The Monitored Script Is Not Specified At All. The CmdLet Enumerates From The MyInvocationInfo Object Who Called The CmdLet. To Ensure That The Monitoring Features Works As Expected It IS Very Important The CmdLet To Ba Called From The Script Itself. In Case The Script Uses Its Own Module And The Monitoring Enablement IS Called From There The MyInvocationInfo Object Will Revert The Module Instead OF The Script. Which Might Lead To Improper Behavior Of The Monitoring. </para> <para type="description"> -- During The Monitored Script Running There Have To Be Another Script Executed On A Schedule Every Few Minutes Depending Of The Desired Outcome And Needed Threshold. The Monitoring Script Have To Invoke Get-SnsMonitoringEntry CmdLet In Regular Intervals To Get Information About The Status Of The Monitored Scripts. Depending Of The Specified To The CmdLet Parameters It Can: </para> <para type="description"> Enumerate Specific Monitoring Entry Present In The Monitoring DataBase Regardless Whether It Is Enabled Or Disabled. </para> <para type="description"> Enumerate All Monitoring Entries Present In The Monitoring DataBase Regardless Whether They Are Enabled Or Disabled. Although This Parameter Set Looks Like Suitable To Prepare A Report When The Monitored Scripts Are Ran, It Actually Is Not Suitable For That Purpose. The Problem Is That The "MonitoredFile" Column Is Primary Key In The Monitoring Table. Which Means That It Can Have Unique Values Only. In The Cases When Specific Script Creates A Transcript Or Log File With The Same Name And Path On Each Execution. There Will Be Only One Monitoring Entry For That Script, Because On Each Script Ran The Previous Monitoring Entry Will Be Overwritten, And The Monitoring DataBase Will Keep Only One Entry For Multiple Script Executions. In The Real Life The Monitored file Will Be Overwritten As Well, So In The DataBase Logic There Is No Big Difference. If You Ensure That Each Monitored Script Will Create Different New Transcript Or Log File To Be Monitored, Then The Data From The Monitoring DataBase Can Be Used For Statistics Reports. </para> <para type="description"> Enumerate All Enabled Monitoring Entries To The Moment Of The CmdLet Execution. </para> <para type="description"> Enumerate All Enabled Failed Monitoring Entries To The Moment Of The CmdLet Execution. As Failed Are Considered The Scripts Which Did Not Updated Their Transcript Or Log Files For Longer Than The Specified Threshold Or Their Process Is No Longer Running. </para> <para type="description"> If "RestartFailed" Switch Parameter Is Specified, To Stop The Processes Of The Failed Scripts If They Are Still Running And Restart Their Scheduled Tasks. "RestartFailed" Is Available Only In "Enabled" And "Failed" Parameter Sets. It Will Work Only If The CmdLet Is Executed In Elevated Mode And All The Needed Information Is Available In The Monitoring Entry Inside The Monitoring DataBase. </para> <para type="description"> Regardless Of The ParameterSet The CmdLet Will Try To Identify Whether There Are Newer Entries For The Enumerated Enabled Ones. In Case Such Are Identified All Older Entries Will Be Disabled And Only The Newer One Will Remain Enabled. Additionally The CmdLet Will Evaluate Whether All Enabled Monitored Files Exist. In Case Some Do Not They Will Be automatically Disabled From Monitoring. From That Perspective It Is Not A Good Idea To Modify The NTFS Permissions Or To Revoke The Access Of The Security Principal That Is Running The CmdLet During The Monitoring. If The CmdLet Looses The Access And Cannot Verify Their Existence, Will Decide That They Are Deleted And Will Disable The Corresponding Monitoring Entries. </para> <para type="description"> -- Before The Finish The Monitored Script Have To Run Disable-SnsScriptMonitoring To Set Its Monitoring Entry With Disabled Date. This Is Required To Prevent False Positives Related With Failed Scripts Which Actually Completed Successfully. There Is No Specific Requirement That This CmdLet Have To Be Executed From Within The Monitored Script As Long As The Correct Path Is Provided To The CmdLet. </para> <para type="description"> The SnsPsScriptsMonitoring Does Not Read What Is Inside The Monitored Files Or Monitored Scripts. It Does Not Send Any Information Outside Its Own Monitoring DataBase Stored Locally. The Module Have No Any Network Capabilities. All The Actions Are Performed Locally. In Case You Need To Put The Monitored File Or The Script On Network Located Resource, Is Possible But You Have To Do It On Such A Manner To Be Presented To The Monitoring PS Module As Local Resource. For Example Map Network Drive. </para> <para type="description"> The SnsPsScriptsMonitoring Does Not Send Any Information Over The Internet. Although It Needs Internet To Verify About Newer Versions. If You Feel This As A Tread Or You Need To Run The Module On A Machine Without Network Connection, You Can Modify The Module .PSM1 File To Not Search For Newer Versions. However You Are Missing Any Future New Features Or Bug Fixes If Any Are Reported Or Discovered. You Still Can Install The Newer Versions Manually. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov (svesavov@hotmail.com)</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-SnsMonitoringEntry -Path "C:\Transcript.txt"; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsMonitoringEntry -All; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsMonitoringEntry -Enabled; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsMonitoringEntry -Failed; </code> <para></para> </example> <example> <code> [SnsPsScriptsMonitoring.MonitoringEntry[]]$arrEntries = Get-SnsMonitoringEntry -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.GetSnsMonitoringEntry.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.GetSnsMonitoringEntry.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.GetSnsMonitoringEntry.Enabled"> <summary> <para type="description">Specifies To The CmdLet To Revert Only The Enabled Entries Without To Verify About Failures</para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.GetSnsMonitoringEntry.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 </para> <para type="description"> As Failed Are Considered The Scripts Which Did Not Updated Their Transcript Or Log Files For More Than The Specified Threshold Or Their Process Is No Longer Running </para> </summary> </member> <member name="P:SnsPsScriptsMonitoring.GetSnsMonitoringEntry.RestartFailed"> <summary> <para type="description">Specifies To The CmdLet To Try To Restart The Failed Scripts</para> <para type="description"> In Order This Feature To Work The Monitoring Entry Shall Contain Information About The Process Id Of The PowerShell Process That Is Running The Monitored Script. This Information Is Provided Automatically By Enable-SnsScriptMonitoring CmdLet. However In Order The Information To Be Correct The CmdLet Have To Be Ran From The Monitored Script. </para> <para type="description"> In Order The CmdLet To Actually Restart The Script It Will Need Information About The Windows Scheduled Task That Have To Be Restarted. In Order This To Work Properly The Scheduled Task Have To Be Configured To Allow Run On Demand. The Scheduled Task Is Provided When The Monitoring Entry Is Created To Enable-SnsScriptMonitoring CmdLet With A Parameter. If Not Provided The CmdLet Will Try To Identify It Automatically. To Avoid Any False Positives Please Make Sure That The Windows Scheduled Task Path Is Specified. </para> </summary> </member> <member name="T:SnsPsScriptsMonitoring.InitializeSnsModuleState"> <summary> <para type="synopsis"> This CmdLet Verifies The Monitoring DataBase Existence And Creates It If Needed. </para> <para type="description"> This CmdLet Verifies The Monitoring DataBase Existence And Creates It If Needed. </para> <para type="description"> The CmdLet Is Intended To Be Hidden For The User And To Be Executed Once When The PowerShell Module Is Loaded. </para> <para type="description"> The SnsPsScriptsMonitoring PowerShell Module Uses A SQLite Serverless DataBase To Store The Required Information About The Scripts Enabled For Monitoring. 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 Of 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"> "C:\ProgramData\SnsPsScriptsMonitoring\SnsScrMon.db" </para> <para type="description"> The Monitoring DataBase Used Is A Simple One With A Single Table. During The PowerShell Module Load The Monitoring DataBase Is Verified About: </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. </para> <para type="description"> -- The NTFS Permissions Of The DataBase Folder. "Full Control" Is Granted To Local Users Group. </para> <para type="description"> -- The Existence Of The DataBase File. In Case The DataBase Is Missing The Module Creates One. </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. </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, Either The Table Is Deleted And New One Is Created Or The Module Exit With Termination Error. The Current Configuration Is To Recreate The Table. The Table Recreation Is Related With Data Lost Which Will Cause All Already Enabled For Monitoring Scripts To Be No Longer Monitored. </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. </para> <para type="description"> -- The CmdLet Verifies About Outdated Entries Related With Scripts Not Being Monitored For More Than 31 Days. In Case The PowerShell Module Detect Existence Of Entries Outdated For More Than 40 Days The User Input Will Be Ignored And Deletion Of The Outdated Entries Is Enabled. In Case The Deletion Is Enabled The CmdLet Defragment The Monitoring DataBase And Compact The DataBase File In Order To Release The White Space To The Operating System. </para> <para type="description"> All The Verifications Above Except The Test Entry Creation And Deletion And The Deletion Of The Outdated Entries With Defragmentation And Compacting Are Performed At The Beginning Of Each CmdLet As Well. The Ones That Actively Perform Tests And Defragmentation With Compacting Are Performed Just Once Per Session. In Case The Initial Run Of This CmdLet Is Removed By The User, This CmdLet Is Executed At The Beginning Of The Each Of The Rest CmdLets In The Module. Which Only Slows Down Them When They Are Ran For The First Time. </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"> [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] DATETIME NOT NULL DEFAULT(datetime('now','localtime')), </para> <para type="description"> [Disabled] DATETIME NULL </para> <para type="description"> ); </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 Produce This File Is Considered As Failed Whenever The File Was Not Updated For Period Of Time 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 That Stop The Failed Scripts Processes And Restarts Their Tasks. This Information Is Not Required As Long As The Restarting Feature Is Not Required. 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 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. In Case The Script Fail On Some Execution It Will Not Disable Its Own Entry. Lets Assume The CmdLet For Monitoring Detect That And Restart 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 For The Failed Instance Since The New Instance Is Already Running. For The Enabled And Failed Scripts That This Is Not Applicable The Monitoring Entry Will Remain And The Script Will Continue To Be Reported As Failed Until A User Manually Disable The Entry Using Disable-SnsScriptMonitoring CmdLet. </para> <para type="description"> The "Enabled" And "Disabled" Columns Actually Determine Whether A Transcript Or Log File From A Script Will Be Monitored About Last Write Time. Each Entry Is Created As Enabled. With Other Words The "Enabled" Column Shall Contain The DateTime When The Entry Was Created And Enabled. The "Disabled" Column Shall Contain The DateTime When The Entry Was Disabled And The Script No Longer Monitored. </para> <list type="alertSet"> <item> <term> </term> <description> <para>AUTHOR: Svetoslav Nedyalkov Savov (svesavov@hotmail.com)</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 -DropTableIfVerificationFail -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.DropTableIfVerificationFail"> <summary> <para type="description">Specifies To The CmdLet To Drop The Monitoring Table If The Schema Verification Fails.</para> </summary> </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 6 Months. </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> </summary> </member> </members> </doc> |