| // Copyright 2016 Google LLC |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package logadmin |
| |
| import ( |
| "context" |
| "errors" |
| "fmt" |
| |
| vkit "cloud.google.com/go/logging/apiv2" |
| "google.golang.org/api/iterator" |
| logpb "google.golang.org/genproto/googleapis/logging/v2" |
| maskpb "google.golang.org/genproto/protobuf/field_mask" |
| ) |
| |
| // Sink describes a sink used to export log entries outside Stackdriver |
| // Logging. Incoming log entries matching a filter are exported to a |
| // destination (a Cloud Storage bucket, BigQuery dataset or Cloud Pub/Sub |
| // topic). |
| // |
| // For more information, see https://cloud.google.com/logging/docs/export/using_exported_logs. |
| // (The Sinks in this package are what the documentation refers to as "project sinks".) |
| type Sink struct { |
| // ID is a client-assigned sink identifier. Example: |
| // "my-severe-errors-to-pubsub". |
| // Sink identifiers are limited to 1000 characters |
| // and can include only the following characters: A-Z, a-z, |
| // 0-9, and the special characters "_-.". |
| ID string |
| |
| // Destination is the export destination. See |
| // https://cloud.google.com/logging/docs/api/tasks/exporting-logs. |
| // Examples: "storage.googleapis.com/a-bucket", |
| // "bigquery.googleapis.com/projects/a-project-id/datasets/a-dataset". |
| Destination string |
| |
| // Filter optionally specifies an advanced logs filter (see |
| // https://cloud.google.com/logging/docs/view/advanced_filters) that |
| // defines the log entries to be exported. Example: "logName:syslog AND |
| // severity>=ERROR". If omitted, all entries are returned. |
| Filter string |
| |
| // WriterIdentity must be a service account name. When exporting logs, Logging |
| // adopts this identity for authorization. The export destination's owner must |
| // give this service account permission to write to the export destination. |
| WriterIdentity string |
| |
| // IncludeChildren, when set to true, allows the sink to export log entries from |
| // the organization or folder, plus (recursively) from any contained folders, billing |
| // accounts, or projects. IncludeChildren is false by default. You can use the sink's |
| // filter to choose log entries from specific projects, specific resource types, or |
| // specific named logs. |
| // |
| // Caution: If you enable this feature, your aggregated export sink might export |
| // a very large number of log entries. To avoid exporting too many log entries, |
| // design your aggregated export sink filter carefully, as described on |
| // https://cloud.google.com/logging/docs/export/aggregated_exports. |
| IncludeChildren bool |
| } |
| |
| // CreateSink creates a Sink. It returns an error if the Sink already exists. |
| // Requires AdminScope. |
| func (c *Client) CreateSink(ctx context.Context, sink *Sink) (*Sink, error) { |
| return c.CreateSinkOpt(ctx, sink, SinkOptions{}) |
| } |
| |
| // CreateSinkOpt creates a Sink using the provided options. It returns an |
| // error if the Sink already exists. Requires AdminScope. |
| func (c *Client) CreateSinkOpt(ctx context.Context, sink *Sink, opts SinkOptions) (*Sink, error) { |
| ls, err := c.sClient.CreateSink(ctx, &logpb.CreateSinkRequest{ |
| Parent: c.parent, |
| Sink: toLogSink(sink), |
| UniqueWriterIdentity: opts.UniqueWriterIdentity, |
| }) |
| if err != nil { |
| return nil, err |
| } |
| return fromLogSink(ls), nil |
| } |
| |
| // SinkOptions define options to be used when creating or updating a sink. |
| type SinkOptions struct { |
| // Determines the kind of IAM identity returned as WriterIdentity in the new |
| // sink. If this value is omitted or set to false, and if the sink's parent is a |
| // project, then the value returned as WriterIdentity is the same group or |
| // service account used by Stackdriver Logging before the addition of writer |
| // identities to the API. The sink's destination must be in the same project as |
| // the sink itself. |
| // |
| // If this field is set to true, or if the sink is owned by a non-project |
| // resource such as an organization, then the value of WriterIdentity will |
| // be a unique service account used only for exports from the new sink. |
| UniqueWriterIdentity bool |
| |
| // These fields apply only to UpdateSinkOpt calls. The corresponding sink field |
| // is updated if and only if the Update field is true. |
| UpdateDestination bool |
| UpdateFilter bool |
| UpdateIncludeChildren bool |
| } |
| |
| // DeleteSink deletes a sink. The provided sinkID is the sink's identifier, such as |
| // "my-severe-errors-to-pubsub". |
| // Requires AdminScope. |
| func (c *Client) DeleteSink(ctx context.Context, sinkID string) error { |
| return c.sClient.DeleteSink(ctx, &logpb.DeleteSinkRequest{ |
| SinkName: c.sinkPath(sinkID), |
| }) |
| } |
| |
| // Sink gets a sink. The provided sinkID is the sink's identifier, such as |
| // "my-severe-errors-to-pubsub". |
| // Requires ReadScope or AdminScope. |
| func (c *Client) Sink(ctx context.Context, sinkID string) (*Sink, error) { |
| ls, err := c.sClient.GetSink(ctx, &logpb.GetSinkRequest{ |
| SinkName: c.sinkPath(sinkID), |
| }) |
| if err != nil { |
| return nil, err |
| } |
| return fromLogSink(ls), nil |
| } |
| |
| // UpdateSink updates an existing Sink. Requires AdminScope. |
| // |
| // WARNING: UpdateSink will always update the Destination, Filter and IncludeChildren |
| // fields of the sink, even if they have their zero values. Use UpdateSinkOpt |
| // for more control over which fields to update. |
| func (c *Client) UpdateSink(ctx context.Context, sink *Sink) (*Sink, error) { |
| return c.UpdateSinkOpt(ctx, sink, SinkOptions{ |
| UpdateDestination: true, |
| UpdateFilter: true, |
| UpdateIncludeChildren: true, |
| }) |
| } |
| |
| // UpdateSinkOpt updates an existing Sink, using the provided options. Requires AdminScope. |
| // |
| // To change a sink's writer identity to a service account unique to the sink, set |
| // opts.UniqueWriterIdentity to true. It is not possible to change a sink's writer identity |
| // from a unique service account to a non-unique writer identity. |
| func (c *Client) UpdateSinkOpt(ctx context.Context, sink *Sink, opts SinkOptions) (*Sink, error) { |
| mask := &maskpb.FieldMask{} |
| if opts.UpdateDestination { |
| mask.Paths = append(mask.Paths, "destination") |
| } |
| if opts.UpdateFilter { |
| mask.Paths = append(mask.Paths, "filter") |
| } |
| if opts.UpdateIncludeChildren { |
| mask.Paths = append(mask.Paths, "include_children") |
| } |
| if opts.UniqueWriterIdentity && len(mask.Paths) == 0 { |
| // Hack: specify a deprecated, unchangeable field so that we have a non-empty |
| // field mask. (An empty field mask would cause the destination, filter and include_children |
| // fields to be changed.) |
| mask.Paths = append(mask.Paths, "output_version_format") |
| } |
| if len(mask.Paths) == 0 { |
| return nil, errors.New("logadmin: UpdateSinkOpt: nothing to update") |
| } |
| ls, err := c.sClient.UpdateSink(ctx, &logpb.UpdateSinkRequest{ |
| SinkName: c.sinkPath(sink.ID), |
| Sink: toLogSink(sink), |
| UniqueWriterIdentity: opts.UniqueWriterIdentity, |
| UpdateMask: mask, |
| }) |
| if err != nil { |
| return nil, err |
| } |
| return fromLogSink(ls), err |
| } |
| |
| func (c *Client) sinkPath(sinkID string) string { |
| return fmt.Sprintf("%s/sinks/%s", c.parent, sinkID) |
| } |
| |
| // Sinks returns a SinkIterator for iterating over all Sinks in the Client's project. |
| // Requires ReadScope or AdminScope. |
| func (c *Client) Sinks(ctx context.Context) *SinkIterator { |
| it := &SinkIterator{ |
| it: c.sClient.ListSinks(ctx, &logpb.ListSinksRequest{Parent: c.parent}), |
| } |
| it.pageInfo, it.nextFunc = iterator.NewPageInfo( |
| it.fetch, |
| func() int { return len(it.items) }, |
| func() interface{} { b := it.items; it.items = nil; return b }) |
| return it |
| } |
| |
| // A SinkIterator iterates over Sinks. |
| type SinkIterator struct { |
| it *vkit.LogSinkIterator |
| pageInfo *iterator.PageInfo |
| nextFunc func() error |
| items []*Sink |
| } |
| |
| // PageInfo supports pagination. See the google.golang.org/api/iterator package for details. |
| func (it *SinkIterator) PageInfo() *iterator.PageInfo { return it.pageInfo } |
| |
| // Next returns the next result. Its second return value is Done if there are |
| // no more results. Once Next returns Done, all subsequent calls will return |
| // Done. |
| func (it *SinkIterator) Next() (*Sink, error) { |
| if err := it.nextFunc(); err != nil { |
| return nil, err |
| } |
| item := it.items[0] |
| it.items = it.items[1:] |
| return item, nil |
| } |
| |
| func (it *SinkIterator) fetch(pageSize int, pageToken string) (string, error) { |
| return iterFetch(pageSize, pageToken, it.it.PageInfo(), func() error { |
| item, err := it.it.Next() |
| if err != nil { |
| return err |
| } |
| it.items = append(it.items, fromLogSink(item)) |
| return nil |
| }) |
| } |
| |
| func toLogSink(s *Sink) *logpb.LogSink { |
| return &logpb.LogSink{ |
| Name: s.ID, |
| Destination: s.Destination, |
| Filter: s.Filter, |
| IncludeChildren: s.IncludeChildren, |
| OutputVersionFormat: logpb.LogSink_V2, |
| // omit WriterIdentity because it is output-only. |
| } |
| } |
| |
| func fromLogSink(ls *logpb.LogSink) *Sink { |
| return &Sink{ |
| ID: ls.Name, |
| Destination: ls.Destination, |
| Filter: ls.Filter, |
| WriterIdentity: ls.WriterIdentity, |
| IncludeChildren: ls.IncludeChildren, |
| } |
| } |