From 43f4c95ec02b8e8cf1d5de28202a43c9e3482d2b Mon Sep 17 00:00:00 2001
From: samiwelthomasHO <113512609+samiwelthomasHO@users.noreply.github.com>
Date: Fri, 16 Sep 2022 15:54:32 +0100
Subject: [PATCH 1/2] Add debug utility function (#225)

* Add debug utility

* Add some documentation into contributing.md
---
 contributing.md                             | 31 +++++++++++++++++++++
 monitoring-as-code/src/util/debug.libsonnet | 10 +++++++
 2 files changed, 41 insertions(+)
 create mode 100644 monitoring-as-code/src/util/debug.libsonnet

diff --git a/contributing.md b/contributing.md
index 701b3536..f4f4f5f4 100644
--- a/contributing.md
+++ b/contributing.md
@@ -469,6 +469,37 @@ To edit the payload just change the template, if you think there is anything mis
 config or SLI specs that you need for the payload then raise the issue with us, since that would
 be a breaking change.
 
+# Debugging
+
+While developing the jsonnet code it can be helpful to write out a trace to inspect the value of
+objects along the way.
+
+We have provided a convenience utility function `debug` that will write the TRACE output using the
+`std.trace` function from the standard library but also returns the traced object so that the
+debug can be added in place.
+
+It is important to bare in mind that the `debug` function will only be run if the expression is evaluated
+due to the lazy-loading nature of jsonnet.
+
+Example usage:
+
+This **will** work:
+
+```
+{
+  local test = [1,2,3];
+  value: debug(test),
+}
+```
+
+This **will not** work since test is never used/evaluated.
+
+```
+{
+  local test = debug({});
+}
+```
+
 # Testing
 
 TBC
diff --git a/monitoring-as-code/src/util/debug.libsonnet b/monitoring-as-code/src/util/debug.libsonnet
new file mode 100644
index 00000000..652c2e7b
--- /dev/null
+++ b/monitoring-as-code/src/util/debug.libsonnet
@@ -0,0 +1,10 @@
+// A function that writes a TRACE output of the object and returns the object itself.
+// @param obj Any serialisable object
+// @returns obj the passed in object
+local debug(obj) = (
+  std.trace(std.toString(obj), obj)
+);
+
+{
+  debug(obj): debug(obj)
+}
\ No newline at end of file

From 305f503473a7a71e2dbd555ebb2d42e44bb373a5 Mon Sep 17 00:00:00 2001
From: Samiwel Thomas <samiwel.thomas@digital.homeoffice.gov.uk>
Date: Fri, 23 Sep 2022 11:27:18 +0100
Subject: [PATCH 2/2] Fix formatting issue.

---
 monitoring-as-code/src/util/debug.libsonnet | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/monitoring-as-code/src/util/debug.libsonnet b/monitoring-as-code/src/util/debug.libsonnet
index 652c2e7b..a5ea7870 100644
--- a/monitoring-as-code/src/util/debug.libsonnet
+++ b/monitoring-as-code/src/util/debug.libsonnet
@@ -6,5 +6,5 @@ local debug(obj) = (
 );
 
 {
-  debug(obj): debug(obj)
-}
\ No newline at end of file
+  debug(obj): debug(obj),
+}