1// Copyright 2018 Google Inc. All Rights Reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//   http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15package metrics
16
17// This file contains the functionality to represent a build event in respect
18// to the metric system. A build event corresponds to a block of scoped code
19// that contains a "Begin()" and immediately followed by "defer End()" trace.
20// When defined, the duration of the scoped code is measure along with other
21// performance measurements such as memory.
22//
23// As explained in the metrics package, the metrics system is a stacked based
24// system since the collected metrics is considered to be topline metrics.
25// The steps of the build system in the UI layer is sequential. Hence, the
26// functionality defined below follows the stack data structure operations.
27
28import (
29	"os"
30	"syscall"
31	"time"
32
33	"android/soong/ui/metrics/metrics_proto"
34	"android/soong/ui/tracer"
35
36	"github.com/golang/protobuf/proto"
37)
38
39// _now wraps the time.Now() function. _now is declared for unit testing purpose.
40var _now = func() time.Time {
41	return time.Now()
42}
43
44// event holds the performance metrics data of a single build event.
45type event struct {
46	// The event name (mostly used for grouping a set of events)
47	name string
48
49	// The description of the event (used to uniquely identify an event
50	// for metrics analysis).
51	desc string
52
53	// The time that the event started to occur.
54	start time.Time
55
56	// The list of process resource information that was executed.
57	procResInfo []*soong_metrics_proto.ProcessResourceInfo
58}
59
60// newEvent returns an event with start populated with the now time.
61func newEvent(name, desc string) *event {
62	return &event{
63		name:  name,
64		desc:  desc,
65		start: _now(),
66	}
67}
68
69func (e event) perfInfo() soong_metrics_proto.PerfInfo {
70	realTime := uint64(_now().Sub(e.start).Nanoseconds())
71	return soong_metrics_proto.PerfInfo{
72		Desc:                  proto.String(e.desc),
73		Name:                  proto.String(e.name),
74		StartTime:             proto.Uint64(uint64(e.start.UnixNano())),
75		RealTime:              proto.Uint64(realTime),
76		ProcessesResourceInfo: e.procResInfo,
77	}
78}
79
80// EventTracer is an array of events that provides functionality to trace a
81// block of code on time and performance. The End call expects the Begin is
82// invoked, otherwise panic is raised.
83type EventTracer []*event
84
85// empty returns true if there are no pending events.
86func (t *EventTracer) empty() bool {
87	return len(*t) == 0
88}
89
90// lastIndex returns the index of the last element of events.
91func (t *EventTracer) lastIndex() int {
92	return len(*t) - 1
93}
94
95// peek returns the active build event.
96func (t *EventTracer) peek() *event {
97	return (*t)[t.lastIndex()]
98}
99
100// push adds the active build event in the stack.
101func (t *EventTracer) push(e *event) {
102	*t = append(*t, e)
103}
104
105// pop removes the active event from the stack since the event has completed.
106// A panic is raised if there are no pending events.
107func (t *EventTracer) pop() *event {
108	if t.empty() {
109		panic("Internal error: No pending events")
110	}
111	e := (*t)[t.lastIndex()]
112	*t = (*t)[:t.lastIndex()]
113	return e
114}
115
116// AddProcResInfo adds information on an executed process such as max resident
117// set memory and the number of voluntary context switches.
118func (t *EventTracer) AddProcResInfo(name string, state *os.ProcessState) {
119	if t.empty() {
120		return
121	}
122
123	rusage := state.SysUsage().(*syscall.Rusage)
124	e := t.peek()
125	e.procResInfo = append(e.procResInfo, &soong_metrics_proto.ProcessResourceInfo{
126		Name:             proto.String(name),
127		UserTimeMicros:   proto.Uint64(uint64(rusage.Utime.Usec)),
128		SystemTimeMicros: proto.Uint64(uint64(rusage.Stime.Usec)),
129		MinorPageFaults:  proto.Uint64(uint64(rusage.Minflt)),
130		MajorPageFaults:  proto.Uint64(uint64(rusage.Majflt)),
131		// ru_inblock and ru_oublock are measured in blocks of 512 bytes.
132		IoInputKb:                  proto.Uint64(uint64(rusage.Inblock / 2)),
133		IoOutputKb:                 proto.Uint64(uint64(rusage.Oublock / 2)),
134		VoluntaryContextSwitches:   proto.Uint64(uint64(rusage.Nvcsw)),
135		InvoluntaryContextSwitches: proto.Uint64(uint64(rusage.Nivcsw)),
136	})
137}
138
139// Begin starts tracing the event.
140func (t *EventTracer) Begin(name, desc string, _ tracer.Thread) {
141	t.push(newEvent(name, desc))
142}
143
144// End performs post calculations such as duration of the event, aggregates
145// the collected performance information into PerfInfo protobuf message.
146func (t *EventTracer) End(tracer.Thread) soong_metrics_proto.PerfInfo {
147	return t.pop().perfInfo()
148}
149