Add and update comments in ui/metrics/event.go
The event.go code was refactored to follow the best practices
of golang code style.
Bug: b/172918681
Test: go test ./ui/metrics
Change-Id: Ic57d7cd576a9b146530ae37f03f4f5679d6cffef
diff --git a/ui/metrics/event.go b/ui/metrics/event.go
index 6becfd1..87c1b84 100644
--- a/ui/metrics/event.go
+++ b/ui/metrics/event.go
@@ -14,6 +14,17 @@
package metrics
+// This file contains the functionality to represent a build event in respect
+// to the metric system. A build event corresponds to a block of scoped code
+// that contains a "Begin()" and immediately followed by "defer End()" trace.
+// When defined, the duration of the scoped code is measure along with other
+// performance measurements such as memory.
+//
+// As explained in the metrics package, the metrics system is a stacked based
+// system since the collected metrics is considered to be topline metrics.
+// The steps of the build system in the UI layer is sequential. Hence, the
+// functionality defined below follows the stack data structure operations.
+
import (
"os"
"syscall"
@@ -21,54 +32,97 @@
"android/soong/ui/metrics/metrics_proto"
"android/soong/ui/tracer"
+
"github.com/golang/protobuf/proto"
)
-// for testing purpose only
-var _now = now
-
-type event struct {
- desc string
- name string
-
- // the time that the event started to occur.
- start time.Time
-
- // The list of process resource information that was executed
- procResInfo []*soong_metrics_proto.ProcessResourceInfo
-}
-
-type EventTracer interface {
- Begin(name, desc string, thread tracer.Thread)
- End(thread tracer.Thread) soong_metrics_proto.PerfInfo
- AddProcResInfo(string, *os.ProcessState)
-}
-
-type eventTracerImpl struct {
- activeEvents []event
-}
-
-var _ EventTracer = &eventTracerImpl{}
-
-func now() time.Time {
+// _now wraps the time.Now() function. _now is declared for unit testing purpose.
+var _now = func() time.Time {
return time.Now()
}
-// AddProcResInfo adds information on an executed process such as max resident set memory
-// and the number of voluntary context switches.
-func (t *eventTracerImpl) AddProcResInfo(name string, state *os.ProcessState) {
- if len(t.activeEvents) < 1 {
+// event holds the performance metrics data of a single build event.
+type event struct {
+ // The event name (mostly used for grouping a set of events)
+ name string
+
+ // The description of the event (used to uniquely identify an event
+ // for metrics analysis).
+ desc string
+
+ // The time that the event started to occur.
+ start time.Time
+
+ // The list of process resource information that was executed.
+ procResInfo []*soong_metrics_proto.ProcessResourceInfo
+}
+
+// newEvent returns an event with start populated with the now time.
+func newEvent(name, desc string) *event {
+ return &event{
+ name: name,
+ desc: desc,
+ start: _now(),
+ }
+}
+
+func (e event) perfInfo() soong_metrics_proto.PerfInfo {
+ realTime := uint64(_now().Sub(e.start).Nanoseconds())
+ return soong_metrics_proto.PerfInfo{
+ Desc: proto.String(e.desc),
+ Name: proto.String(e.name),
+ StartTime: proto.Uint64(uint64(e.start.UnixNano())),
+ RealTime: proto.Uint64(realTime),
+ ProcessesResourceInfo: e.procResInfo,
+ }
+}
+
+// EventTracer is an array of events that provides functionality to trace a
+// block of code on time and performance. The End call expects the Begin is
+// invoked, otherwise panic is raised.
+type EventTracer []*event
+
+// empty returns true if there are no pending events.
+func (t *EventTracer) empty() bool {
+ return len(*t) == 0
+}
+
+// lastIndex returns the index of the last element of events.
+func (t *EventTracer) lastIndex() int {
+ return len(*t) - 1
+}
+
+// peek returns the active build event.
+func (t *EventTracer) peek() *event {
+ return (*t)[t.lastIndex()]
+}
+
+// push adds the active build event in the stack.
+func (t *EventTracer) push(e *event) {
+ *t = append(*t, e)
+}
+
+// pop removes the active event from the stack since the event has completed.
+// A panic is raised if there are no pending events.
+func (t *EventTracer) pop() *event {
+ if t.empty() {
+ panic("Internal error: No pending events")
+ }
+ e := (*t)[t.lastIndex()]
+ *t = (*t)[:t.lastIndex()]
+ return e
+}
+
+// AddProcResInfo adds information on an executed process such as max resident
+// set memory and the number of voluntary context switches.
+func (t *EventTracer) AddProcResInfo(name string, state *os.ProcessState) {
+ if t.empty() {
return
}
rusage := state.SysUsage().(*syscall.Rusage)
- // The implementation of the metrics system is a stacked based system. The steps of the
- // build system in the UI layer is sequential so the Begin function is invoked when a
- // function (or scoped code) is invoked. That is translated to a new event which is added
- // at the end of the activeEvents array. When the invoking function is completed, End is
- // invoked which is a pop operation from activeEvents.
- curEvent := &t.activeEvents[len(t.activeEvents)-1]
- curEvent.procResInfo = append(curEvent.procResInfo, &soong_metrics_proto.ProcessResourceInfo{
+ e := t.peek()
+ e.procResInfo = append(e.procResInfo, &soong_metrics_proto.ProcessResourceInfo{
Name: proto.String(name),
UserTimeMicros: proto.Uint64(uint64(rusage.Utime.Usec)),
SystemTimeMicros: proto.Uint64(uint64(rusage.Stime.Usec)),
@@ -82,23 +136,13 @@
})
}
-func (t *eventTracerImpl) Begin(name, desc string, _ tracer.Thread) {
- t.activeEvents = append(t.activeEvents, event{name: name, desc: desc, start: _now()})
+// Begin starts tracing the event.
+func (t *EventTracer) Begin(name, desc string, _ tracer.Thread) {
+ t.push(newEvent(name, desc))
}
-func (t *eventTracerImpl) End(tracer.Thread) soong_metrics_proto.PerfInfo {
- if len(t.activeEvents) < 1 {
- panic("Internal error: No pending events for endAt to end!")
- }
- lastEvent := t.activeEvents[len(t.activeEvents)-1]
- t.activeEvents = t.activeEvents[:len(t.activeEvents)-1]
- realTime := uint64(_now().Sub(lastEvent.start).Nanoseconds())
-
- return soong_metrics_proto.PerfInfo{
- Desc: proto.String(lastEvent.desc),
- Name: proto.String(lastEvent.name),
- StartTime: proto.Uint64(uint64(lastEvent.start.UnixNano())),
- RealTime: proto.Uint64(realTime),
- ProcessesResourceInfo: lastEvent.procResInfo,
- }
+// End performs post calculations such as duration of the event, aggregates
+// the collected performance information into PerfInfo protobuf message.
+func (t *EventTracer) End(tracer.Thread) soong_metrics_proto.PerfInfo {
+ return t.pop().perfInfo()
}
diff --git a/ui/metrics/event_test.go b/ui/metrics/event_test.go
index 6fc0b50..043450b 100644
--- a/ui/metrics/event_test.go
+++ b/ui/metrics/event_test.go
@@ -28,14 +28,14 @@
_now = func() time.Time { return startTime.Add(dur) }
defer func() { _now = initialNow }()
- eventTracer := &eventTracerImpl{}
- eventTracer.activeEvents = append(eventTracer.activeEvents, event{
+ et := &EventTracer{}
+ et.push(&event{
desc: "test",
name: "test",
start: startTime,
})
- perf := eventTracer.End(tracer.Thread(0))
+ perf := et.End(tracer.Thread(0))
if perf.GetRealTime() != uint64(dur.Nanoseconds()) {
t.Errorf("got %d, want %d nanoseconds for event duration", perf.GetRealTime(), dur.Nanoseconds())
}
diff --git a/ui/metrics/metrics.go b/ui/metrics/metrics.go
index 7031042..2a09461 100644
--- a/ui/metrics/metrics.go
+++ b/ui/metrics/metrics.go
@@ -39,13 +39,13 @@
type Metrics struct {
metrics soong_metrics_proto.MetricsBase
- EventTracer EventTracer
+ EventTracer *EventTracer
}
func New() (metrics *Metrics) {
m := &Metrics{
metrics: soong_metrics_proto.MetricsBase{},
- EventTracer: &eventTracerImpl{},
+ EventTracer: &EventTracer{},
}
return m
}