Merge "Add and update comments in ui/metrics/metrics.go."
diff --git a/ui/metrics/metrics.go b/ui/metrics/metrics.go
index 1cef2c7..efb572c 100644
--- a/ui/metrics/metrics.go
+++ b/ui/metrics/metrics.go
@@ -12,8 +12,30 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+// Package metrics represents the metrics system for Android Platform Build Systems.
package metrics
+// This is the main heart of the metrics system for Android Platform Build Systems.
+// The starting of the soong_ui (cmd/soong_ui/main.go), the metrics system is
+// initialized by the invocation of New and is then stored in the context
+// (ui/build/context.go) to be used throughout the system. During the build
+// initialization phase, several functions in this file are invoked to store
+// information such as the environment, build configuration and build metadata.
+// There are several scoped code that has Begin() and defer End() functions
+// that captures the metrics and is them added as a perfInfo into the set
+// of the collected metrics. Finally, when soong_ui has finished the build,
+// the defer Dump function is invoked to store the collected metrics to the
+// raw protobuf file in the $OUT directory.
+//
+// There is one additional step that occurs after the raw protobuf file is written.
+// If the configuration environment variable ANDROID_ENABLE_METRICS_UPLOAD is
+// set with the path, the raw protobuf file is uploaded to the destination. See
+// ui/build/upload.go for more details. The filename of the raw protobuf file
+// and the list of files to be uploaded is defined in cmd/soong_ui/main.go.
+//
+// See ui/metrics/event.go for the explanation of what an event is and how
+// the metrics system is a stack based system.
+
import (
"io/ioutil"
"os"
@@ -27,21 +49,37 @@
)
const (
- PrimaryNinja = "ninja"
- RunKati = "kati"
+ // Below is a list of names passed in to the Begin tracing functions. These
+ // names are used to group a set of metrics.
+
+ // Setup and tear down of the build systems.
RunSetupTool = "setup"
RunShutdownTool = "shutdown"
- RunSoong = "soong"
- RunBazel = "bazel"
TestRun = "test"
- Total = "total"
+
+ // List of build system tools.
+ RunSoong = "soong"
+ PrimaryNinja = "ninja"
+ RunKati = "kati"
+ RunBazel = "bazel"
+
+ // Overall build from building the graph to building the target.
+ Total = "total"
)
+// Metrics is a struct that stores collected metrics during the course
+// of a build which later is dumped to a MetricsBase protobuf file.
+// See ui/metrics/metrics_proto/metrics.proto for further details
+// on what information is collected.
type Metrics struct {
- metrics soong_metrics_proto.MetricsBase
+ // The protobuf message that is later written to the file.
+ metrics soong_metrics_proto.MetricsBase
+
+ // A list of pending build events.
EventTracer *EventTracer
}
+// New returns a pointer of Metrics to store a set of metrics.
func New() (metrics *Metrics) {
m := &Metrics{
metrics: soong_metrics_proto.MetricsBase{},
@@ -50,6 +88,8 @@
return m
}
+// SetTimeMetrics stores performance information from an executed block of
+// code.
func (m *Metrics) SetTimeMetrics(perf soong_metrics_proto.PerfInfo) {
switch perf.GetName() {
case RunKati:
@@ -67,14 +107,19 @@
}
}
+// BuildConfig stores information about the build configuration.
func (m *Metrics) BuildConfig(b *soong_metrics_proto.BuildConfig) {
m.metrics.BuildConfig = b
}
+// SystemResourceInfo stores information related to the host system such
+// as total CPU and memory.
func (m *Metrics) SystemResourceInfo(b *soong_metrics_proto.SystemResourceInfo) {
m.metrics.SystemResourceInfo = b
}
+// SetMetadataMetrics sets information about the build such as the target
+// product, host architecture and out directory.
func (m *Metrics) SetMetadataMetrics(metadata map[string]string) {
for k, v := range metadata {
switch k {
@@ -94,15 +139,15 @@
m.metrics.TargetBuildVariant = soong_metrics_proto.MetricsBase_ENG.Enum()
}
case "TARGET_ARCH":
- m.metrics.TargetArch = m.getArch(v)
+ m.metrics.TargetArch = arch(v)
case "TARGET_ARCH_VARIANT":
m.metrics.TargetArchVariant = proto.String(v)
case "TARGET_CPU_VARIANT":
m.metrics.TargetCpuVariant = proto.String(v)
case "HOST_ARCH":
- m.metrics.HostArch = m.getArch(v)
+ m.metrics.HostArch = arch(v)
case "HOST_2ND_ARCH":
- m.metrics.Host_2NdArch = m.getArch(v)
+ m.metrics.Host_2NdArch = arch(v)
case "HOST_OS_EXTRA":
m.metrics.HostOsExtra = proto.String(v)
case "HOST_CROSS_OS":
@@ -117,8 +162,10 @@
}
}
-func (m *Metrics) getArch(arch string) *soong_metrics_proto.MetricsBase_Arch {
- switch arch {
+// arch returns the corresponding MetricsBase_Arch based on the string
+// parameter.
+func arch(a string) *soong_metrics_proto.MetricsBase_Arch {
+ switch a {
case "arm":
return soong_metrics_proto.MetricsBase_ARM.Enum()
case "arm64":
@@ -132,37 +179,51 @@
}
}
+// SetBuildDateTime sets the build date and time. The value written
+// to the protobuf file is in seconds.
func (m *Metrics) SetBuildDateTime(buildTimestamp time.Time) {
m.metrics.BuildDateTimestamp = proto.Int64(buildTimestamp.UnixNano() / int64(time.Second))
}
+// SetBuildCommand adds the build command specified by the user to the
+// list of collected metrics.
func (m *Metrics) SetBuildCommand(cmd []string) {
m.metrics.BuildCommand = proto.String(strings.Join(cmd, " "))
}
-// exports the output to the file at outputPath
-func (m *Metrics) Dump(outputPath string) error {
+// Dump exports the collected metrics from the executed build to the file at
+// out path.
+func (m *Metrics) Dump(out string) error {
// ignore the error if the hostname could not be retrieved as it
// is not a critical metric to extract.
if hostname, err := os.Hostname(); err == nil {
m.metrics.Hostname = proto.String(hostname)
}
m.metrics.HostOs = proto.String(runtime.GOOS)
- return writeMessageToFile(&m.metrics, outputPath)
+
+ return save(&m.metrics, out)
}
+// SetSoongBuildMetrics sets the metrics collected from the soong_build
+// execution.
func (m *Metrics) SetSoongBuildMetrics(metrics *soong_metrics_proto.SoongBuildMetrics) {
m.metrics.SoongBuildMetrics = metrics
}
+// A CriticalUserJourneysMetrics is a struct that contains critical user journey
+// metrics. These critical user journeys are defined under cuj/cuj.go file.
type CriticalUserJourneysMetrics struct {
+ // A list of collected CUJ metrics.
cujs soong_metrics_proto.CriticalUserJourneysMetrics
}
+// NewCriticalUserJourneyMetrics returns a pointer of CriticalUserJourneyMetrics
+// to capture CUJs metrics.
func NewCriticalUserJourneysMetrics() *CriticalUserJourneysMetrics {
return &CriticalUserJourneysMetrics{}
}
+// Add adds a set of collected metrics from an executed critical user journey.
func (c *CriticalUserJourneysMetrics) Add(name string, metrics *Metrics) {
c.cujs.Cujs = append(c.cujs.Cujs, &soong_metrics_proto.CriticalUserJourneyMetrics{
Name: proto.String(name),
@@ -170,22 +231,25 @@
})
}
-func (c *CriticalUserJourneysMetrics) Dump(outputPath string) (err error) {
- return writeMessageToFile(&c.cujs, outputPath)
+// Dump saves the collected CUJs metrics to the raw protobuf file.
+func (c *CriticalUserJourneysMetrics) Dump(filename string) (err error) {
+ return save(&c.cujs, filename)
}
-func writeMessageToFile(pb proto.Message, outputPath string) (err error) {
+// save takes a protobuf message, marshals to an array of bytes
+// and is then saved to a file.
+func save(pb proto.Message, filename string) (err error) {
data, err := proto.Marshal(pb)
if err != nil {
return err
}
- tempPath := outputPath + ".tmp"
- err = ioutil.WriteFile(tempPath, []byte(data), 0644)
- if err != nil {
+
+ tempFilename := filename + ".tmp"
+ if err := ioutil.WriteFile(tempFilename, []byte(data), 0644 /* rw-r--r-- */); err != nil {
return err
}
- err = os.Rename(tempPath, outputPath)
- if err != nil {
+
+ if err := os.Rename(tempFilename, filename); err != nil {
return err
}