BHoM_Engine: Enhance the logging functionality by including ability t…

…o suppress logging if desired (#3286)

BHoM_Engine/Compute/RecordEvent.cs

@@ -25,7 +25,6 @@
 using System.Linq;
 using System.ComponentModel;
 using System;
-using BH.Engine.Base.Objects;
 
 namespace BH.Engine.Base
 {
@@ -96,14 +95,28 @@ public static bool RecordEvent(Event newEvent)
                 newEvent.StackTrace = string.Join("\n", trace.Split('\n').Skip(4).ToArray());
             }
 
+            bool suppressEvents = (newEvent.Type == EventType.Error && m_SuppressError) 
+                                || (newEvent.Type == EventType.Warning && m_SuppressWarning)
+                                || (newEvent.Type == EventType.Note && m_SuppressNote);
+
+            Log log = null;
+            if (!suppressEvents)
+                log = Query.DebugLog();
+            else
+                log = Query.SuppressedLog();
+
             lock (Global.DebugLogLock)
             {
-                Log log = Query.DebugLog();
                 log.AllEvents.Add(newEvent);
                 log.CurrentEvents.Add(newEvent);
-                OnEventRecorded(newEvent);
+
+                if(!suppressEvents)
+                    OnEventRecorded(newEvent); //Only raise an event if we're not in switched off mode
             }
 
+            if (newEvent.Type == EventType.Error && !m_SuppressErrorThrowing && !m_SuppressError) //Only throw the event as an exception if someone has asked us to throw it, AND we aren't suppressing them
+                throw new Exception(newEvent.ToText());
+
             return true;
         }
 
@@ -129,6 +142,15 @@ private static void OnEventRecorded(Event ev)
         }
 
         /***************************************************/
+        /**** Private Variables                         ****/
+        /***************************************************/
+
+        private static bool m_SuppressError = false; //Default to false, do not suppress any events which come through the system
+        private static bool m_SuppressWarning = false;
+        private static bool m_SuppressNote = false;
+
+        private static bool m_SuppressErrorThrowing = true; //Default to true - do not throw errors as exceptions. However, if a user (developer user or UI user) has unsuppressed this, then errors will be thrown for try/catch statements to handle.
+        //ToDo: Discuss whether we want this to be true by default and have BHoM_UI switch it off on load, or keep as is. FYI @alelom
     }
 }
 

BHoM_Engine/Compute/RetrieveSuppressedLog.cs

@@ -0,0 +1,55 @@
+/*
+ * This file is part of the Buildings and Habitats object Model (BHoM)
+ * Copyright (c) 2015 - 2024, the respective contributors. All rights reserved.
+ *
+ * Each contributor holds copyright over their respective contributions.
+ * The project versioning (Git) records all such contribution source information.
+ *                                           
+ *                                                                              
+ * The BHoM is free software: you can redistribute it and/or modify         
+ * it under the terms of the GNU Lesser General Public License as published by  
+ * the Free Software Foundation, either version 3.0 of the License, or          
+ * (at your option) any later version.                                          
+ *                                                                              
+ * The BHoM is distributed in the hope that it will be useful,              
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of               
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the                 
+ * GNU Lesser General Public License for more details.                          
+ *                                                                            
+ * You should have received a copy of the GNU Lesser General Public License     
+ * along with this code. If not, see <https://www.gnu.org/licenses/lgpl-3.0.html>.      
+ */
+
+using BH.oM.Base.Debugging;
+using BH.oM.Base.Attributes;
+using System.Linq;
+using System.ComponentModel;
+using System;
+
+namespace BH.Engine.Base
+{
+    public static partial class Compute
+    {
+        /***************************************************/
+        /**** Public Methods                            ****/
+        /***************************************************/
+
+        [Description("Retrieve the events recorded while the logging system was switched off and put them into the main log. When the logging system is switched off, recording of events is done in quiet mode which means UIs are not made aware of the events and the main event log does not have knowledge of them. We still record the events though because they may be useful. This method will move any events stored within the log when it was switched off up to the main log for visibiliy and inspection, and will reset the quiet log to a clean state.")]
+        [Output("True if no error occurs in moving up events recorded during a quiet period.")]
+        public static bool RetrieveSuppressedLog()
+        {
+            lock(Global.DebugLogLock)
+            {
+                Log switchedOffLog = Query.SuppressedLog();
+                Log debugLog = Query.DebugLog();
+
+                debugLog.CurrentEvents.AddRange(switchedOffLog.CurrentEvents);
+                debugLog.AllEvents.AddRange(switchedOffLog.AllEvents);
+
+                Query.ResetSuppressedLog(); //Now we've moved the switched off log events into the main log, we don't need the switched off log to also keep a copy of them
+            }
+
+            return true;
+        }
+    }
+}

BHoM_Engine/Compute/SuppressRecording.cs

@@ -0,0 +1,64 @@
+/*
+ * This file is part of the Buildings and Habitats object Model (BHoM)
+ * Copyright (c) 2015 - 2024, the respective contributors. All rights reserved.
+ *
+ * Each contributor holds copyright over their respective contributions.
+ * The project versioning (Git) records all such contribution source information.
+ *                                           
+ *                                                                              
+ * The BHoM is free software: you can redistribute it and/or modify         
+ * it under the terms of the GNU Lesser General Public License as published by  
+ * the Free Software Foundation, either version 3.0 of the License, or          
+ * (at your option) any later version.                                          
+ *                                                                              
+ * The BHoM is distributed in the hope that it will be useful,              
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of               
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the                 
+ * GNU Lesser General Public License for more details.                          
+ *                                                                            
+ * You should have received a copy of the GNU Lesser General Public License     
+ * along with this code. If not, see <https://www.gnu.org/licenses/lgpl-3.0.html>.      
+ */
+
+using BH.oM.Base.Debugging;
+using BH.oM.Base.Attributes;
+using System.Linq;
+using System.ComponentModel;
+using System;
+
+namespace BH.Engine.Base
+{
+    public static partial class Compute
+    {
+        /***************************************************/
+        /**** Public Methods                            ****/
+        /***************************************************/
+
+        [Description("Suppress the logging system used within BHoM. Any part of the code base which tries to log notes, warnings, or errors into the log system will be housed in the suppressed log and not displayed to users depending on which systems you've chosen to suppress. By default, all recording systems are turned on when BHoM is initialised.")]
+        [Input("suppressErrors", "Determine whether to suppress BHoM Events of type ERROR from the log. Set to true to suppress these events.")]
+        [Input("suppressWarnings", "Determine whether to suppress BHoM Events of type WARNING from the log. Set to true to suppress these events.")]
+        [Input("suppressNotes", "Determine whether to suppress BHoM Events of type NOTE from the log. Set to true to suppress these events.")]
+        public static void StartSuppressRecordingEvents(bool suppressErrors = false, bool suppressWarnings = false, bool suppressNotes = false)
+        {
+            //Only change the state of each suppresion flag if it is set to true - this will prevent the scenario where MethodA suppresses everything, then calls MethodB which suppresses only Warnings and the false flags would turn on errors/notes which MethodA wouldn't want - this will ensure that the suppresions are set until the StopSuppressRecordingEvents is called
+            if(suppressErrors)
+                m_SuppressError = suppressErrors;
+
+            if(suppressWarnings)
+                m_SuppressWarning = suppressWarnings;
+
+            if(suppressNotes)
+                m_SuppressNote = suppressNotes;
+        }
+
+        /***************************************************/
+
+        [Description("Switch on the entire logging system used within BHoM. By default all recording systems are switched on when BHoM is initialised. Events of all types will be logged after this component has been used regardless of which ones were previously suppressed.")]
+        public static void StopSuppressRecordingEvents()
+        {
+            m_SuppressError = false;
+            m_SuppressWarning = false;
+            m_SuppressNote = false;
+        }
+    }
+}

BHoM_Engine/Compute/ThrowError.cs

@@ -0,0 +1,44 @@
+/*
+ * This file is part of the Buildings and Habitats object Model (BHoM)
+ * Copyright (c) 2015 - 2024, the respective contributors. All rights reserved.
+ *
+ * Each contributor holds copyright over their respective contributions.
+ * The project versioning (Git) records all such contribution source information.
+ *                                           
+ *                                                                              
+ * The BHoM is free software: you can redistribute it and/or modify         
+ * it under the terms of the GNU Lesser General Public License as published by  
+ * the Free Software Foundation, either version 3.0 of the License, or          
+ * (at your option) any later version.                                          
+ *                                                                              
+ * The BHoM is distributed in the hope that it will be useful,              
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of               
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the                 
+ * GNU Lesser General Public License for more details.                          
+ *                                                                            
+ * You should have received a copy of the GNU Lesser General Public License     
+ * along with this code. If not, see <https://www.gnu.org/licenses/lgpl-3.0.html>.      
+ */
+
+using BH.oM.Base.Debugging;
+using BH.oM.Base.Attributes;
+using System.Linq;
+using System.ComponentModel;
+using System;
+
+namespace BH.Engine.Base
+{
+    public static partial class Compute
+    {
+        /***************************************************/
+        /**** Public Methods                            ****/
+        /***************************************************/
+
+        [Description("Decide whether or not to have BHoM Events of type error thrown as C# excceptions or not. Default behaviour of BHoM Event log is for errors to NOT be thrown. Turn this off if you would like to catch BHoM Events of type error as C# exceptions.")]
+        [Input("suppressErrorThrowing", "Set this to false if you want to have BHoM Events of type Error to be thrown when they are logged. Set this to true if you do NOT want this to happen (default BHoM Log behaviour).")]
+        public static void ThrowError(bool suppressErrorThrowing)
+        {
+            m_SuppressErrorThrowing = suppressErrorThrowing;
+        }
+    }
+}

BHoM_Engine/Convert/ToText.cs

@@ -29,6 +29,7 @@
 using System.Threading.Tasks;
 using BH.oM.Base.Attributes;
 using BH.oM.Base.Attributes.Enums;
+using BH.oM.Base.Debugging;
 
 namespace BH.Engine.Base
 {
@@ -160,6 +161,7 @@ public static string ToText(this MethodBase method, bool includePath = false, st
         [Description("Provides a human-friendly text representation of a type.")]
         [Input("type", "type to convert to text.")]
         [Input("includePath", "If true, the path/namespace will be provided.")]
+        [Input("replaceGeneric", "If true, generic types will be replaced.")]
         [Input("genericStart", "Start symbol used for the beginning of the generic parameters, if any. Usually, '<'.")]
         [Input("genericSeparator", "Symbol used to separate the generic parameters. Usually, ','.")]
         [Input("genericEnd", "Start symbol used for the end of the generic parameters, if any. Usually, '>'.")]
@@ -227,6 +229,29 @@ public static string ToText(this Enum item, bool includePath = false)
             }
         }
 
+        /***************************************************/
+
+        [Description("Get a string representation of a BHoM event.")]
+        [Input("bhomEvent", "The BHoM event to convert to text.")]
+        [Input("includePath", "If true, the stack trace for the event will be included.")]
+        [Output("Text representation.")]
+        public static string ToText(this Event bhomEvent, bool includePath = true)
+        {
+            if(bhomEvent == null)
+                return "null";
+
+            string result = "";
+            result += $"Type: {bhomEvent.Type.ToString()}\n";
+            result += $"Message: {bhomEvent.Message}\n";
+
+            if(includePath)
+                result += $"Stack Trace: {bhomEvent.StackTrace}\n";
+
+            result += $"UTC Time: {bhomEvent.UtcTime.ToString("HH:mm:ss dd/MM/yyyy")}\n";
+
+            return result;
+        }
+
         /***************************************************/
         /**** Fallback Methods                          ****/
         /***************************************************/
@@ -244,9 +269,4 @@ private static string ToText(object item, bool includePath = false)
 
         /***************************************************/
     }
-}
-
-
-
-
-
+}

BHoM_Engine/Query/DebugLog.cs

@@ -45,12 +45,36 @@ internal static Log DebugLog()
             }
         }
 
+        /***************************************************/
+
+        internal static Log SuppressedLog()
+        {
+            lock(Global.DebugLogLock)
+            {
+                if (m_SuppressedLog == null)
+                    m_SuppressedLog = new Log();
+
+                return m_SuppressedLog;
+            }
+        }
+
+        /***************************************************/
+
+        internal static void ResetSuppressedLog()
+        {
+            lock(Global.DebugLogLock)
+            {
+                m_SuppressedLog = new Log();
+            }
+        }
+
 
         /***************************************************/
         /**** Private Fields                            ****/
         /***************************************************/
 
         private static Log m_DebugLog = new Log();
+        private static Log m_SuppressedLog = new Log(); //If someone has switched off the log for any reason, keep a record of their events in this log instead - this way they're not completely removed and could be accessed if they switched it off by accident
 
         /***************************************************/
     }

BHoM_Engine/Query/Events.cs

@@ -61,12 +61,37 @@ public static List<Event> CurrentEvents()
             }
         }
 
+        /***************************************************/
+
+        [Description("Gets the events from the BHoM event log that have occurred on or since the given date/time.")]
+        [Input("utcDateTime", "A date/time in the UTC timezone. Only events recorded ON (to the second) or AFTER this date/time will be returned.")]
+        [Output("events", "Events from the BHoM event log raised since the given date/time.")]
+        public static List<Event> EventsSince(DateTime utcDateTime)
+        {
+            lock (Global.DebugLogLock)
+            {
+                Log log = Query.DebugLog();
+                return log.AllEvents.Where(x => x.UtcTime >= utcDateTime).ToList();
+            }
+        }
 
         /***************************************************/
-    }
-}
 
+        [Description("Gets the events from the BHoM event log that have occurred since the last time you asked to view the event logs. On the first time of asking, this will be all events which have occurred. Each time you run this component, the bookmark will be updated to reflect the current UTC Date/Time.")]
+        [Output("events", "Events from the BHoM event log raised since the last time you queried the event log via the bookmark method.")]
+        public static List<Event> EventsSinceBookmark()
+        {
+            List<Event> events = EventsSince(m_LastBookmark);
 
+            m_LastBookmark = DateTime.UtcNow; //Update the bookmark to now
 
+            return events;
+        }
 
+        /***************************************************/
+        /*** Private variables                         *****/
+        /***************************************************/
 
+        private static DateTime m_LastBookmark = DateTime.UtcNow; //Default to the current UTC time on load
+    }
+}