From fbcafaeb9bc277e6b08dd8e2260276ba176a6d5f Mon Sep 17 00:00:00 2001
From: Curtis Stallings <curtis.stallings@rockwellautomation.com>
Date: Sat, 18 Feb 2023 11:27:34 -0600
Subject: [PATCH] tabular tracing doc

---
 docs/tabular_tracing.md      |  1 +
 mkdocs.yml                   |  1 +
 pytabular/tabular_tracing.py | 38 ++++++++++++++++++++++++++++--------
 3 files changed, 32 insertions(+), 8 deletions(-)
 create mode 100644 docs/tabular_tracing.md

diff --git a/docs/tabular_tracing.md b/docs/tabular_tracing.md
new file mode 100644
index 0000000..c266a36
--- /dev/null
+++ b/docs/tabular_tracing.md
@@ -0,0 +1 @@
+:::pytabular.tabular_tracing
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 2be1964..d178d05 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -23,6 +23,7 @@ nav:
       - best_practice_analyzer: best_practice_analyzer.md
       - pbi_helper: pbi_helper.md
       - logic_utils: logic_utils.md
+    - Running Traces: tabular_tracing.md
     - Documenting Model: document.md
     - Contributing: CONTRIBUTING.md
 
diff --git a/pytabular/tabular_tracing.py b/pytabular/tabular_tracing.py
index fe3a278..130f2b9 100644
--- a/pytabular/tabular_tracing.py
+++ b/pytabular/tabular_tracing.py
@@ -2,6 +2,28 @@
 
 It also includes some pre built traces to make life easier.
 Feel free to build your own.
+
+Example:
+    ```python title="Monitor Queries"
+    import pytabular as p
+    import logging as l
+    model = p.Tabular(CONNECTION_STR)
+    query_trace = p.QueryMonitor(model)
+    query_trace.start() # (1)
+
+    ###
+
+    p.logger.setLevel(l.DEBUG) # (2)
+
+    ###
+
+    query_trace.stop()
+    query_trace.drop() # (3)
+    ```
+
+    1. You will now start to see query traces on your model get outputed to your console.
+    2. If you want to see the FULL query then set logging to DEBUG.
+    3. You can drop on your own, or will get dropped on script exit.
 """
 import logging
 import random
@@ -118,8 +140,8 @@ def update(self) -> None:
         """Runs on init. Syncs with Server.
 
         Returns:
-                None: Returns None.
-                    Unless unsuccessful then it will return the error from Server.
+            None: Returns None.
+                Unless unsuccessful then it will return the error from Server.
         """
         logger.info(f"Updating {self.Name} in {self.tabular_class.Server.Name}")
         if self.tabular_class.Server.Connected is False:
@@ -131,8 +153,8 @@ def start(self) -> None:
         """Call when you want to start the trace.
 
         Returns:
-                None: Returns None.
-                    Unless unsuccessful then it will return the error from Server.
+            None: Returns None.
+                Unless unsuccessful then it will return the error from Server.
         """
         logger.info(f"Starting {self.Name} in {self.tabular_class.Server.Name}")
         return self.Trace.Start()
@@ -141,8 +163,8 @@ def stop(self) -> None:
         """Call when you want to stop the trace.
 
         Returns:
-                None: Returns None.
-                    Unless unsuccessful then it will return the error from Server.
+            None: Returns None.
+                Unless unsuccessful then it will return the error from Server.
         """
         logger.info(f"Stopping {self.Name} in {self.tabular_class.Server.Name}")
         return self.Trace.Stop()
@@ -151,8 +173,8 @@ def drop(self) -> None:
         """Call when you want to drop the trace.
 
         Returns:
-                None: Returns None. Unless unsuccessful,
-                    then it will return the error from Server.
+            None: Returns None. Unless unsuccessful,
+                then it will return the error from Server.
         """
         logger.info(f"Dropping {self.Name} in {self.tabular_class.Server.Name}")
         atexit.unregister(self.drop)