Minor changes to note support

* Check if node is non-nil to prevent panic
* Omit empty message field from API response
* Use native string type for message fields

Author: tsandall

ast/builtins.go

@@ -133,7 +133,7 @@ var DefaultBuiltins = [...]*Builtin{
 	// HTTP
 	HTTPSend,
 
-	//Trace
+	// Tracing
 	Trace,
 }
 
@@ -980,7 +980,7 @@ var HTTPSend = &Builtin{
  * Trace
  */
 
-// Trace built-in for supporting debug messages
+// Trace prints a note that is included in the query explanation.
 var Trace = &Builtin{
 	Name: "trace",
 	Decl: types.NewFunction(

docs/book/language-reference.md

@@ -144,10 +144,10 @@ evaluation query will always return the same value.
 | ------- |--------|-------------|
 | <span class="opa-keep-it-together">``http.send(request, output)``</span> | 1 | ``http.send`` executes a HTTP request and returns the response.``request`` is an object containing keys ``method``, ``url`` and  optionally ``body``. For example, ``http.send({"method": "get", "url": "http://www.openpolicyagent.org/"}, output)``. ``output`` is an object containing keys ``status``, ``status_code`` and ``body`` which represent the HTTP status, status code and response body respectively. Sample output, ``{"status": "200 OK", "status_code": 200, "body": null``}|
 
-### <a name="trace"/>Debug Trace
+### <a name="debugging"/>Debugging
 | Built-in | Inputs | Description |
 | ------- |--------|-------------|
-| <span class="opa-keep-it-together">``trace("debug message")``</span> | 1 | ``trace`` outputs the debug message in the ``Note`` if tracing is enabled. For example, ``trace("Hello There!")`` includes ``Note "Hello There!"`` in the trace. To print variable values, include sprintf in the trace message. For example, ``person = "Bob" trace(sprintf("Hello There! %v", [person]))`` will return ``Note "Hello There! Bob"``|
+| <span class="opa-keep-it-together">``trace(string)``</span> | 1 | ``trace`` outputs the debug message ``string`` as a ``Note`` event in the query explanation. For example, ``trace("Hello There!")`` includes ``Note "Hello There!"`` in the query explanation. To print variables, use sprintf. For example, ``person = "Bob"; trace(sprintf("Hello There! %v", [person]))`` will emit ``Note "Hello There! Bob"``. |
 
 ## <a name="reserved-names"></a> Reserved Names
 

server/types/types.go

@@ -242,11 +242,13 @@ func newRawTraceV1(trace []*topdown.Event) (TraceV1, error) {
 			Op:       strings.ToLower(string(trace[i].Op)),
 			QueryID:  trace[i].QueryID,
 			ParentID: trace[i].ParentID,
-			Type:     ast.TypeName(trace[i].Node),
-			Node:     trace[i].Node,
 			Locals:   NewBindingsV1(trace[i].Locals),
 			Message:  trace[i].Message,
 		}
+		if trace[i].Node != nil {
+			result[i].Type = ast.TypeName(trace[i].Node)
+			result[i].Node = trace[i].Node
+		}
 	}
 
 	b, err := json.Marshal(result)
@@ -276,7 +278,7 @@ type TraceEventV1 struct {
 	Type     string      `json:"type"`
 	Node     interface{} `json:"node"`
 	Locals   BindingsV1  `json:"locals"`
-	Message  ast.String  `json:"message"`
+	Message  string      `json:"message,omitempty"`
 }
 
 // UnmarshalJSON deserializes a TraceEventV1 object. The Node field is

topdown/trace.go

@@ -36,7 +36,7 @@ const (
 	// FailOp is emitted when an expression evaluates to false.
 	FailOp Op = "Fail"
 
-	//NoteOp is emitted when trace is requested
+	// NoteOp is emitted when an expression invokes a tracing built-in function.
 	NoteOp Op = "Note"
 )
 
@@ -47,7 +47,7 @@ type Event struct {
 	QueryID  uint64        // Identifies the query this event belongs to.
 	ParentID uint64        // Identifies the parent query this event belongs to.
 	Locals   *ast.ValueMap // Contains local variable bindings from the query context.
-	Message  ast.String
+	Message  string        // Contains message for Note events.
 }
 
 // HasRule returns true if the Event contains an ast.Rule.
@@ -149,7 +149,7 @@ func PrettyTrace(w io.Writer, trace []*Event) {
 func formatEvent(event *Event, depth int) string {
 	padding := formatEventPadding(event, depth)
 	if event.Op == NoteOp {
-		return fmt.Sprintf("%v%v %v", padding, event.Op, event.Message)
+		return fmt.Sprintf("%v%v %q", padding, event.Op, event.Message)
 	}
 	return fmt.Sprintf("%v%v %v", padding, event.Op, event.Node)
 }
@@ -205,7 +205,7 @@ func builtinTrace(bctx BuiltinContext, args []*ast.Term, iter func(*ast.Term) er
 		Op:       NoteOp,
 		QueryID:  bctx.QueryID,
 		ParentID: bctx.ParentID,
-		Message:  str,
+		Message:  string(str),
 	}
 	bctx.Tracer.Trace(evt)