[etw] Add String() functions, JSON field option (#285)

Add `String()` functions to `etw.Level` and `etw.Opcode` types.

Add `etw.JSONStringField()`, which denotes a string field containing
JSON data.

Fix doc comment casing.

Signed-off-by: Hamza El-Saawy <hamzaelsaawy@microsoft.com>

pkg/etw/eventdescriptor.go

@@ -1,7 +1,7 @@
-//go:build windows
-
 package etw
 
+import "fmt"
+
 // Channel represents the ETW logging channel that is used. It can be used by
 // event consumers to give an event special treatment.
 type Channel uint8
@@ -19,7 +19,11 @@ const (
 // will always be collected.
 type Level uint8
 
+var _ fmt.Stringer = Level(0)
+
 // Predefined ETW log levels from winmeta.xml in the Windows SDK.
+//
+//go:generate go run golang.org/x/tools/cmd/stringer -type=Level -trimprefix=Level
 const (
 	LevelAlways Level = iota
 	LevelCritical
@@ -32,7 +36,11 @@ const (
 // Opcode represents the operation that the event indicates is being performed.
 type Opcode uint8
 
+var _ fmt.Stringer = Opcode(0)
+
 // Predefined ETW opcodes from winmeta.xml in the Windows SDK.
+//
+//go:generate go run golang.org/x/tools/cmd/stringer -type=Opcode -trimprefix=Opcode
 const (
 	// OpcodeInfo indicates an informational event.
 	OpcodeInfo Opcode = iota
@@ -46,7 +54,7 @@ const (
 	OpcodeDCStop
 )
 
-// EventDescriptor represents various metadata for an ETW event.
+// eventDescriptor represents various metadata for an ETW event.
 type eventDescriptor struct {
 	id      uint16
 	version uint8
@@ -57,7 +65,7 @@ type eventDescriptor struct {
 	keyword uint64
 }
 
-// NewEventDescriptor returns an EventDescriptor initialized for use with
+// newEventDescriptor returns an EventDescriptor initialized for use with
 // TraceLogging.
 func newEventDescriptor() *eventDescriptor {
 	// Standard TraceLogging events default to the TraceLogging channel, and
@@ -68,7 +76,7 @@ func newEventDescriptor() *eventDescriptor {
 	}
 }
 
-// Identity returns the identity of the event. If the identity is not 0, it
+// identity returns the identity of the event. If the identity is not 0, it
 // should uniquely identify the other event metadata (contained in
 // EventDescriptor, and field metadata). Only the lower 24 bits of this value
 // are relevant.
@@ -78,7 +86,7 @@ func (ed *eventDescriptor) identity() uint32 {
 	return (uint32(ed.version) << 16) | uint32(ed.id)
 }
 
-// SetIdentity sets the identity of the event. If the identity is not 0, it
+// setIdentity sets the identity of the event. If the identity is not 0, it
 // should uniquely identify the other event metadata (contained in
 // EventDescriptor, and field metadata). Only the lower 24 bits of this value
 // are relevant.

pkg/etw/fieldopt.go

@@ -56,6 +56,14 @@ func StringField(name string, value string) FieldOpt {
 	}
 }
 
+// JSONStringField adds a JSON-encoded string field to the event.
+func JSONStringField(name string, value string) FieldOpt {
+	return func(em *eventMetadata, ed *eventData) {
+		em.writeField(name, inTypeANSIString, outTypeJSON, 0)
+		ed.writeString(value)
+	}
+}
+
 // StringArray adds an array of string to the event.
 func StringArray(name string, values []string) FieldOpt {
 	return func(em *eventMetadata, ed *eventData) {

pkg/etw/level_string.go

@@ -0,0 +1,28 @@
+// Code generated by "stringer -type=Level -trimprefix=Level"; DO NOT EDIT.
+
+package etw
+
+import "strconv"
+
+func _() {
+	// An "invalid array index" compiler error signifies that the constant values have changed.
+	// Re-run the stringer command to generate them again.
+	var x [1]struct{}
+	_ = x[LevelAlways-0]
+	_ = x[LevelCritical-1]
+	_ = x[LevelError-2]
+	_ = x[LevelWarning-3]
+	_ = x[LevelInfo-4]
+	_ = x[LevelVerbose-5]
+}
+
+const _Level_name = "AlwaysCriticalErrorWarningInfoVerbose"
+
+var _Level_index = [...]uint8{0, 6, 14, 19, 26, 30, 37}
+
+func (i Level) String() string {
+	if i >= Level(len(_Level_index)-1) {
+		return "Level(" + strconv.FormatInt(int64(i), 10) + ")"
+	}
+	return _Level_name[_Level_index[i]:_Level_index[i+1]]
+}

pkg/etw/opcode_string.go

@@ -0,0 +1,27 @@
+// Code generated by "stringer -type=Opcode -trimprefix=Opcode"; DO NOT EDIT.
+
+package etw
+
+import "strconv"
+
+func _() {
+	// An "invalid array index" compiler error signifies that the constant values have changed.
+	// Re-run the stringer command to generate them again.
+	var x [1]struct{}
+	_ = x[OpcodeInfo-0]
+	_ = x[OpcodeStart-1]
+	_ = x[OpcodeStop-2]
+	_ = x[OpcodeDCStart-3]
+	_ = x[OpcodeDCStop-4]
+}
+
+const _Opcode_name = "InfoStartStopDCStartDCStop"
+
+var _Opcode_index = [...]uint8{0, 4, 9, 13, 20, 26}
+
+func (i Opcode) String() string {
+	if i >= Opcode(len(_Opcode_index)-1) {
+		return "Opcode(" + strconv.FormatInt(int64(i), 10) + ")"
+	}
+	return _Opcode_name[_Opcode_index[i]:_Opcode_index[i+1]]
+}