CT-1718: Add Note and Formatting event types (#6691)

* CT-1718: Add Note and Formatting event types

* CT-1718: Add changelog entry

.changes/unreleased/Under the Hood-20230120-172254.yaml

@@ -0,0 +1,7 @@
+kind: Under the Hood
+body: Replaced the EmptyLine event with a more general Formatting event, and added
+  a Note event.
+time: 2023-01-20T17:22:54.45828-05:00
+custom:
+  Author: peterallenwebb
+  Issue: "6481"

core/dbt/events/functions.py

@@ -3,7 +3,7 @@
 from dbt.events.base_types import BaseEvent, Cache, EventLevel, NoFile, NoStdOut, EventMsg
 from dbt.events.eventmgr import EventManager, LoggerConfig, LineFormat, NoFilter
 from dbt.events.helpers import env_secrets, scrub_secrets
-from dbt.events.types import EmptyLine
+from dbt.events.types import Formatting
 import dbt.flags as flags
 from dbt.logger import GLOBAL_LOGGER, make_log_dir_if_missing
 from functools import partial
@@ -65,7 +65,7 @@ def _stdout_filter(
         and (not isinstance(msg.data, Cache) or log_cache_events)
         and (EventLevel(msg.info.level) != EventLevel.DEBUG or debug_mode)
         and (EventLevel(msg.info.level) == EventLevel.ERROR or not quiet_mode)
-        and not (flags.LOG_FORMAT == "json" and type(msg.data) == EmptyLine)
+        and not (flags.LOG_FORMAT == "json" and type(msg.data) == Formatting)
     )
 
 
@@ -85,7 +85,7 @@ def _logfile_filter(log_cache_events: bool, msg: EventMsg) -> bool:
     return (
         not isinstance(msg.data, NoFile)
         and not (isinstance(msg.data, Cache) and not log_cache_events)
-        and not (flags.LOG_FORMAT == "json" and type(msg.data) == EmptyLine)
+        and not (flags.LOG_FORMAT == "json" and type(msg.data) == Formatting)
     )
 
 

core/dbt/events/types.proto

@@ -1473,15 +1473,7 @@ message SeedHeaderMsg {
     SeedHeader data = 2;
 }
 
-// Q005
-message SeedHeaderSeparator {
-    int32 len_header = 1;
-}
-
-message SeedHeaderSeparatorMsg {
-    EventInfo info = 1;
-    SeedHeaderSeparator data = 2;
-}
+// Skipped Q005
 
 // Q006
 message SQLRunnerException {
@@ -2004,12 +1996,13 @@ message OpenCommandMsg {
 }
 
 // Z017
-message EmptyLine {
+message Formatting {
+    string msg = 1;
 }
 
-message EmptyLineMsg {
+message FormattingMsg {
     EventInfo info = 1;
-    EmptyLine data = 2;
+    Formatting data = 2;
 }
 
 // Z018
@@ -2288,6 +2281,15 @@ message ListCmdOutMsg {
     ListCmdOut data = 2;
 }
 
+// Z050
+message Note {
+    string msg = 1;
+}
+
+message NoteMsg {
+    EventInfo info = 1;
+    Note data = 2;
+}
 
 // T - Integration tests
 

core/dbt/events/types.py

@@ -1498,15 +1498,6 @@ def message(self) -> str:
         return self.header
 
 
-@dataclass
-class SeedHeaderSeparator(InfoLevel, pt.SeedHeaderSeparator):
-    def code(self):
-        return "Q005"
-
-    def message(self) -> str:
-        return "-" * self.len_header
-
-
 @dataclass
 class SQLRunnerException(DebugLevel, pt.SQLRunnerException):  # noqa
     def code(self):
@@ -2084,13 +2075,18 @@ def message(self) -> str:
         return msg
 
 
+# We use events to create console output, but also think of them as a sequence of important and
+# meaningful occurrences to be used for debugging and monitoring. The Formatting event helps eases
+# the tension between these two goals by allowing empty lines, heading separators, and other
+# formatting to be written to the console, while they can be ignored for other purposes. For
+# general information that isn't simple formatting, the Note event should be used instead.
 @dataclass
-class EmptyLine(InfoLevel, pt.EmptyLine):
+class Formatting(InfoLevel, pt.Formatting):
     def code(self):
         return "Z017"
 
     def message(self) -> str:
-        return ""
+        return self.msg
 
 
 @dataclass
@@ -2372,3 +2368,14 @@ def code(self):
 
     def message(self) -> str:
         return self.msg
+
+
+# The Note event provides a way to log messages which aren't likely to be useful as more structured events.
+# For conslole formatting text like empty lines and separator bars, use the Formatting event instead.
+@dataclass
+class Note(InfoLevel, pt.Note):
+    def code(self):
+        return "Z050"
+
+    def message(self) -> str:
+        return self.msg

core/dbt/task/deps.py

@@ -20,7 +20,7 @@
     DepsInstallInfo,
     DepsListSubdirectory,
     DepsNotifyUpdatesAvailable,
-    EmptyLine,
+    Formatting,
 )
 from dbt.clients import system
 
@@ -88,7 +88,7 @@ def run(self) -> None:
                     package_name=package_name, source_type=source_type, version=version
                 )
             if packages_to_upgrade:
-                fire_event(EmptyLine())
+                fire_event(Formatting(""))
                 fire_event(DepsNotifyUpdatesAvailable(packages=ListOfStrings(packages_to_upgrade)))
 
     @classmethod

core/dbt/task/printer.py

@@ -5,7 +5,7 @@
 )
 from dbt.events.functions import fire_event
 from dbt.events.types import (
-    EmptyLine,
+    Formatting,
     RunResultWarning,
     RunResultWarningMessage,
     RunResultFailure,
@@ -72,14 +72,14 @@ def print_run_status_line(results) -> None:
         stats["total"] += 1
 
     with TextOnly():
-        fire_event(EmptyLine())
+        fire_event(Formatting(""))
     fire_event(StatsLine(stats=stats))
 
 
 def print_run_result_error(result, newline: bool = True, is_warning: bool = False) -> None:
     if newline:
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
 
     if result.status == NodeStatus.Fail or (is_warning and result.status == NodeStatus.Warn):
         if is_warning:
@@ -109,12 +109,12 @@ def print_run_result_error(result, newline: bool = True, is_warning: bool = Fals
 
         if result.node.build_path is not None:
             with TextOnly():
-                fire_event(EmptyLine())
+                fire_event(Formatting(""))
             fire_event(SQLCompiledPath(path=result.node.compiled_path))
 
         if result.node.should_store_failures:
             with TextOnly():
-                fire_event(EmptyLine())
+                fire_event(Formatting(""))
             fire_event(CheckNodeTestFailure(relation_name=result.node.relation_name))
 
     elif result.message is not None:
@@ -143,7 +143,7 @@ def print_run_end_messages(results, keyboard_interrupt: bool = False) -> None:
 
     with DbtStatusMessage(), InvocationProcessor():
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
         fire_event(
             EndOfRunSummary(
                 num_errors=len(errors),

core/dbt/task/run.py

@@ -30,7 +30,7 @@
 from dbt.events.functions import fire_event, get_invocation_id
 from dbt.events.types import (
     DatabaseErrorRunningHook,
-    EmptyLine,
+    Formatting,
     HooksRunning,
     FinishedRunningStats,
     LogModelResult,
@@ -335,7 +335,7 @@ def run_hooks(self, adapter, hook_type: RunHookType, extra_context):
         num_hooks = len(ordered_hooks)
 
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
         fire_event(HooksRunning(num_hooks=num_hooks, hook_type=hook_type))
 
         startctx = TimestampNamed("node_started_at")
@@ -388,7 +388,7 @@ def run_hooks(self, adapter, hook_type: RunHookType, extra_context):
         self._total_executed += len(ordered_hooks)
 
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
 
     def safe_run_hooks(
         self, adapter, hook_type: RunHookType, extra_context: Dict[str, Any]
@@ -419,7 +419,7 @@ def print_results_line(self, results, execution_time):
             execution = utils.humanize_execution_time(execution_time=execution_time)
 
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
         fire_event(
             FinishedRunningStats(
                 stat_line=stat_line, execution=execution, execution_time=execution_time

core/dbt/task/runnable.py

@@ -28,7 +28,7 @@
 )
 from dbt.events.functions import fire_event, warn_or_error
 from dbt.events.types import (
-    EmptyLine,
+    Formatting,
     LogCancelLine,
     DefaultSelector,
     NodeStart,
@@ -377,7 +377,7 @@ def execute_nodes(self):
                 )
             )
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
 
         pool = ThreadPool(num_threads)
         try:
@@ -458,7 +458,7 @@ def run(self):
 
         if len(self._flattened_nodes) == 0:
             with TextOnly():
-                fire_event(EmptyLine())
+                fire_event(Formatting(""))
             warn_or_error(NothingToDo())
             result = self.get_result(
                 results=[],
@@ -467,7 +467,7 @@ def run(self):
             )
         else:
             with TextOnly():
-                fire_event(EmptyLine())
+                fire_event(Formatting(""))
             selected_uids = frozenset(n.unique_id for n in self._flattened_nodes)
             result = self.execute_with_hooks(selected_uids)
 

core/dbt/task/seed.py

@@ -12,8 +12,7 @@
 from dbt.events.functions import fire_event
 from dbt.events.types import (
     SeedHeader,
-    SeedHeaderSeparator,
-    EmptyLine,
+    Formatting,
     LogSeedResult,
     LogStartLine,
 )
@@ -99,13 +98,13 @@ def show_table(self, result):
 
         header = "Random sample of table: {}.{}".format(schema, alias)
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
         fire_event(SeedHeader(header=header))
-        fire_event(SeedHeaderSeparator(len_header=len(header)))
+        fire_event(Formatting("-" * len(header)))
 
         rand_table.print_table(max_rows=10, max_columns=None)
         with TextOnly():
-            fire_event(EmptyLine())
+            fire_event(Formatting(""))
 
     def show_tables(self, results):
         for result in results:

core/dbt/task/serve.py

@@ -6,7 +6,12 @@
 from http.server import SimpleHTTPRequestHandler
 from socketserver import TCPServer
 from dbt.events.functions import fire_event
-from dbt.events.types import ServingDocsPort, ServingDocsAccessInfo, ServingDocsExitInfo, EmptyLine
+from dbt.events.types import (
+    ServingDocsPort,
+    ServingDocsAccessInfo,
+    ServingDocsExitInfo,
+    Formatting,
+)
 
 from dbt.task.base import ConfiguredTask
 
@@ -22,8 +27,8 @@ def run(self):
 
         fire_event(ServingDocsPort(address=address, port=port))
         fire_event(ServingDocsAccessInfo(port=port))
-        fire_event(EmptyLine())
-        fire_event(EmptyLine())
+        fire_event(Formatting(""))
+        fire_event(Formatting(""))
         fire_event(ServingDocsExitInfo())
 
         # mypy doesn't think SimpleHTTPRequestHandler is ok here, but it is