luci-go: Basic support for event logging in Go.

common/eventlog/eventlog.go

Index: common/eventlog/eventlog.go
diff --git a/common/eventlog/eventlog.go b/common/eventlog/eventlog.go
new file mode 100644
index 0000000000000000000000000000000000000000..bb36d144420296a63b34f23fb9b8ead530f80d67
--- /dev/null
+++ b/common/eventlog/eventlog.go
@@ -0,0 +1,101 @@
+// Copyright 2016 The LUCI Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package eventlog provides a client which can be used to to collect and send batches of ChromeInfraEvent logs to the eventlog service.
+package eventlog
+
+import (
+	"net/http"
+	"time"
+
+	"golang.org/x/net/context"
+
+	"github.com/golang/protobuf/proto"
+	"github.com/luci/luci-go/common/eventlog/internal/logservice"
+	logpb "github.com/luci/luci-go/common/eventlog/proto"
+)
+
+// TestEndpoint is the server address for test logs.
+const TestEndpoint = "https://jmt17.google.com/log"
+
+// ProdEndpoint is the server address for production logs.
+const ProdEndpoint = "https://play.googleapis.com/log"
+
+// Client may be used to send ChromeInfraEvent logs to the eventlog service.
+type Client struct {
+	c *logservice.Client
+
+	// EventSource identifies the log producer. It may be configured before sending logs.
+	EventSource *logpb.InfraEventSource
+}
+
+// NewClient constructs a Client which can be used to send ChromeInfraEvent logs to the eventlog service.
+// Users must call Close when the Client is no longer needed.
+func NewClient(serverAddr string, opts ...ClientOption) *Client {
+	// TODO(mcgreevy): help users to set EventSource?
+
+	settings := clientSettings{
+		HTTPClient: http.DefaultClient,
+	}
+	settings.Populate(opts)
+
+	serviceClient := logservice.NewClient(serverAddr, "CHROME_INFRA")
+	serviceClient.HTTPClient = settings.HTTPClient
+	return &Client{c: serviceClient}
+}
+
+// LogSync synchronously logs events to the eventlog service.
+// Use NewLogEvent to assist with constructing a well-formed log event.
+// LogSync takes ownership of events.
+func (c *Client) LogSync(ctx context.Context, events []*ChromeInfraLogEvent) error {

[djd-OOO-Apr2017, 2016/11/21 04:02:24]

I'd use the ... form for events here (for the common case, you wouldn't need to
mint a slice).

[mcgreevy, 2016/11/21 04:51:06]

Done.

+	var logEvents []*logpb.LogRequestLite_LogEventLite
+
+	for _, event := range events {
+		sourceExt, err := proto.Marshal(event.InfraEvent)
+		if err != nil {
+			return err
+		}
+		event.LogEvent.SourceExtension = sourceExt
+		logEvents = append(logEvents, event.LogEvent)
+	}
+
+	return c.c.LogSync(ctx, logEvents)
+}
+
+// NewLogEvent constructs a well-formed log event.
+func (c *Client) NewLogEvent(ctx context.Context, eventTime TypedTime) *ChromeInfraLogEvent {
+	// TODO(mcgreevy): look into whether we can populate TraceID, SpanId, ParentId from the context.
+	// TODO(mcgreevy): support event_code, event_flow_id.
+	return &ChromeInfraLogEvent{
+		LogEvent: &logpb.LogRequestLite_LogEventLite{
+			EventTimeMs: proto.Int64(eventTime.Time.UnixNano() / 1e6),
+		},
+		InfraEvent: &logpb.ChromeInfraEvent{
+			TimestampKind: &eventTime.Kind,
+			EventSource:   c.EventSource,
+		},
+	}
+}
+
+// Close flushes any pending logs and releases any resources held by the client.
+// Close should be called when the client is no longer needed.
+func (c *Client) Close() error {
+	return c.c.Close()
+}
+
+// ChromeInfraLogEvent stores a pending LogEvent, and the proto used to populate its SourceExtension field.
+type ChromeInfraLogEvent struct {
+	// LogEvent is the event to be sent to the server. The LogEvent's SourceExtension
+	// field will be overwritten with the serialized contents of InfraEvent
+	// when the log event is sent to the server.
+	LogEvent   *logpb.LogRequestLite_LogEventLite
+	InfraEvent *logpb.ChromeInfraEvent
+}
+
+// TypedTime is a time, accompanied by an indication of what the time represents.
+type TypedTime struct {
+	// The time at which an event occurrred. Must have been obtained from Time.Now.

[djd-OOO-Apr2017, 2016/11/21 04:02:24]

sp. occurred

The "must have been obtained" is the bit that's kinda, uh, funny. It feels like
we should be able to just do that for the user.

Could NewLogEvent just take the enum directly?

[mcgreevy, 2016/11/21 04:51:06]

Yeah, it could, but I'm worried about making this API too inflexible.  What if
they want to record the time that they started handling a request and only later
create and log an event, passing in the start time? Calling time.Now for them
kind of inhibits that. It would still be doable -- they only have to override
the EventTimeMs in the returned proto, but I don't really want to encourage
that.

Perhaps this is where some helper functions could come in handy:

// Returns Now as a Point
func Point() TypedTime {...}

// Returns Now as a Begin
func Begin() TypedTime {...}

// Returns Now as an End
func End() TypedTime {...}


// Or:

func Now(kind TimeKind) TypedTime {}

type TimeKind int32

const (
  Unknown TimeKind = iota
  Point
  Begin
  End 
)

This pushes the weirdness away from the common usage -- you only need care about
it if you try to construct a TypedTime manually.

WDYT?

[djd-OOO-Apr2017, 2016/11/21 05:51:26]

I like the first of those options (Point/Begin/End) more. They feel less fussy.

I think making a copy of the enum is interesting, but it's weird you're doing it
for that part of the proto and not the entire structure.

+	Time time.Time
+	Kind logpb.ChromeInfraEvent_TimestampKind
+}