metrics.go

Documentation: cloud.google.com/go/logging/logadmin

     1  // Copyright 2016 Google LLC
     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  
    15  package logadmin
    16  
    17  import (
    18  	"context"
    19  	"fmt"
    20  
    21  	vkit "cloud.google.com/go/logging/apiv2"
    22  	logpb "cloud.google.com/go/logging/apiv2/loggingpb"
    23  	"google.golang.org/api/iterator"
    24  )
    25  
    26  // Metric describes a logs-based metric. The value of the metric is the
    27  // number of log entries that match a logs filter.
    28  //
    29  // Metrics are a feature of Cloud Monitoring.
    30  // See https://cloud.google.com/monitoring/api/v3/metrics for more about them.
    31  type Metric struct {
    32  	// ID is a client-assigned metric identifier. Example:
    33  	// "severe_errors".  Metric identifiers are limited to 1000
    34  	// characters and can include only the following characters: A-Z,
    35  	// a-z, 0-9, and the special characters _-.,+!*',()%/\.  The
    36  	// forward-slash character (/) denotes a hierarchy of name pieces,
    37  	// and it cannot be the first character of the name.
    38  	ID string
    39  
    40  	// Description describes this metric. It is used in documentation.
    41  	Description string
    42  
    43  	// Filter is an advanced logs filter (see
    44  	// https://cloud.google.com/logging/docs/view/advanced_filters).
    45  	// Example: "logName:syslog AND severity>=ERROR".
    46  	Filter string
    47  }
    48  
    49  // CreateMetric creates a logs-based metric.
    50  func (c *Client) CreateMetric(ctx context.Context, m *Metric) error {
    51  	_, err := c.mClient.CreateLogMetric(ctx, &logpb.CreateLogMetricRequest{
    52  		Parent: c.parent,
    53  		Metric: toLogMetric(m),
    54  	})
    55  	return err
    56  }
    57  
    58  // DeleteMetric deletes a log-based metric.
    59  // The provided metric ID is the metric identifier. For example, "severe_errors".
    60  func (c *Client) DeleteMetric(ctx context.Context, metricID string) error {
    61  	return c.mClient.DeleteLogMetric(ctx, &logpb.DeleteLogMetricRequest{
    62  		MetricName: c.metricPath(metricID),
    63  	})
    64  }
    65  
    66  // Metric gets a logs-based metric.
    67  // The provided metric ID is the metric identifier. For example, "severe_errors".
    68  // Requires ReadScope or AdminScope.
    69  func (c *Client) Metric(ctx context.Context, metricID string) (*Metric, error) {
    70  	lm, err := c.mClient.GetLogMetric(ctx, &logpb.GetLogMetricRequest{
    71  		MetricName: c.metricPath(metricID),
    72  	})
    73  	if err != nil {
    74  		return nil, err
    75  	}
    76  	return fromLogMetric(lm), nil
    77  }
    78  
    79  // UpdateMetric creates a logs-based metric if it does not exist, or updates an
    80  // existing one.
    81  func (c *Client) UpdateMetric(ctx context.Context, m *Metric) error {
    82  	_, err := c.mClient.UpdateLogMetric(ctx, &logpb.UpdateLogMetricRequest{
    83  		MetricName: c.metricPath(m.ID),
    84  		Metric:     toLogMetric(m),
    85  	})
    86  	return err
    87  }
    88  
    89  func (c *Client) metricPath(metricID string) string {
    90  	return fmt.Sprintf("%s/metrics/%s", c.parent, metricID)
    91  }
    92  
    93  // Metrics returns a MetricIterator for iterating over all Metrics in the Client's project.
    94  // Requires ReadScope or AdminScope.
    95  func (c *Client) Metrics(ctx context.Context) *MetricIterator {
    96  	it := &MetricIterator{
    97  		it: c.mClient.ListLogMetrics(ctx, &logpb.ListLogMetricsRequest{Parent: c.parent}),
    98  	}
    99  	it.pageInfo, it.nextFunc = iterator.NewPageInfo(
   100  		it.fetch,
   101  		func() int { return len(it.items) },
   102  		func() interface{} { b := it.items; it.items = nil; return b })
   103  	return it
   104  }
   105  
   106  // A MetricIterator iterates over Metrics.
   107  type MetricIterator struct {
   108  	it       *vkit.LogMetricIterator
   109  	pageInfo *iterator.PageInfo
   110  	nextFunc func() error
   111  	items    []*Metric
   112  }
   113  
   114  // PageInfo supports pagination. See the google.golang.org/api/iterator package for details.
   115  func (it *MetricIterator) PageInfo() *iterator.PageInfo { return it.pageInfo }
   116  
   117  // Next returns the next result. Its second return value is Done if there are
   118  // no more results. Once Next returns Done, all subsequent calls will return
   119  // Done.
   120  func (it *MetricIterator) Next() (*Metric, error) {
   121  	if err := it.nextFunc(); err != nil {
   122  		return nil, err
   123  	}
   124  	item := it.items[0]
   125  	it.items = it.items[1:]
   126  	return item, nil
   127  }
   128  
   129  func (it *MetricIterator) fetch(pageSize int, pageToken string) (string, error) {
   130  	return iterFetch(pageSize, pageToken, it.it.PageInfo(), func() error {
   131  		item, err := it.it.Next()
   132  		if err != nil {
   133  			return err
   134  		}
   135  		it.items = append(it.items, fromLogMetric(item))
   136  		return nil
   137  	})
   138  }
   139  
   140  func toLogMetric(m *Metric) *logpb.LogMetric {
   141  	return &logpb.LogMetric{
   142  		Name:        m.ID,
   143  		Description: m.Description,
   144  		Filter:      m.Filter,
   145  	}
   146  }
   147  
   148  func fromLogMetric(lm *logpb.LogMetric) *Metric {
   149  	return &Metric{
   150  		ID:          lm.Name,
   151  		Description: lm.Description,
   152  		Filter:      lm.Filter,
   153  	}
   154  }
   155
View as plain text