monitoring: Improving the monitoring client library API

[BlueMonday]

TL;DR: It would be nice if the monitoring client library API:

• Provided functions which make it easy to send different types of metrics and only require parameters pertinent to the type of metric
• Wrapped the underlying protobuf packages and did not require knowledge of the packages being wrapped
• Batched metrics before sending them to Stackdriver

Improving the monitoring client API might be on someone's todo list already but there doesn't seem to be any issues currently tracking this (at least in this repository).

---

At the moment to send metrics to Stackdriver using the monitoring client library I have to do something like this:

        ctx := context.Background()
    metricClient, err := monitoring.NewMetricClient(ctx)
    if err != nil {
        return err
    }

    now := time.Now()
    timeProto, err := ptypes.TimestampProto(now)
    if err != nil {
        return err
    }

    createTimeSeriesReq := &monitoringpb.CreateTimeSeriesRequest{
        Name: monitoring.MetricProjectPath("dog-metrics-322"),
        TimeSeries: []*monitoringpb.TimeSeries{
            {
                Metric: &metricpb.Metric{
                    Type: "custom.googleapis.com/tail_wags_per_second",
                    Labels: map[string]string{
                                                "region": "us-west-dog-park1-a"
                                        },
                },
                Resource: &monitoredrespb.MonitoredResource{
                    Type: "global",
                },
                MetricKind: metricpb.MetricDescriptor_GAUGE,
                Points: []*monitoringpb.Point{
                    {
                        Interval: &monitoringpb.TimeInterval{
                            EndTime: timeProto,
                        },
                        Value: &monitoringpb.TypedValue{
                                                 Value: &monitoringpb.TypedValue_DoubleValue{
                                                     DoubleValue: 10.0,
                                                  },
                                             },
                    },
                },
            },
        },
    }

    err = metricClient.CreateTimeSeries(ctx, createTimeSeriesReq)
    if err != nil {
        return err
    }

The API is a bit verbose and tedious to use. A lot of the fields in the different structs don't have to be set depending on the type of metric. For example Point.TimeInterval.StartTime does not need to be set if the metric is a gauge. Having to figure out what needs and doesn't need to be set is not fun. I can create wrappers around the API for my particular use case to make it easier to use but it would be nice if I didn't have to.

Figuring out the structure of the message was also a bit of detective work. I had to bounce around the documentation for these 3 packages:

• cloud.google.com/go/monitoring/apiv3
• google.golang.org/genproto/googleapis/api/metric
• google.golang.org/genproto/googleapis/monitoring/v3

At the moment the code in this repository wraps the autogenerated protobuf code but requires developers to have knowledge of the code being wrapped in order to use it.

It would also be nice if the client API took care of batching requests. Based on the docs and a few tests it seems like stackdriver has limited batching capabilities though? Multiple points for the same metric can not be batched into the same request. It seems like the only supported behaviour is sending a single point for multiple metrics in a single request.

I was hoping the monitoring client API could be given a similar treatment to the logging client library API.

[pongad]

@jba Do you happen to know if monitoring is prioritized?

From the issue, I think the main issue is that the request object is large and difficult to get right. The code generator doesn't help with this difficulty. This is something we should consider for generator v2.

[s-mang]

cc @zombiezen I think we talked a few weeks ago (with @jba too) about whether or not to prioritize a handwritten client for monitoring, and decided against it b/c we didn't think sending custom metrics was a popular use-case (at least, not as popular as some of the higher-priority clients). Perhaps we should reconsider pushing for this?

[jba]

Moved to https://github.com/GoogleCloudPlatform/google-cloud-go/wiki/Feature-Backlog.