google-cloud-logging 2.0.0

data/lib/google/cloud/logging/resource_descriptor/list.rb

@@ -0,0 +1,175 @@
+# 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
+#
+#     https://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.
+
+
+require "delegate"
+
+module Google
+  module Cloud
+    module Logging
+      class ResourceDescriptor
+        ##
+        # ResourceDescriptor::List is a special case Array with additional
+        # values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more records that match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new ResourceDescriptor::List with an array of
+          # ResourceDescriptor instances.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of resource descriptors.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #
+          #   resource_descriptors = logging.resource_descriptors
+          #   if resource_descriptors.next?
+          #     next_resource_descriptors = resource_descriptors.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of resource descriptors.
+          #
+          # @return [Sink::List]
+          #
+          # @example
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #
+          #   resource_descriptors = logging.resource_descriptors
+          #   if resource_descriptors.next?
+          #     next_resource_descriptors = resource_descriptors.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            list_grpc = @service.list_resource_descriptors(
+              token: token, max: @max
+            )
+            self.class.from_grpc list_grpc, @service, @max
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all resource descriptors. Default is no limit.
+          # @yield [resource_descriptor] The block for accessing each resource
+          #   descriptor.
+          # @yieldparam [ResourceDescriptor] resource_descriptor The resource
+          #   descriptor object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each resource descriptor by passing a block:
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #   resource_descriptors = logging.resource_descriptors
+          #
+          #   resource_descriptors.all do |rd|
+          #     puts rd.type
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #   resource_descriptors = logging.resource_descriptors
+          #
+          #   all_types = resource_descriptors.all.map do |rd|
+          #     rd.type
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud/logging"
+          #
+          #   logging = Google::Cloud::Logging.new
+          #   resource_descriptors = logging.resource_descriptors
+          #
+          #   resource_descriptors.all(request_limit: 10) do |rd|
+          #     puts rd.type
+          #   end
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            unless block_given?
+              return enum_for :all, request_limit: request_limit
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New ResourceDescriptor::List from a
+          # Google::Cloud::Logging::V2::ListMonitoredResourceDescriptorsResponse
+          # object.
+          def self.from_grpc grpc_list, service, max = nil
+            rds = new(Array(grpc_list.resource_descriptors).map do |grpc|
+              ResourceDescriptor.from_grpc grpc
+            end)
+            token = grpc_list.next_page_token
+            token = nil if token == "".freeze
+            rds.instance_variable_set :@token,   token
+            rds.instance_variable_set :@service, service
+            rds.instance_variable_set :@max,     max
+            rds
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active service is available.
+          def ensure_service!
+            raise "Must have active service" unless @service
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/logging/service.rb

@@ -0,0 +1,239 @@
+# 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
+#
+#     https://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.
+
+
+require "google/cloud/errors"
+require "google/cloud/logging/version"
+require "google/cloud/logging/v2"
+require "uri"
+
+module Google
+  module Cloud
+    module Logging
+      ##
+      # @private Represents the gRPC Logging service, including all the API
+      # methods.
+      class Service
+        attr_accessor :project, :credentials, :timeout, :host
+
+        ##
+        # Creates a new Service instance.
+        def initialize project, credentials, timeout: nil, host: nil
+          @project = project
+          @credentials = credentials
+          @timeout = timeout
+          @host = host
+        end
+
+        def logging
+          return mocked_logging if mocked_logging
+          @logging ||= \
+            V2::LoggingService::Client.new do |config|
+              config.credentials = credentials if credentials
+              config.timeout = timeout if timeout
+              config.endpoint = host if host
+              config.lib_name = "gccl"
+              config.lib_version = Google::Cloud::Logging::VERSION
+              config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+            end
+        end
+        attr_accessor :mocked_logging
+
+        def sinks
+          return mocked_sinks if mocked_sinks
+          @sinks ||= \
+            V2::ConfigService::Client.new do |config|
+              config.credentials = credentials if credentials
+              config.timeout = timeout if timeout
+              config.endpoint = host if host
+              config.lib_name = "gccl"
+              config.lib_version = Google::Cloud::Logging::VERSION
+              config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+            end
+        end
+        attr_accessor :mocked_sinks
+
+        def metrics
+          return mocked_metrics if mocked_metrics
+          @metrics ||= \
+            V2::MetricsService::Client.new do |config|
+              config.credentials = credentials if credentials
+              config.timeout = timeout if timeout
+              config.endpoint = host if host
+              config.lib_name = "gccl"
+              config.lib_version = Google::Cloud::Logging::VERSION
+              config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+            end
+        end
+        attr_accessor :mocked_metrics
+
+        def list_entries resources: nil, filter: nil, order: nil, token: nil,
+                         max: nil, projects: nil
+
+          project_ids = Array(projects).map { |p| "projects/#{p}" }
+          resource_names = Array(resources) + project_ids
+          resource_names = ["projects/#{@project}"] if resource_names.empty?
+          paged_enum = logging.list_log_entries resource_names: resource_names,
+                                                filter:         filter,
+                                                order_by:       order,
+                                                page_size:      max,
+                                                page_token:     token
+          paged_enum.response
+        end
+
+        def write_entries entries, log_name: nil, resource: nil, labels: nil,
+                          partial_success: nil
+          # Fix log names so they are the full path
+          entries = Array(entries).each do |entry|
+            entry.log_name = log_path entry.log_name
+          end
+          resource = resource.to_grpc if resource
+          labels = Hash[labels.map { |k, v| [String(k), String(v)] }] if labels
+          logging.write_log_entries entries:         entries,
+                                    log_name:        log_path(log_name),
+                                    resource:        resource,
+                                    labels:          labels,
+                                    partial_success: partial_success
+        end
+
+        def list_logs resource: nil, token: nil, max: nil
+          parent = resource || "projects/#{@project}"
+          paged_enum = logging.list_logs parent:     parent,
+                                         page_size:  max,
+                                         page_token: token
+          paged_enum.response
+        end
+
+        def delete_log name
+          logging.delete_log log_name: log_path(name)
+        end
+
+        def list_resource_descriptors token: nil, max: nil
+          logging.list_monitored_resource_descriptors page_size: max, page_token: token
+        end
+
+        def list_sinks token: nil, max: nil
+          paged_enum = sinks.list_sinks parent: project_path, page_size: max, page_token: token
+          paged_enum.response
+        end
+
+        def create_sink name, destination, filter, unique_writer_identity: nil
+          sink = Google::Cloud::Logging::V2::LogSink.new(
+            {
+              name: name, destination: destination, filter: filter
+            }.delete_if { |_, v| v.nil? }
+          )
+          sinks.create_sink parent:                 project_path,
+                            sink:                   sink,
+                            unique_writer_identity: unique_writer_identity
+        end
+
+        def get_sink name
+          sinks.get_sink sink_name: sink_path(name)
+        end
+
+        def update_sink name, destination, filter, unique_writer_identity: nil
+          sink = Google::Cloud::Logging::V2::LogSink.new(
+            {
+              name: name, destination: destination, filter: filter
+            }.delete_if { |_, v| v.nil? }
+          )
+          sinks.update_sink sink_name:              sink_path(name),
+                            sink:                   sink,
+                            unique_writer_identity: unique_writer_identity
+        end
+
+        def delete_sink name
+          sinks.delete_sink sink_name: sink_path(name)
+        end
+
+        def list_metrics token: nil, max: nil
+          paged_enum = metrics.list_log_metrics parent:     project_path,
+                                                page_size:  max,
+                                                page_token: token
+          paged_enum.response
+        end
+
+        def create_metric name, filter, description
+          metric = Google::Cloud::Logging::V2::LogMetric.new(
+            { name: name, description: description,
+              filter: filter }.delete_if { |_, v| v.nil? }
+          )
+          metrics.create_log_metric parent: project_path, metric: metric
+        end
+
+        def get_metric name
+          metrics.get_log_metric metric_name: metric_path(name)
+        end
+
+        def update_metric name, description, filter
+          metric = Google::Cloud::Logging::V2::LogMetric.new(
+            { name: name, description: description,
+              filter: filter }.delete_if { |_, v| v.nil? }
+          )
+          metrics.update_log_metric metric_name: metric_path(name), metric: metric
+        end
+
+        def delete_metric name
+          metrics.delete_log_metric metric_name: metric_path(name)
+        end
+
+        def log_path log_name
+          return nil if log_name.nil?
+          return log_name if log_name.empty?
+          return log_name if log_name.to_s.include? "/"
+          "#{project_path}/logs/#{log_name}"
+        end
+
+        def inspect
+          "#{self.class}(#{@project})"
+        end
+
+        protected
+
+        def project_path
+          "projects/#{@project}"
+        end
+
+        def sink_path sink_name
+          return sink_name if sink_name.to_s.include? "/"
+          "#{project_path}/sinks/#{sink_name}"
+        end
+
+        def metric_path metric_name
+          return metric_name if metric_name.to_s.include? "/"
+          "#{project_path}/metrics/#{metric_name}"
+        end
+
+        ##
+        # @private Get a Google::Protobuf::Timestamp object from a Time object.
+        def time_to_timestamp time
+          return nil if time.nil?
+          # Make sure we have a Time object
+          return nil unless time.respond_to? :to_time
+          time = time.to_time
+          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
+        end
+
+        ##
+        # @private Get a Time object from a Google::Protobuf::Timestamp object.
+        def timestamp_to_time timestamp
+          return nil if timestamp.nil?
+          # Time.at takes microseconds, so convert nano seconds to microseconds
+          Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/logging/sink.rb

@@ -0,0 +1,315 @@
+# 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
+#
+#     https://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.
+
+
+require "google/cloud/logging/sink/list"
+
+module Google
+  module Cloud
+    module Logging
+      ##
+      # # Sink
+      #
+      # Used to export log entries outside Stackdriver Logging. When you create
+      # a sink, new log entries are exported. Stackdriver Logging does not send
+      # previously-ingested log entries to the sink's destination.
+      #
+      # A logs filter controls which log entries are exported.
+      #
+      # Before creating the sink, ensure that you have granted the sink's
+      # _unique writer identity_ permission to write logs to the destination.
+      # See [Destination
+      # permissions](https://cloud.google.com/logging/docs/export/configure_export_v2#dest-auth).
+      #
+      # You can retrieve an existing sink with {Project#sink}.
+      #
+      # @see https://cloud.google.com/logging/docs/export
+      #   Overview of logs exports
+      # @see https://cloud.google.com/logging/docs/reference/v2/rpc/google.logging.v2#configservicev2
+      #   ConfigService API which includes sink methods
+      #
+      # @example
+      #   require "google/cloud/storage"
+      #
+      #   storage = Google::Cloud::Storage.new
+      #   bucket = storage.create_bucket "my-logs-bucket"
+      #
+      #   # Grant owner permission to Stackdriver Logging service
+      #   email = "cloud-logs@google.com"
+      #   bucket.acl.add_owner "group-#{email}"
+      #
+      #   require "google/cloud/logging"
+      #
+      #   logging = Google::Cloud::Logging.new
+      #   sink = logging.create_sink "my-sink",
+      #                              "storage.googleapis.com/#{bucket.id}"
+      #
+      class Sink
+        ##
+        # @private The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # @private The Google API Client object.
+        attr_accessor :grpc
+
+        ##
+        # @private Create an empty Sink object.
+        def initialize
+          @service = nil
+          @grpc = Google::Cloud::Logging::V2::LogSink.new
+        end
+
+        ##
+        # The client-assigned sink identifier. Sink identifiers are limited to
+        # 1000 characters and can include only the following characters: `A-Z`,
+        # `a-z`, `0-9`, and the special characters `_-.`.
+        def name
+          @grpc.name
+        end
+
+        ##
+        # The export destination. See [Properties of
+        # Sinks](https://cloud.google.com/logging/docs/export#sink-terms).
+        def destination
+          @grpc.destination
+        end
+
+        ##
+        # Updates the export destination. See [Properties of
+        # Sinks](https://cloud.google.com/logging/docs/export#sink-terms).
+        def destination= destination
+          @grpc.destination = destination
+        end
+
+        ##
+        # An [advanced logs
+        # filter](https://cloud.google.com/logging/docs/view/advanced-queries)
+        # that defines the log entries to be exported. The filter must be
+        # consistent with the log entry format designed by the `version`
+        # parameter, regardless of the format of the log entry that was
+        # originally written to Stackdriver Logging.
+        def filter
+          @grpc.filter
+        end
+
+        ##
+        # Updates the [advanced logs
+        # filter](https://cloud.google.com/logging/docs/view/advanced-queries)
+        # that defines the log entries to be exported. The filter must be
+        # consistent with the log entry format designed by the `version`
+        # parameter, regardless of the format of the log entry that was
+        # originally written to Stackdriver Logging.
+        def filter= filter
+          @grpc.filter = filter
+        end
+
+        ##
+        # **Deprecated.** The log entry version used when exporting log entries
+        # from this sink. This version does not have to correspond to the
+        # version of the log entry when it was written to Stackdriver Logging.
+        #
+        # @deprecated The v2 format is used by default and cannot be changed.
+        def version
+          warn "[DEPRECATION] version is deprecated."
+          :V2
+        end
+
+        ##
+        # **Deprecated.** Updates the log entry version used when exporting log
+        # entries from this sink. This version does not have to correspond to
+        # the version of the log entry when it was written to Stackdriver
+        # Logging. Accepted values are `:VERSION_FORMAT_UNSPECIFIED`, `:V2`, and
+        # `:V1`.
+        #
+        # @deprecated The v2 format is used by default and cannot be changed.
+        def version= _version
+          warn "[DEPRECATION] version= is deprecated and will be ignored."
+        end
+
+        ##
+        # Helper to determine if the sink's version is
+        # `VERSION_FORMAT_UNSPECIFIED`.
+        #
+        # @deprecated The v2 format is used by default and cannot be changed.
+        def unspecified?
+          warn "[DEPRECATION] unspecified? is deprecated."
+          false
+        end
+
+        ##
+        # Helper to determine if the sink's version is `V2`.
+        #
+        # @deprecated The v2 format is used by default and cannot be changed.
+        def v2?
+          warn "[DEPRECATION] v2? is deprecated."
+          true
+        end
+
+        ##
+        # Helper to determine if the sink's version is `V1`.
+        #
+        # @deprecated The v2 format is used by default and cannot be changed.
+        def v1?
+          warn "[DEPRECATION] v1? is deprecated."
+          false
+        end
+
+        ##
+        # **Deprecated.** The time at which this sink will begin exporting log
+        # entries. If this value is present, then log entries are exported only
+        # if `start_at` is less than the log entry's timestamp. Optional.
+        #
+        # @deprecated This field is ignored when creating or updating sinks.
+        def start_at
+          warn "[DEPRECATION] start_at is deprecated."
+          nil
+        end
+        alias start_time start_at
+
+        ##
+        # **Deprecated.** Sets the time at which this sink will begin exporting
+        # log entries. If this value is present, then log entries are exported
+        # only if `start_at` is less than the log entry's timestamp. Optional.
+        #
+        # @deprecated This field is ignored when creating or updating sinks.
+        def start_at= _new_start_at
+          warn "[DEPRECATION] start_at= is deprecated and will be ignored."
+        end
+        alias start_time= start_at=
+
+        ##
+        # **Deprecated.** Time at which this sink will stop exporting log
+        # entries. If this value is present, then log entries are exported only
+        # if the log entry's timestamp is less than `end_at`. Optional.
+        #
+        # @deprecated This field is ignored when creating or updating sinks.
+        def end_at
+          warn "[DEPRECATION] end_at is deprecated."
+          nil
+        end
+        alias end_time end_at
+
+        ##
+        # **Deprecated.** Sets the time at which this sink will stop exporting
+        # log entries. If this value is present, then log entries are exported
+        # only if the log entry's timestamp is less than `end_at`. Optional.
+        #
+        # @deprecated This field is ignored when creating or updating sinks.
+        def end_at= _new_end_at
+          warn "[DEPRECATION] end_at= is deprecated and will be ignored."
+        end
+        alias end_time= end_at=
+
+        ##
+        # An IAM identity (a service account or group) that will write exported
+        # log entries to the destination on behalf of Stackdriver Logging. You
+        # must grant this identity write-access to the destination. Consult the
+        # destination service's documentation to determine the exact role that
+        # must be granted.
+        def writer_identity
+          @grpc.writer_identity
+        end
+
+        ##
+        # Updates the logs-based sink.
+        #
+        # @param [Boolean] unique_writer_identity Whether the sink will have a
+        #    dedicated service account returned in the sink's `writer_identity`.
+        #    Set this field to be true to export logs from one project to a
+        #    different project. This field is ignored for non-project sinks
+        #    (e.g. organization sinks) because those sinks are required to have
+        #    dedicated service accounts. Optional.
+        #
+        # @example
+        #   require "google/cloud/logging"
+        #
+        #   logging = Google::Cloud::Logging.new
+        #   sink = logging.sink "severe_errors"
+        #   sink.filter = "logName:syslog AND severity>=ERROR"
+        #   sink.save
+        #
+        def save unique_writer_identity: nil
+          ensure_service!
+          @grpc = service.update_sink \
+            name, destination, filter,
+            unique_writer_identity: unique_writer_identity
+        end
+
+        ##
+        # Reloads the logs-based sink with current data from the Logging
+        # service.
+        def reload!
+          ensure_service!
+          @grpc = service.get_sink name
+        end
+        alias refresh! reload!
+
+        ##
+        # Permanently deletes the logs-based sink.
+        #
+        # @return [Boolean] Returns `true` if the sink was deleted.
+        #
+        # @example
+        #   require "google/cloud/logging"
+        #
+        #   logging = Google::Cloud::Logging.new
+        #   sink = logging.sink "severe_errors"
+        #   sink.delete
+        #
+        def delete
+          ensure_service!
+          service.delete_sink name
+          true
+        end
+
+        ##
+        # @private New Sink from a Google::Cloud::Logging::V2::LogSink object.
+        def self.from_grpc grpc, service
+          new.tap do |f|
+            f.grpc = grpc
+            f.service = service
+          end
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          raise "Must have active connection to service" unless service
+        end
+
+        ##
+        # @private Get a Google::Protobuf::Timestamp object from a Time object.
+        def time_to_timestamp time
+          return nil if time.nil?
+          # Make sure we have a Time object
+          return nil unless time.respond_to? :to_time
+          time = time.to_time
+          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
+        end
+
+        ##
+        # @private Get a Time object from a Google::Protobuf::Timestamp object.
+        def timestamp_to_time timestamp
+          return nil if timestamp.nil?
+          # Time.at takes microseconds, so convert nano seconds to microseconds
+          Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
+        end
+      end
+    end
+  end
+end